DEV Community: Ionx Solutions

Safely Handling Malware Samples for API Testing

Ionx Solutions — Thu, 30 Apr 2026 12:15:56 +0000

This is a developer's guide to safely submitting malware samples to Verisys Antivirus API.

Malware samples can be a useful tool when testing an antivirus API - but handling live malware is genuinely dangerous. This guide covers everything you need to know: from safe test files for most developers, to a purpose-built, hardened environment for those who need the real thing.

Who This Guide is For

If you're building a file upload feature and want to verify that your integration with Verisys Antivirus API works correctly before going to production, you've come to the right place. But before we go any further, we need to split this audience in two.

The vast majority of developers testing an antivirus integration don't need live malware at all. The EICAR test file - a purpose-built, universally recognised test vector - is all you need to validate that your API calls are correctly wired up, that malware detections are returned and handled properly, and that your application behaves as expected when a threat is found. If that's you, jump straight to Start here: the EICAR test file.
A small number of developers (such as those working in dedicated security roles, or researchers building specialised tooling) may legitimately need to work with real samples. The rest of this guide is written for you. But be warned: this is not a casual undertaking - here be dragons! Handling live malware without proper precautions can compromise your machine, your network, and potentially your colleagues' machines too.

NOTE: This guide is specifically about safely uploading malware samples to an antivirus API for detection testing. It is not a guide to malware analysis or reverse engineering. You will not be executing (or "detonating"), debugging, or decompiling anything. That distinction meaningfully reduces the risk profile, as we'll explain below.

Start Here: The EICAR Test File

The EICAR Anti-Malware Test File is the industry-standard way to test antivirus integrations without handling real malware. It was created in the 90s as a collaboration between antivirus vendors, and virtually every antivirus engine recognises it as a test threat and returns a detection.

It's a completely harmless plain text file containing exactly this string:

X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*

Despite containing no actual malicious code, every major antivirus engine flags it. It's entirely harmless - your machine is not at risk. But it lets you exercise the full detection path in your integration with confidence.

You can download it directly from EICAR's website, or you can simply create the file yourself by copying the string above into a new file and save it with any extension (.com, .txt, or anything else).

To scan it with Verisys Antivirus API:

curl https://eu1.api.av.ionxsolutions.com/v1/malware/scan/file \
    --header 'X-API-Key: YOUR_API_KEY' \
    --form file=@/path/to/eicar.com

You should receive a response something like this:

{
  "id": "275d2ead-abb2-4764-a4d4-0797d1a2193d",
  "scan_type": "malware",
  "status": "threat",
  "content_length": 68,
  "content_type": "text/plain",
  "signals": ["Virus:EICAR_Test_File"],
  "metadata": {
    "hash_sha1": "3395856ce81f2b7382dee72602f798b642f14140",
    "hash_sha256": "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"
  }
}

A status of threat and the signal Virus:EICAR_Test_File tells you everything is working as intended. If you see this, your integration is correctly passing files to the API and receiving threat detections back. That's all you need to scan real malware too.

NOTE: Don't have an API key yet? Start a free trial of Verisys Antivirus API - no credit card required. You'll be scanning files in no time!

You can also scan the EICAR file by URL, without downloading it at all:

curl https://eu1.api.av.ionxsolutions.com/v1/malware/scan/url \
    --header 'X-API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{"file_url": "https://secure.eicar.org/eicar.com.txt"}'

If you're satisfied that EICAR meets your needs, you're done - and your machine is safer for it. The rest of this guide covers the small number of scenarios where real malware samples are necessary - only proceed if you have a clear, justified need to work with real malware samples.

Why You Might Need Real Malware Samples

For the vast majority of file upload integrations, EICAR is sufficient. But there are legitimate reasons a developer might need to work with real samples:

Detection rate validation: verifying that the API correctly detects a specific malware family or strain relevant to your threat model.
Edge case testing: testing API behaviour with unusual file types, packed executables, or polyglot files that embed malicious payloads.
QA pipeline stress testing: building a comprehensive test corpus that exercises multiple threat categories - ransomware, trojans, infostealers, and so on - to validate detection across the board.
Security research tooling: building infrastructure that processes, classifies, or routes malware samples as part of a broader security product.

If any of these apply to you, continue reading - but proceed cautiously.

The Dangers of Handling Live Malware

Let's be direct about what you're dealing with. Unlike the EICAR file, real malware is not inert - it is specifically designed to execute, propagate, and cause harm. Even if your intention is only to upload a file to an API for scanning, the risks are real:

Accidental execution: Double-clicking, previewing, or opening a file in the wrong application can trigger execution. Modern operating systems have many automatic file-handling behaviours - thumbnail generation, indexing, preview pane rendering - that can invoke malicious payloads without any deliberate action on your part.
Network propagation: Some malware families - worms in particular - are designed to scan the local network and spread to reachable hosts automatically upon execution. If your machine is connected to a shared network, a single accidental execution can cascade rapidly.
Lateral movement: Many modern malware strains include persistence mechanisms, credential harvesting, and lateral movement capabilities. If a sample executes on a machine with access to shared drives, password managers, or cloud sync folders, the damage can extend far beyond the original machine.
Legal and policy risk: Depending on your jurisdiction, possessing certain malware samples may carry legal implications. Always ensure you're operating within the law and within your organisation's acceptable use policies.
Human error: This is, honestly, the most common risk. Experienced security researchers have accidentally executed malware despite knowing better. Fatigue, distraction, and familiarity all contribute. A robust environment doesn't just protect against malware - it protects against you!

The Upload-Only Advantage

Here's the key insight that most general malware handling guides miss: if your goal is only to upload a sample to an API, your risk profile is dramatically lower than a malware analyst's.

A malware analyst needs to execute samples, observe runtime behaviour, capture network traffic, and interact with live processes. That requires a fundamentally different (and far more complex) containment strategy.

You don't need any of that. Your workflow is:

Download the sample (remember that by convention, samples are compressed and password-protected)
Extract the sample in an isolated environment
Upload the file to the API via curl
Observe the response
Delete the sample

You never execute anything. This means the primary risk is accidental execution, which a combination of isolation, careful tooling choices, and good habits can mitigate effectively.

Architecture Overview

The environment we'll build has two components: a dedicated physical host running Linux, and a sandbox virtual machine running inside it. The key design principle is a clean separation of responsibilities.

The host is responsible for downloading compressed, password-protected malware archives from the internet. It stores them in /malware-archives, a bind-mounted directory with noexec and nosuid flags. The host never extracts or uploads these encrypted archives - it only ever downloads them to disk - so the risk of accidental execution on the host is greatly reduced.

The sandbox VM is responsible for extracting archives and uploading the resulting files (typically binaries) to Verisys Antivirus API. It can see the host's /malware-archives as a read-only virtiofs mount - it can read archives, but cannot modify or add to them. Extracted binaries are stored in /malware-binaries, a tmpfs RAM disk inside the sandbox with noexec flags. Crucially, the sandbox VM's network access is permanently and significantly locked down: it can make outbound TCP/443 connections to exactly one IP address - your chosen Verisys Antivirus API endpoint - and nothing else. It cannot reach the internet, your local network, or any other host.

This separation ensures that the two critical risk factors - extracted malware binaries and internet access - never coexist in the same environment. The host retains internet access, but never encounters the extracted binaries; the sandbox VM holds the malware binaries but has no meaningful network connectivity.

The sandbox VM is also intended to be ephemeral; that is, temporary in nature. Every time the malware upload workflow is required, the sandbox VM is restored from a clean-state snapshot, and is then discarded afterwards. This means that malware binaries will only live for as long as needed, and even then, they will only exist on a RAM disk inside a disposable virtual machine.

What You'll Need

To follow this guide, you will need:

A dedicated physical host, separate from your day-to-day machine. An old laptop or desktop works fine. Running a Linux host OS means that most Windows-targeted malware will not execute even if it somehow escapes its VM - it simply has no runtime to attach to
At least 4GB RAM on the host (we'll allocate just 2GB for the sandbox VM OS)
At least 40GB disk on the host (we'll allocate 16GB for the sandbox VM disk)
Hardware virtualisation support (Intel VT-x or AMD-V) - verified during host setup

Setting Up the Host

Use a minimal, up-to-date Linux distribution for your host - Ubuntu Server LTS or Debian are good choices, and indeed we used Ubuntu Server 24.04 LTS here for this guide. There is no need to install a desktop environment, as a console is enough for our needs - this also helps reduce the attack surface. During installation you will be prompted to enter a username for a non-root account - in this guide we've used ops as that user.

Once the host OS is installed, install KVM/QEMU and the management tools you'll need:

sudo apt update && sudo apt install -y qemu-kvm libvirt-daemon-system \
    libvirt-clients bridge-utils virtinst dnsmasq

Importantly, verify that the host hardware supports virtualisation:

# Verify hardware virtualisation support (output must be > 0)
egrep -c '(vmx|svm)' /proc/cpuinfo

Download an ISO for the sandbox VM's guest OS - just like our host, we'll stick with Ubuntu Server LTS:

# Create the directory for ISOs
sudo mkdir -p /var/lib/libvirt/images/iso

# Download Ubuntu Server LTS
sudo wget https://releases.ubuntu.com/24.04/ubuntu-24.04.4-live-server-amd64.iso \
    -O /var/lib/libvirt/images/iso/ubuntu-24.04-server.iso

Creating the Sandbox Virtual Network

The sandbox VM needs a dedicated virtual network, isolated from your main network. libvirt will NAT the VM's traffic through the host - in a later step, we'll use iptables to lock down exactly what the VM can actually reach.

Create a network definition file for a libvirt network bridge named virbr-sandbox:

cat > ~/sandbox-net.xml << 'EOF'
<network>
  <name>sandbox-net</name>
  <forward mode='nat'/>
  <bridge name='virbr-sandbox' stp='on' delay='0'/>
  <ip address='192.168.100.1' netmask='255.255.255.0'>
    <dhcp>
      <host mac='52:54:00:10:24:24' name='sandbox' ip='192.168.100.10'/>
      <range start='192.168.100.100' end='192.168.100.150'/>
    </dhcp>
  </ip>
</network>
EOF

The DHCP entry with a fixed MAC address (52:54:00:10:24:24) ensures the sandbox VM always gets the same IP (192.168.100.10). We'll use this same MAC when creating the sandbox VM, and the fixed IP is what we'll later target with iptables rules to lock down network access.

Define, start, and persist the virtual network:

# Define the network from the XML file
virsh net-define ~/sandbox-net.xml

# Start the network
virsh net-start sandbox-net

# Mark it to autostart with libvirtd
virsh net-autostart sandbox-net

# Confirm it is active
virsh net-list --all

Setting Up Shared Directories

The host needs a directory to hold compressed, encrypted malware archives, and the sandbox VM needs a read-only view of that same directory. We use bind mounts to create both - one for host use, one specifically for sharing into the VM.

# The backing directory - this is where archives actually live on the host disk
# Our non-root user is `ops` - replace with your own non-root user if required
sudo mkdir -p /var/lib/libvirt/shared/malware-archives
sudo chown ops:ops /var/lib/libvirt/shared/malware-archives
sudo chmod 0755 /var/lib/libvirt/shared/malware-archives

# A hardened bind mount for host usage - noexec, nosuid, nodev
sudo mkdir -p /malware-archives
sudo mount --bind -o noexec,nodev,nosuid \
    /var/lib/libvirt/shared/malware-archives /malware-archives

# A separate read-only bind mount to share into the sandbox VM via virtiofs
sudo mkdir -p /var/lib/libvirt/shared/malware-archives-ro
sudo mount --bind -o ro,nodev,nosuid,noexec \
    /var/lib/libvirt/shared/malware-archives \
    /var/lib/libvirt/shared/malware-archives-ro

Make both mounts persistent by adding them to /etc/fstab:

echo "/var/lib/libvirt/shared/malware-archives /malware-archives \
    none bind,noexec,nodev,nosuid 0 0" | sudo tee -a /etc/fstab

echo "/var/lib/libvirt/shared/malware-archives \
    /var/lib/libvirt/shared/malware-archives-ro \
    none bind,ro,nodev,nosuid,noexec 0 0" | sudo tee -a /etc/fstab

Verify both mounts are in place:

mount | grep malware

You should see output something like this:

/dev/mapper/ubuntu--vg-ubuntu--lv on /malware-archives type ext4 (rw,nosuid,nodev,noexec,relatime)
/dev/mapper/ubuntu--vg-ubuntu--lv on /var/lib/libvirt/shared/malware-archives-ro type ext4 (ro,nosuid,nodev,noexec,relatime)

The reason for two separate mounts (rather than sharing the backing directory directly) is defence in depth: the host uses /malware-archives for its own operations; the sandbox VM receives only the dedicated read-only path. libvirt's virtiofs shares a directory from the host into the guest - by pointing it at the read-only bind mount rather than the live backing directory, we get kernel-level enforcement of the read-only constraint inside the VM, not just filesystem permissions.

Creating the Sandbox VM

With the network and shared directories in place, we are now ready to create the sandbox VM. We pass the read-only malware-archives directory in at creation time using a virtiofs filesystem share:

# Create the VM disk image
sudo qemu-img create -f qcow2 /var/lib/libvirt/images/sandbox.qcow2 16G

# Create the VM and boot the Ubuntu installer
sudo virt-install \
    --connect qemu:///system \
    --name sandbox \
    --vcpus 4 \
    --memory 2048 \
    --network network=sandbox-net,mac=52:54:00:10:24:24,model=virtio \
    --graphics=none \
    --disk path=/var/lib/libvirt/images/sandbox.qcow2,format=qcow2,bus=virtio \
    --filesystem source=/var/lib/libvirt/shared/malware-archives-ro,target=malware-archives,accessmode=passthrough,driver.type=virtiofs \
    --location /var/lib/libvirt/images/iso/ubuntu-24.04-server.iso,kernel=casper/vmlinuz,initrd=casper/initrd \
    --os-variant ubuntu24.04 \
    --console pty,target_type=serial \
    --memorybacking access.mode=shared,source.type=memfd \
    --extra-args="console=ttyS0,115200n8"

A few flags worth noting:

--network mac=52:54:00:10:24:24: matches the fixed DHCP entry in the network definition, ensuring the VM always gets IP 192.168.100.10.
--filesystem driver.type=virtiofs: virtiofs is a high-performance virtio-based filesystem protocol for sharing host directories into guests. It requires --memorybacking access.mode=shared,source.type=memfd, which enables the shared memory backend virtiofs needs.
--graphics=none: no VNC or SPICE surface is created; there is no clipboard or drag-and-drop channel to act as an escape vector.
--location: if using a different Linux distribution other than Ubuntu Server LTS, you will need to change this value accordingly

Follow the on-screen prompts to install Ubuntu Server in the guest VM. Accept defaults where possible - a minimal installation is fine. As with the host OS, during installation you will be prompted to enter a username for a non-root account - in this guide we've used ops as that user, just as we did for the host OS.

Configuring the Sandbox VM

Once the guest OS is installed, the VM should reboot into the fresh system. If you're no longer still in a console prompt in the sandbox, reconnect from the host:

# Connect to the sandbox VM console
sudo virsh --connect qemu:///system console sandbox

Install the few tools you'll need for working with malware archives:

sudo apt install -y unzip p7zip-full jq

unzip and p7zip-full handle the compressed archives that malware repositories distribute samples in. jq is useful for pretty-printing the JSON responses from the Verisys API.

Next, configure the mount points for the shared malware archives and the extraction RAM disk:

# Mount point for the read-only virtiofs share from the host
sudo mkdir -p /malware-archives
echo "malware-archives  /malware-archives  virtiofs  ro,nodev,nosuid,noexec,_netdev 0 0" \
    | sudo tee -a /etc/fstab

# Mount point for a 1GB noexec tmpfs RAM disk - extracted binaries live here
sudo mkdir -p /malware-binaries
echo "malware-binaries  /malware-binaries  tmpfs  rw,noexec,nodev,nosuid,size=1G 0 0" \
    | sudo tee -a /etc/fstab

The _netdev flag on the virtiofs mount tells the init system to wait for the virtio network backend to be ready before mounting - without it, the mount may fail on boot. The tmpfs size of 1GB is a sensible ceiling for a working extraction area, but do adjust it if you expect to need more space (and you have the RAM, of course!).

Reboot the sandbox VM to apply the fstab entries:

sudo reboot now

Once it's back up, verify both mounts are present:

mount | grep malware

You should see:

malware-binaries on /malware-binaries type tmpfs (rw,nosuid,nodev,noexec,relatime,size=1048576k,inode64)
malware-archives on /malware-archives type virtiofs (ro,nosuid,nodev,noexec,relatime,_netdev)

With both mounts correctly in place, shut the VM down cleanly and take a snapshot - this is the clean baseline you'll revert to at the start of every malware upload session:

# Still connected to the console of the sandbox VM, shut it down
sudo shutdown -P now

Then once you're back at the host prompt:

virsh snapshot-create-as sandbox --name "clean"

This snapshot captures the configured, clean state of the VM - mounts, installed tools, but no malware. Every session starts by reverting to this snapshot, which guarantees a completely clean environment regardless of what happened in the previous session.

To start a new sandbox VM session:

virsh shutdown sandbox
virsh snapshot-revert sandbox --snapshotname "clean"
virsh start sandbox

# Connect to the VM console
sudo virsh --connect qemu:///system console sandbox

Locking Down the Network

The last piece of the setup - and arguably the most important - is restricting what the sandbox VM can do with its network connection. At this point, the VM still has full internet access via the NAT network, so we need to reduce that to a single outbound destination.

First, save a backup of your current iptables rules so you can restore them if anything goes wrong:

sudo iptables-save | tee ~/iptables_without_sandbox.conf

Resolve the IP address of your chosen Verisys Antivirus API regional endpoint. We'll use eu1 here - swap it for gb1, us1, or ap1 depending on your region:

dig +short eu1.api.av.ionxsolutions.com

This gives you the endpoint IP - 5.75.138.88 for eu1 at time of writing. Note it down, as you'll use it in the rules below.

Region	Endpoint
EU (Germany)	`eu1.api.av.ionxsolutions.com`
UK	`gb1.api.av.ionxsolutions.com`
US	`us1.api.av.ionxsolutions.com`
Asia Pacific (Singapore)	`ap1.api.av.ionxsolutions.com`

Now create a dedicated iptables chain for the sandbox and populate it with rules:

# Create the chain (or flush it if it already exists from a previous run)
sudo iptables -N SANDBOX_LOCKDOWN 2>/dev/null || iptables -F SANDBOX_LOCKDOWN

# Allow return traffic for connections the VM has already established
sudo iptables -A SANDBOX_LOCKDOWN -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# Allow outbound HTTPS to the Verisys Antivirus API endpoint only
# Replace 5.75.138.88 with the IP you resolved above if using a different region
sudo iptables -A SANDBOX_LOCKDOWN -p tcp -d 5.75.138.88 --dport 443 -j ACCEPT

# Log anything that doesn't match the above rules, then drop it
sudo iptables -A SANDBOX_LOCKDOWN -j LOG --log-prefix "SANDBOX DROP: "
sudo iptables -A SANDBOX_LOCKDOWN -j DROP

# Attach the chain to the FORWARD table for traffic originating from the sandbox bridge
# The -C check avoids inserting a duplicate rule if this is re-run
sudo iptables -C FORWARD -i virbr-sandbox -j SANDBOX_LOCKDOWN 2>/dev/null || \
    sudo iptables -I FORWARD 1 -i virbr-sandbox -j SANDBOX_LOCKDOWN

Persist the rules across reboots:

sudo netfilter-persistent save

The chain is attached using -i virbr-sandbox - matching on the bridge interface name rather than a source IP range. This means the rules apply to all traffic entering the host's FORWARD path from the sandbox bridge, regardless of what IP the guest happens to have. It's slightly more robust than source IP matching.

The LOG rule before the final DROP means that any traffic the VM attempts to send that isn't to the Verisys endpoint will appear in your system logs (/var/log/syslog or via journalctl -k), prefixed with SANDBOX DROP:. This is useful for diagnosing unexpected behaviour.

NOTE: While we try hard not to, the IP addresses of Verisys API endpoints could change over time. If you need to update the rules to change the IP, update the SANDBOX_LOCKDOWN chain: flush it with sudo iptables -F SANDBOX_LOCKDOWN, re-add the rules above with the new IP, and then run sudo netfilter-persistent save to persist the changes.

Sourcing Malware Samples

With your environment ready, you now need malware samples to work with. The following are well-regarded, legitimate sources used by security researchers worldwide, and all provide samples in password-protected archives to prevent accidental execution. Remember that downloads will happen only on the host - the sandbox VM's network is locked down and can't reach them. Do not extract downloaded malware sample archives on the host system under any circumstances.

WARNING: Downloading malware samples is a deliberate, professional act. Only download what you actually need. Keep /malware-archives tidy - delete archives you're no longer working with. The directory is noexec, nosuid, and nodev, so archives cannot execute directly on the host; but good housekeeping is still important. And for extraction and upload, always, always only work within your isolated sandbox environment as described above.

MalwareBazaar

MalwareBazaar is run by abuse.ch, a Swiss non-profit security research organisation. It maintains a large, searchable database of malware samples contributed by the security community, browsable by malware family, file type, tag, and signature. Samples are distributed as password-protected ZIP archives (password: infected). It's one of the most reputable and widely used sources in the industry.

Use the MalwareBazaar API to download a sample by its SHA-256 hash - find this on the sample's page on the MalwareBazaar website:

As well as a website, MalwareBazaar also provides an API for programmatic access, which is useful if you're building a test corpus. Note that you'll need to create an account before you can use the API (it's free to use under their free use principles) For example, to download a sample by its SHA-256 hash (such hashes can be found on the website):

# On the host
hash="<YOUR_SHA256_HERE>"
wget -O /malware-archives/${hash}.zip \
    "https://mb-api.abuse.ch/api/v1/" \
    --header "Auth-Key: YOUR_API_AUTH_KEY_HERE" \
    --post-data="query=get_file&sha256_hash=${hash}"

TheZoo

TheZoo is a curated GitHub repository of live malware samples, explicitly intended for security researchers. Samples are organised by family name and stored as password-protected ZIP archives (password: infected).

# On the host, download a sample directly from the GitHub repository
family="<MALWARE_FAMILY_NAME>"
wget -O /malware-archives/${family}.zip \
    https://github.com/ytisf/theZoo/raw/refs/heads/master/malware/Binaries/${family}/${family}.zip

vx-underground

vx-underground maintains one of the largest freely available malware archives on the internet, covering a wide range of families and historical strains. Samples are stored as password-protected 7z archives (password: infected).

To obtain a sample's URL for download, navigate through the website to your chosen malware binary, and copy the download link. You can then use wget or curl to download the sample (note that VX Underground download links are only valid for 1 hour):

# On the host
wget -O /malware-archives/sample.zip "https://<vx-underground-sample-url>"

End-to-End Workflow

Now everything is setup, let's walk through a complete workflow example from start to finish. We'll download a real malware sample (Nivdort, a Windows data-stealing trojan dating back to 2016) from the TheZoo repository, scan it with Verisys Antivirus API, and interpret the result.

Step 1 - Download the sample archive on the host:
Download a sample of the Nivdort trojan:

# On the host
wget -O /malware-archives/Nivdort.zip \
    https://github.com/ytisf/theZoo/raw/refs/heads/master/malware/Binaries/Nivdort/Nivdort.zip

Step 2 - Start a clean instance of the sandbox VM:
Start a nice, clean sandbox instance to work in:

# On the host - revert to the clean snapshot and start afresh
virsh shutdown sandbox 2>/dev/null
virsh snapshot-revert sandbox --snapshotname "clean"
virsh start sandbox

# Connect to the VM console and log in when prompted
sudo virsh --connect qemu:///system console sandbox

Step 3 - Extract the archive inside the sandbox VM:
The archive is visible inside the sandbox VM at /malware-archives/Nivdort.zip via the read-only virtiofs mount. Extract it to the noexec RAM disk, entering password infected when prompted:

# Inside the sandbox VM
unzip /malware-archives/Nivdort.zip -d /malware-binaries

Note what's happening here: the archive comes in to the sandbox VM through a read-only mount (the sandbox can't modify or add to /malware-archives), and the extracted binary lands in a tmpfs RAM disk with noexec set at the mount level - the kernel will refuse to execute binaries directly from /malware-binaries, regardless of the file's permission bits.

Step 4 - Upload to Verisys Antivirus API:
Now we'll upload the sample (change endpoint eu1.api.av.ionxsolutions.com if you're using a different one):

# Inside the sandbox VM
curl https://eu1.api.av.ionxsolutions.com/v1/malware/scan/file \
    --header 'X-API-Key: YOUR_API_KEY' \
    --form file=@/malware-binaries/sample.exe | jq

This is the only outbound network connection the VM is permitted to make - TCP/443 to 5.75.138.88. Any other network traffic from the VM is logged and dropped by the SANDBOX_LOCKDOWN chain.

NOTE: Don't have an API key yet? Start a free trial of Verisys Antivirus API - no credit card required. You'll be scanning malware in minutes!

Interpreting the API Response

Verisys Antivirus API returns a consistent JSON structure for every scan. For a detected threat, like the Nivdort sample above, you'll see something like this:

{
  "id": "9f9590f6-1be7-4764-8e2e-233133aa4f13",
  "scan_type": "malware",
  "status": "threat",
  "content_length": 892416,
  "content_type": "application/vnd.microsoft.portable-executable",
  "signals": [
    "TrojanSpy:Win32/Nivdort.DU"
  ],
  "metadata": {
    "hash_sha1": "5b3e04f8208d3de912413efce27372255d6b3fe9",
    "hash_sha256": "eea059174127860154f4dce1a7d8995a9a5056febf73819d63ddadb522ed6c8f"
  }
}

And for a clean file you'll see something like this:

{
  "id": "8f1c4b2d-3a9e-4f7c-b6d1-2e5a8c0f9b3e",
  "scan_type": "malware",
  "status": "clean",
  "content_length": 12288,
  "content_type": "application/pdf",
  "signals": [],
  "metadata": {
    "hash_sha1": "adc83b19e793491b1c6ea0fd8b46cd9f32e592fc",
    "hash_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }
}

Key fields to pay attention to:

Field	Description
`status`	`clean`, `threat` (or `error` if something went wrong)
`signals`	Names of identified threats (empty array if clean)
`content_type`	The actual detected file type, determined by binary signature analysis - not the filename or client-supplied `Content-Type` header
`metadata.hash_sha1`	SHA-1 hash of the scanned file
`metadata.hash_sha256`	SHA-256 hash of the scanned file - useful for cross-referencing against threat intelligence databases like MalwareBazaar

The content_type field is worth highlighting: Verisys Antivirus API detects the real file type from the binary signature, independently of the file extension. A Windows executable renamed to invoice.pdf is still identified as a Windows binary - a critical defence against file type spoofing in production upload pipelines.

SHA-1/SHA-256 hashes (metadata.hash_sha*) are particularly useful when working with known samples, as they provide a unique, verifiable file signature that can be cross-referenced against threat intelligence databases.

Closing Thoughts

The environment described in this guide is deliberately designed around a clean separation of concerns: the host handles internet access and storage of password-protected archives; the sandbox handles extraction and upload to Verisys Antivirus API. Neither environment does both. This means the two most dangerous moments in the workflow - open internet access and live, extracted binaries - never coincide in the same place.

The key protections working together are:

A dedicated physical host running Linux, so Windows-targeted malware has no runtime to attach to, even if it somehow broke out of the sandbox onto the host.
noexec bind mounts on the host, so archives can't execute even if somehow triggered.
A read-only virtiofs share into the sandbox VM, so the sandbox can read archives but cannot modify the source directory.
A noexec tmpfs RAM disk for extracted binaries inside the sandbox VM, enforced at the mount level by the kernel.
A permanent iptables lockdown allowing only TCP/443 to one specific Verisys API IP - the sandbox VM cannot reach the internet, your local network, or any C2 (Command and Control) infrastructure.
Snapshot-based session management, so every sandbox session begins from a guaranteed clean state.

For the majority of developers, the answer remains the same as it was at the beginning of this guide: use EICAR, validate your integration, and ship with confidence. But for those who need more, this architecture provides a secure, tightly controlled environment for safely acquiring and processing real-world malware samples.

Learn more about Verisys Antivirus API, our language-agnostic antivirus REST API that makes it simple to add malware scanning to any application.

How to Handle File Uploads with Node.js and Express - Multer Edition

Ionx Solutions — Mon, 12 May 2025 13:48:14 +0000

A variation on our earlier post 'How to Handle File Uploads with Node.js and Express' (which used express-fileupload). This time, we'll use Multer, a powerful middleware for handling file uploads with Node.js and Express.

NOTE: In order to follow this tutorial, you will need the following:

Node.js installed on your machine

Basic knowledge of JavaScript and Express

A text editor or lightweight IDE such as Visual Studio Code

Why Choose Multer?

In our previous guide, we showed how easy it is to handle file uploads using express-fileupload. Multer brings additional flexibility and control:

Disk & Memory Storage Engines: Choose between saving files directly to disk or keeping them in memory for immediate processing. Third parties even offer pluggable engines for cloud storage.
File Filtering: Accept or reject files based on MIME type or custom criteria.
Limits & Validation: Set size limits, file count limits, and other constraints to protect your server.
Streaming Support: Process large uploads efficiently without consuming excessive RAM.

With these features, Multer is ideal for both simple and advanced upload workflows.

Project Scaffold/Setup

The first step is to create and initialize a new Express project.

Open a terminal or command prompt, navigate to the directory where you want to store the project, and run the following commands:

npx express-generator --view=pug myapp
cd myapp
npm install

The generated app should have the following directory structure:

.
├── app.js
├── package.json
├── bin
│   └── www
├── package.json
├── public
│   ├── images
│   ├── javascripts
│   └── stylesheets
│       └── style.css
├── routes
│   ├── index.js
│   └── users.js
├── views
│   ├── error.pug
│   └── index.pug
│   └── layout.pug

Before we move on, make sure you are able to run the app and view it in a browser

On MacOS, Linux or Git Bash on Windows, run the app with this command:

DEBUG=myapp:* npm start

Or use this command for Windows:

set DEBUG=myapp:* & npm start

Or this command for Windows Powershell:

$env:DEBUG='myapp:*'; npm start

Then navigate to http://localhost:3000 in your browser to access the app - you should see a page that looks like this:

Go ahead and stop the server by hitting CTRL-C at the command prompt
Next we’re going to add a few NPM packages:
- We'll add a package to deal with file uploads easier. There are several popular choices here, including Formidable and express-fileupload - but for this tutorial, we'll use Multer.
- For this tutorial, we're going to scan the file for malware using Verisys Antivirus API, and so we'll add a package to make it easier to make external HTTP requests. Popular choices include Axios and node-fetch - for this article, we'll use node-fetch.
- We'll also add the form-data package to allow working with multipart form data, which is used to perform file uploads.

npm install multer@^1.4.5-lts.2
npm install node-fetch@^2.7.0
npm install form-data

Frontend

Before we write JavaScript code to handle the file upload, let’s create a simple web page that lets the end user select a file to upload.

Update the content of myapp/views/index.pug to contain the following:

extends layout

block content

  h2 File Upload

  <form action="/upload" method="POST" enctype="multipart/form-data">
    <input type="file" name="file" required>
    <button type="submit">Upload File</button>
  </form>

  br

  h2 Malware Scan

  <form action="/scan" method="POST" enctype="multipart/form-data">
    <input type="file" name="file" required>
    <button type="submit">Scan File</button>
  </form>

We’ve added two forms to the page. When the File Upload form is submitted, the file will be sent to a route at /upload - the next step is to create the route and route handler. We’ll get back to the Malware Scan form later.

Backend - Simple File Upload

Now we’re going to add a route handler to process uploaded files, and then we’ll wire up the handler to the /upload route.

Create file myapp/routes/upload.js with the following content:

const express = require('express');
const multer  = require('multer');
const router = express.Router();

const storage = multer.diskStorage({
  // Configure file uploads with maximum file size 10MB
  limits: { fileSize: 10 * 1024 * 1024 }
});
const fileUpload = multer({ storage: storage });

router.post('/', fileUpload.single('file'), async function(req, res, next) {
  // Was a file submitted?
  if (!req.file) {
    return res.status(422).send('No files were uploaded');
  }

  const uploadedFile = req.file;

  // Print information about the file to the console
  console.log(`Original File Name: ${uploadedFile.originalname}`);
  console.log(`Uploaded File Name: ${uploadedFile.filename}`);
  console.log(`Uploaded File Path: ${uploadedFile.path}`);
  console.log(`File Size: ${uploadedFile.size}`);
  console.log(`File Mime Type: ${uploadedFile.mimetype}`);

  // Return a web page showing information about the file
  res.send(`File Name: ${uploadedFile.originalname}<br>
  File Size: ${uploadedFile.size}<br>
  File Mime Type: ${uploadedFile.mimetype}`);
});

module.exports = router;

This simple handler will both print information about the file to the console and return it in as a web page, so you can see what has been received by your router.

Next, we need to wire up this code to the /upload route.

Update the content of myapp/app.js to contain the following:

var createError = require('http-errors');
var express = require('express');
var path = require('path');
var cookieParser = require('cookie-parser');
var logger = require('morgan');

var indexRouter = require('./routes/index');
var usersRouter = require('./routes/users');
var uploadRouter = require('./routes/upload');

var app = express();

// view engine setup
app.set('views', path.join(__dirname, 'views'));
app.set('view engine', 'pug');

app.use(logger('dev'));
app.use(express.json());
app.use(express.urlencoded({ extended: false }));
app.use(cookieParser());
app.use(express.static(path.join(__dirname, 'public')));

app.use('/', indexRouter);
app.use('/users', usersRouter);
app.use('/upload', uploadRouter);

// catch 404 and forward to error handler
app.use(function(req, res, next) {
  next(createError(404));
});

// error handler
app.use(function(err, req, res, next) {
  // set locals, only providing error in development
  res.locals.message = err.message;
  res.locals.error = req.app.get('env') === 'development' ? err : {};

  // render the error page
  res.status(err.status || 500);
  res.render('error');
});

module.exports = app;

We’ve only added 2 lines to the default code provided by the Express generator (lines #9 and #25 above), telling Express to use our upload.js router for the /upload route.

Testing File Uploads

Now we’re ready to test it! 🎉

Begin by starting your Node.js server using the same command as before
Open your browser and navigate to http://localhost:3000 - you should see a page that looks like this:

Use the File Upload form, Browse to select a file and press the Upload File button

If everything was set up correctly, you should see information about the file being printed to the console, and also shown in a web page.

Backend - Malware Scanning

Now we’re going to add a route handler to perform a virus scan on uploaded files, and then we’ll wire up the handler to the /scan route.

Create file myapp/routes/scan.js with the following content:

const express = require('express');
const fetch = require('node-fetch');
const multer  = require('multer');
const FormData = require('form-data'); 
const fs = require('fs');
const router = express.Router();

const storage = multer.diskStorage({
  // Configure file uploads with maximum file size 10MB
  limits: { fileSize: 10 * 1024 * 1024 }
});
const fileUpload = multer({ storage: storage });

router.post('/', fileUpload.single('file'), async function(req, res, next) {
  // Was a file submitted?
  if (!req.file) {
    return res.status(422).send('No files were uploaded');
  }

  const uploadedFile = req.file;

  // Print information about the file to the console
  console.log(`Original File Name: ${uploadedFile.originalname}`);
  console.log(`Uploaded File Name: ${uploadedFile.filename}`);
  console.log(`Uploaded File Path: ${uploadedFile.path}`);
  console.log(`File Size: ${uploadedFile.size}`);
  console.log(`File Mime Type: ${uploadedFile.mimetype}`);

  // Scan the file for malware using the Verisys Antivirus API - the same concepts can be
  // used to work with the uploaded file in different ways
  try {
    // Attach the uploaded file to a FormData instance
    var form = new FormData();
    form.append('file', fs.createReadStream(uploadedFile.path), uploadedFile.originalname);

    const headers = {
      'X-API-Key': '<YOUR API KEY HERE>',
      'Accept': '*/*'
    };

    // Send the file to the Verisys Antivirus API
    const response = await fetch('https://eu1.api.av.ionxsolutions.com/v1/malware/scan/file', {
      method: "POST",
      body: form,
      headers: headers
    });

    // Did we get a response from the API?
    if (response.ok) {
      const result = await response.json();

      // Did the file contain a virus/malware?
      if (result.status === 'clean') {
        return res.send('Uploaded file is clean!');
      } else {
        return res.status(500).send(`Uploaded file contained malware: <b>${result.signals[0]}</b>`);
      }
    } else {
      throw new Error('Unable to scan file: ' + response.statusText);
    }
  } catch (error) {
    // Delete the uploaded file
    fs.rm(uploadedFile.path, () => {});

    // Forward the error to the Express error handler
    return next(error);
  }
});

module.exports = router;

As with the /upload handler, this new /scan handler will print information about the file to the console, so you can see what has been received by your route handler. It then uploads the file to Verisys Antivirus API to scan it for malware.

NOTE:
The X-API-Key in the above code will need to be replaced with a real API key to scan files. Don't have an API key? Subscribe or start a trial now!

Next, we need to wire up this code to the /scan route.

Update the content of myapp/app.js to contain the following:

var createError = require('http-errors');
var express = require('express');
var path = require('path');
var cookieParser = require('cookie-parser');
var logger = require('morgan');

var indexRouter = require('./routes/index');
var usersRouter = require('./routes/users');
var uploadRouter = require('./routes/upload');
var scanRouter = require('./routes/scan');

var app = express();

// view engine setup
app.set('views', path.join(__dirname, 'views'));
app.set('view engine', 'pug');

app.use(logger('dev'));
app.use(express.json());
app.use(express.urlencoded({ extended: false }));
app.use(cookieParser());
app.use(express.static(path.join(__dirname, 'public')));

app.use('/', indexRouter);
app.use('/users', usersRouter);
app.use('/upload', uploadRouter);
app.use('/scan', scanRouter);

// catch 404 and forward to error handler
app.use(function(req, res, next) {
  next(createError(404));
});

// error handler
app.use(function(err, req, res, next) {
  // set locals, only providing error in development
  res.locals.message = err.message;
  res.locals.error = req.app.get('env') === 'development' ? err : {};

  // render the error page
  res.status(err.status || 500);
  res.render('error');
});

module.exports = app;

We’ve only added two lines to the previous code (lines #10 and #27 above), telling Express to use our scan.js router for the /scan route.

Testing Malware Scanning

Now we’re ready to test malware scanning! 🎉

Begin by starting your Node.js server using the same command as before
Open your browser and navigate to http://localhost:3000 - you should see a page that looks like this:

Use the Malware Scan form, Browse to select a file and press the Scan File button

If everything was set up correctly, as before you should see information about the file being printed to the console, but you should also see a response from Verisys Antivirus API:

Code for this tutorial can be found on GitHub: https://github.com/IonxSolutions/tutorial-file-uploads-express-multer

How to Handle File Uploads with Python and FastAPI

Ionx Solutions — Mon, 14 Oct 2024 11:14:52 +0000

Handling file uploads securely is a common need for modern applications, but it comes with challenges. From managing large files to ensuring that the content isn't malicious, developers must implement robust solutions. In this guide, we'll walk through how to use Python's FastAPI to handle file uploads. Plus, we'll show you how to integrate Verisys Antivirus API to scan files for malware, protecting your application and users.

NOTE: To follow this tutorial, you will need the following:

Python 3.7+ installed on your machine

Basic knowledge of Python and FastAPI

A text editor or lightweight IDE such as Visual Studio Code

Why FastAPI?

FastAPI is a modern web framework for Python that enables you to build APIs quickly. It's built on standard Python type hints, making it easier to work with and maintain. With built-in support for asynchronous request handling, it's also ideal for high-performance applications.

Combined with Verisys Antivirus API, FastAPI helps you build secure file upload endpoints, crucial for any web or mobile app handling potentially unsafe files.

Project Scaffold/Setup

The first step is to create a Python environment, ready with the libraries we will use for the FastAPI project.

Open a terminal or command prompt, and navigate to the directory where you want to store the project
Create and activate a virtual environment

Install FastAPI, Uvicorn and python-multipart:

pip install fastapi uvicorn python-multipart

For this tutorial, we'll also use the requests library to send uploaded files to Verisys Antivirus API for malware scanning:
```
pip install requests
```

Creating the FastAPI App

Let's start by setting up a simple FastAPI app that will accept file uploads. Create a file main.py with this content:

from fastapi import FastAPI, File, UploadFile
import uvicorn
import logging

logger = logging.getLogger('uvicorn.error')
logger.setLevel(logging.DEBUG)

app = FastAPI()

@app.post("/upload/")
async def upload_file(file: UploadFile = File(...)):
    content = await file.read()

    # Print information about the file to the console
    logger.debug(f"File Name: {file.filename}")
    logger.debug(f"File Size: {len(content)}")
    logger.debug(f"File MIME Type: {file.content_type}")

    # Return information about the file to the caller - note that the
    # content_type can easily be spoofed
    return {"filename": file.filename, "file_size": len(content), "file_mime_type": file.content_type}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

Starting the FastAPI App

To run the API using the Uvicorn web server, execute the following from the same folder as main.py:

uvicorn main:app --reload

The --reload flag allows the server to automatically reload as we make changes to the code, which is helpful during development.

Once Uvicorn starts, you'll see output indicating that the app is running, along with the URL where it's accessible. By default, it will run at:

http://127.0.0.1:8000

Testing the API

To test the basic file upload functionality, you can simply use curl, or you could a tool like Postman or Insomnia.

Here's an example using curl, with a file testfile.png (substitute for any file you want to upload):

curl -F "file=@testfile.png" http://127.0.0.1:8000/upload/

You should see a result similar to:

{
  "filename":"testfile.png",
  "file_size":26728,
  "file_mime_type":"image/png"
}

Integrating Verisys Antivirus API

Uploading files is a start, but ensuring that uploaded files are free of malware is critical, especially when accepting files from end users. Verisys Antivirus API allows us to scan files before processing them further.

Verisys Antivirus API is a language-agnostic REST API that allows you to easily add malware scanning to mobile apps, web apps and backend processing.

By scanning user-generated content and file uploads, Verisys Antivirus API can stop dangerous malware at the edge, before it reaches your servers, applications - or end users.

Here's how to integrate Verisys Antivirus API to scan uploaded files:

Get your Verisys API Key: Before we start, ensure you have your Verisys Antivirus API key. If you don't have one, visit Verisys Antivirus API to get started or request a trial.
Send the file to Verisys Antivirus API: Once the file has been received, send it to the Verisys API for scanning.

Update main.py with this content:

from fastapi import FastAPI, File, UploadFile
import uvicorn
import requests
import logging

VERISYS_API_URL = "https://eu1.api.av.ionxsolutions.com/v1/malware/scan/file"
API_KEY = "your_api_key"

logger = logging.getLogger('uvicorn.error')
logger.setLevel(logging.DEBUG)

app = FastAPI()

class ScanResult:
    def __init__(self, filename="", status="", content_type="", signals=None, metadata=None):
        self.filename = filename
        self.status = status
        self.content_type = content_type
        self.signals = signals if signals is not None else []
        self.metadata = metadata if metadata is not None else []

    def __repr__(self):
        return f"ScanResult(filename={self.filename},status={self.status}, content_type={self.content_type}, signals={self.signals}, metadata={self.metadata})"

def scan_file(file_content, filename):
    files = {'file': (filename, file_content)}
    headers = {'X-API-Key': API_KEY, 'Accept': '*/*'}

    response = requests.post(VERISYS_API_URL, headers=headers, files=files)

    # Was the scan successful?    
    if response.status_code == 201:
        result = response.json()

        # Print the full scan result to the console
        logger.debug(f"Scan result: {result}")

        scan_result = ScanResult(
            filename=filename,
            status=result["status"],
            content_type=result["content_type"],
            signals=result["signals"],
            metadata=result["metadata"]
        )

        return scan_result
    else:
        return ScanResult(status="error", metadata=[{"message": "Failed to scan file"}])

@app.post("/upload/")
async def upload_file(file: UploadFile = File(...)):
    content = await file.read()

    # Print information about the file to the console
    logger.debug(f"File Name: {file.filename}")
    logger.debug(f"File Size: {len(content)}")
    logger.debug(f"File MIME Type: {file.content_type}")

    # Scan file with Verisys API
    scan_result = scan_file(content, file.filename)

    # In real-life, you'd now use the scan result to determine what to do 
    # next - but here, we'll just return the scan results to the caller

    return scan_result

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

In this modified version, after the file is uploaded, it's passed to the scan_file function, which sends the file to Verisys Antivirus API for scanning. The response from Verisys is returned as part of the result, indicating whether the file is safe or malicious.

Testing the Completed API

To test the file upload and scanning functionality, as before you can use curl or another tool of your preference.

Here's an example using curl, with an EICAR Anti-Virus Test File eicar.png (substitute for any file you want to upload):

curl -F "file=@eicar.png" http://127.0.0.1:8000/upload/

Depending on the file you upload, you should see the malware scan result:

{
  "filename": "eicar.png",
  "status": "threat",
  "content_type": "text/plain",
  "signals": [
    "Virus:EICAR_Test_File"
  ],
  "metadata": {
    "hash_sha1": "3395856ce81f2b7382dee72602f798b642f14140",
    "hash_sha256": "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"
  }
}

Your upload endpoint could use the scan result to determine what to do next - for example, to prevent uploading files that contain malware.

Note that while in this example the file masqueraded as a PNG image file, Verisys Antivirus API detected that it was actually a plain text file!

Handling File Uploads Securely

Here are a couple of additional tips to ensure your file upload system is secure:

Limit File Size: Ensure you're not accepting excessively large files, which could cause performance issues or even DoS attacks. FastAPI allows you to define custom file size limits.
Restrict File Types: Only accept specific file types (e.g., PDFs, images) to prevent the upload of executable or malicious files.

{{% aside-note %}}
Checking the file extension and Content-Type header are basic steps towards securing file uploads. However, both of these can easily be spoofed.

By scanning the actual file content, Verisys Antivirus API can identify 50+ different file formats for you, while also scanning files for malware.
{{% /aside-note %}}

Checking the file extension and Content-Type header are basic steps towards securing file uploads. However, both of these can easily be spoofed.

By scanning the actual file content, Verisys Antivirus API can identify 50+ different file formats for you, while also scanning files for malware.

Why Choose Verisys Antivirus API?

Verisys Antivirus API is specifically designed to ensure secure file uploads in your applications. Here's why it's a great fit for your project:

Powerful Malware Detection: Verisys detects a wide range of threats, ensuring that no malicious files slip through.
Easy Integration: The API is simple to integrate with any web framework, including FastAPI.
Content Type Detection: Alongside malware scanning, the API also scans the file content to determine the real file type.

Conclusion

Handling file uploads is essential for many applications, but steps must be taken to ensure security. By using FastAPI and Verisys Antivirus API, you can create a secure file upload endpoint that scans files for malware before processing them further. Whether you're building a web app or an API for file storage, this approach ensures that your infrastructure - and your users - remain safe from harmful files.

If you haven't yet, sign up for Verisys Antivirus API today and start protecting your application against malware!

Code for this tutorial can be found on GitHub: https://github.com/IonxSolutions/tutorial-file-uploads-fastapi

Securing File Uploads

Ionx Solutions — Thu, 06 Jun 2024 11:06:14 +0000

File uploads are a common feature in web and mobile applications, but they can pose significant security risks if not handled properly. To ensure your apps remains secure, it's crucial to implement robust validation and security measures. This guide will help you to effectively secure file uploads, protecting your systems and end users from malicious intent and malware.

File uploads present several security risks that could compromise both your apps and users. The main risks include:

Malicious Files: Uploaded files can contain viruses, malware, or executable code designed to exploit vulnerabilities.
Cross-Site Scripting (XSS): Inadequately validated files can contain scripts that execute in the context of the user's browser.
Denial-of-Service (DoS) Attacks: Malicious users upload large files, or numerous smaller files, to exhaust server storage and processing capacities.
SQL Injection: If uploaded file metadata (e.g. filename) are not meticulously sanitised, they can serve as vectors for SQL injection attacks, potentially compromising the database.

Due to the diverse range of risks, relying on a single method is not sufficient - a multi-layered approach is required, combining validation checks, metadata sanitisation, secure configuration and malware scanning.

Validate the File Extension

File extensions help in identifying the type of file and determining whether it should be accepted. However, just like the Content-Type header, file extensions can be manipulated. Despite this, enforcing a whitelist of allowed file extensions can act as a preliminary filter to block obviously dangerous file types. Ensure that only extensions pertinent to your application's needs are accepted.

Checking the file extension is another basic step in securing file uploads. However, like other HTTP headers, file names and extensions can easily be spoofed. Use an allowlist approach, permitting only the specific extensions that your application requires (e.g., .jpg, .png, .pdf). This is a simple validation, and can act as a preliminary filter to block obviously dangerous/incorrect file types.

Validate the File Size

Limiting the file size is crucial to prevent denial-of-service (DoS) attacks where an attacker attempts to upload extremely large files to exhaust server resources. Set a maximum file size limit according to your application's requirements and enforce this limit server-side to ensure that oversized files are rejected immediately.

Validate the `Content-Type` Header

Depending on your application's requirements, you will want to accept only particular types of file; for example, for a profile picture you would only want to accept image files.

The Content-Type header, sent by the client, indicates the MIME type of the file being uploaded. While it's useful to validate as a quick and easy check, it should never be fully trusted - malicious users can easily spoof this header. Therefore, treat the Content-Type header as just one of several checks.

How to definitively determine the file type is covered in the next section.

Validate the File Type Based on Signature

As neither the file extension or Content-Type header can be trusted, the most effective and reliable way to verify a file's content/media type is by checking its file signature, or "magic number". These are unique sequences of bytes, usually at the beginning of a file, that indicate its true format. Validation can be performed by reading the first few bytes of the file and matching them against known signatures for allowed file types. For example, a PNG file typically starts with 89 50 4E 47, and a JPEG file starts with FF D8 FF.

This method ensures that the file content matches its purported type, providing a robust defence against file type spoofing. Libraries and tools are available in various programming languages to facilitate this check, or alternatively Verisys Antivirus API can identify 50+ different file formats for you, while also scanning files for malware.

Scan for Malware

Incorporating malware scanning into your file upload process is a critical step to ensure the security of both your application and your end users. Malware can be hidden in seemingly harmless files, posing significant risks once they are uploaded and processed.

While there are several malware scanning tools available, not all are equally effective. For instance, ClamAV is a popular open-source antivirus engine, but has notable drawbacks such as poor detection rates, high resource usage, and slow scan times. These limitations can compromise your application's performance and security.

Consider using a more robust and efficient solution like Verisys Antivirus API. Verisys Antivirus API offers vastly superior detection capabilities, faster scan times, and a ready-to-use antivirus API, making it a reliable choice for integrating malware scanning into your applications.

Boost your app security with Verisys Antivirus API: our language-agnostic API seamlessly integrates malware scanning into your mobile apps, web apps, and backend systems.

By scanning user-generated content and file uploads, Verisys Antivirus API can stop dangerous malware at the edge, before it reaches your servers, applications - or end users.

Storing Files

Steps required to secure files at rest will depend on the location of stored files - for example, they could be uploaded to object storage such as S3, or they could be stored on disk.

Sanitise File Names: file names can contain malicious characters that your application may be unable to process correctly. Always sanitise file names by removing or replacing special characters, spaces, and potentially executable scripts. Consider renaming files upon upload to a standardised naming convention to prevent any harmful effects.
Secure Storage Location: if storing files on disk (rather than, for example, object storage), uploaded files should be stored in a directory that is not directly accessible via the web. This prevents direct execution or access to the files from a URL.
Set Appropriate Permissions: ensure that uploaded files have the minimum necessary permissions. For instance, files should not be executable if they don't need to be.

Closing Thoughts

By combining these strategies, developers can significantly enhance the security of file uploads in their applications. A layered approach, which includes malware scanning, provides comprehensive protection against a variety of attack vectors, ensuring that file uploads remain a safe and useful feature.

For a comprehensive guide on securing file uploads and other web application security best practices, refer to OWASP (Open Worldwide Application Security Project). OWASP provides a wealth of resources, including the OWASP Top Ten, which highlights the most critical security risks to web applications. In particular, see Unrestricted File Upload.

Learn more about Verisys Antivirus API, our language-agnostic API that seamlessly integrates antivirus scanning into your mobile apps, web apps, and backend systems: https://www.ionxsolutions.com/products/antivirus-api

How to Handle File Uploads with ASP.NET Core

Ionx Solutions — Tue, 07 May 2024 11:21:02 +0000

Managing file uploads from end users is often required in web apps and APIs. This tutorial will guide you through the process of handling uploaded files using using ASP.NET Core and C#.

NOTE: To follow this tutorial, you will need the following:

.NET SDK 8 installed on your machine

Basic knowledge of .NET, ASP.NET Core and C#

An IDE or text editor; we'll use Visual Studio 2022 for this tutorial, but a lightweight IDE such as Visual Studio Code will work just as well

To allow files to be uploaded, you will:

Create ASP.NET Core Razor views that allow the user to select a file to upload
Create ASP.NET Core controllers to work with uploaded files

Of course, you will also want to do something with each uploaded file! In this tutorial, we're going to write C# code to show information about the file, and also to scan it for malware using Verisys Antivirus API.

Verisys Antivirus API is a language-agnostic REST API that allows you to easily add malware scanning to mobile apps, web apps and backend processing.

By scanning user-generated content and file uploads, Verisys Antivirus API can stop dangerous malware at the edge, before it reaches your servers, applications - or end users.

Project Setup

First, we need to create a new ASP.NET Core MVC project.

Start Visual Studio and select File > New > Project
Select the template named ASP.NET Core Web App (Model-View-Controller) and click Next

Enter Web for the Project Name, choose a location to save the project, then click Next

For the Framework, select .NET 8.0 (Long Term Support), then click Create

The new project will be created, and you should see this folder structure in Visual Studio's Solution Explorer:

Running the App

Now we've created a new project, let's make sure it runs!

Press CTRL+F5, or click the Start Without Debugging button:

The first time you run the project, you will be asked to install an SSL/TLS certificate - click Yes on both popups:

Visual Studio will then run the app, opening it in the default browser:

While running your project, Visual Studio will open a terminal as well as the browser - this is for the default web server, Kestrel. If you press CTRL-C, it will shut down the web server and stop running your project.

File Upload

To enable file uploads, we need to add:

View models, to encapsulate information about uploaded files
A view with a form that allows users to select and upload a file
A view to show information about the uploaded file
A controller, to show the views and handle the uploaded file
We'll also update the main layout view, just to add links to our new pages

Let's get started!

First, create file Models/FileModels.cs, with content:

namespace Web.Models;

public record UploadModel(IFormFile File);
public record ResultModel(string Name, long Size, string MimeType, 
    MalwareStatus MalwareStatus, string[] Signals);

public record ApiResultModel(Guid Id, MalwareStatus Status, string[] Signals);
public enum MalwareStatus { Unknown, Clean, Threat }

Next, create a folder Views/Upload, and inside a view file Views/Upload/Index.cshtml with content:

@model UploadModel
@{
    ViewData["Title"] = "Upload File";
}

<form method="post" enctype="multipart/form-data">
    <input type="file" asp-for="File">
    <button type="submit">Upload File</button>
</form>

Note the form's encoding type (enctype) property is set to multipart/form-data - this is required for uploading files.

Next, create view file Views/Upload/Result.cshtml with content:

@model ResultModel
@{
    ViewData["Title"] = "Result";
}

<h1>Result</h1>

<div>File Name: @Model.Name</div>
<div>File Size: @Model.Size</div>
<div>Mime Type: @Model.MimeType</div>
<div>Malware Status: @Model.MalwareStatus</div>

Create a controller file Controllers/UploadController.cs with content:

using Microsoft.AspNetCore.Mvc;
using Web.Models;

namespace Web.Controllers;

public class UploadController : Controller
{
    [HttpGet]
    public IActionResult Index()
    {
        return View();
    }

    [HttpPost]
    public IActionResult Index(UploadModel model)
    {
        var result = new ResultModel(model.File.FileName, model.File.Length, model.File.ContentType, MalwareStatus.Unknown, []);
        return View("Result", result);
    }
}

Finally, update the content of Views/Shared/_Layout.cshtml to add links to our new pages:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <title>@ViewData["Title"]</title>
    <link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css" />
</head>
<body>
    <header>
        <nav class="navbar navbar-expand border-bottom mb-3">
            <div class="container-fluid">
                <div class="navbar-collapse">
                    <a class="nav-link text-dark" href="/upload">Upload File</a>
                    <a class="nav-link text-dark" href="/scan">Scan File</a>
                </div>
            </div>
        </nav>
    </header>

    <div class="container">
        <main role="main" class="pb-3">
            @RenderBody()
        </main>
    </div>

</body>
</html>

It really is that simple!

Testing File Uploads

Now we’re ready to test file uploads! 🎉

Begin by running the project again, either by pressing CTRL+F5, or by click the Start Without Debugging button
Your browser should open automatically, showing a page that looks like this:

Click the link Upload File, and you should see one of the new views we created:

Press Choose File to select a file to upload, then and press the Upload File button
If everything was set up correctly, you should see information about the file being shown in a web page:

Note that the Malware Status is shown as Unknown - we'll fix that in the next section.

Malware Scanning

Now we're going to use Verisys Antivirus API to scan uploaded files for malware. Following a similar pattern as for the previous section, we need to add:

Registration of an HTTP client with the Dependency Injection (DI) container
A view with a form that allows users to select and upload a file for scanning
A view to show the results of the malware scan
A controller, to show the views and send the uploaded file to Verisys Antivirus API

Let's get started!

In file Program.cs, replace line builder.Services.AddControllersWithViews(); with:

// Register an HTTP client for use with Verisys Antivirus API
builder.Services.AddHttpClient<HomeController>(x =>
{
    x.BaseAddress = new Uri("https://eu1.api.av.ionxsolutions.com/v1/");
    x.DefaultRequestHeaders.Add("Accept", "application/json");
    x.DefaultRequestHeaders.Add("X-API-Key", "<YOUR API KEY HERE>");
});

builder.Services.AddControllersWithViews().AddJsonOptions(x => {
    x.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
    x.JsonSerializerOptions.PropertyNameCaseInsensitive = false;
});

NOTE:
The X-API-Key in the above code will need to be replaced with a real API key to scan files for real. Don’t have an API key? Subscribe now!

Create a folder Views/Scan, and inside a view file Views/Scan/Index.cshtml with content:

@model UploadModel
@{
    ViewData["Title"] = "Scan File";
}

<form method="post" enctype="multipart/form-data">
    <input type="file" asp-for="File">
    <button type="submit">Scan File</button>
</form>

Next, create view file Views/Scan/Result.cshtml with content:

@model ResultModel
@{
    ViewData["Title"] = "Result";
}

<h1>Result</h1>

<div>File Name: @Model.Name</div>
<div>File Size: @Model.Size</div>
<div>Mime Type: @Model.MimeType</div>
<div>Malware Status: @Model.MalwareStatus</div>

@if (Model.MalwareStatus == MalwareStatus.Threat)
{
    foreach (var signal in Model.Signals)
    {
        <div>Signal: @signal</div>
    }
}

Finally, create a controller file Controllers/ScanController.cs with content:

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;
using System.Text.Json;
using Web.Models;

namespace Web.Controllers;

public class ScanController : Controller
{
    private readonly IHttpClientFactory clientFactory;
    private readonly JsonSerializerOptions jsonOptions;

    public ScanController(IHttpClientFactory clientFactory, IOptions<JsonOptions> jsonOptions)
    {
        this.clientFactory = clientFactory;
        this.jsonOptions = jsonOptions.Value.JsonSerializerOptions;
    }

    [HttpGet]
    public IActionResult Index()
    {
        return View();
    }

    [HttpPost]
    public async Task<IActionResult> Index(UploadModel model)
    {
        using var client = this.clientFactory.CreateClient(nameof(HomeController));

        using var formData = new MultipartFormDataContent();
        formData.Add(new StreamContent(model.File.OpenReadStream()), "file", model.File.FileName);

        using var response = await client.PostAsync("malware/scan/file", formData);
        response.EnsureSuccessStatusCode();

        var apiModel = await response.Content.ReadFromJsonAsync<ApiResultModel>(this.jsonOptions);

        var result = new ResultModel(model.File.FileName, model.File.Length, model.File.ContentType, apiModel!.Status, apiModel.Signals);
        return View("Result", result);
    }
}

Testing Malware Scanning

Now we’re ready to test malware scanning! 🎉

Begin by running the project again, either by pressing CTRL+F5, or by click the Start Without Debugging button
Your browser should open automatically, showing a page that looks like this:

Click the link Scan File, and you should see one of the new views we created:

Press Choose File to select a file to upload, then and press the Upload File button
If everything was set up correctly, you should see malware scan results from Verisys Antivirus API being shown in a web page:

Code for this tutorial can be found on GitHub: https://github.com/IonxSolutions/tutorial-file-uploads-aspnetcore

How to Handle File Uploads with Node.js and Express

Ionx Solutions — Wed, 07 Feb 2024 13:47:30 +0000

A common requirement in web apps and APIs is handling file uploads from end users. In this tutorial you will learn how to work with uploaded files using Node.js and Express.

NOTE: In order to follow this tutorial, you will need the following:

Node.js installed on your machine

Basic knowledge of JavaScript and Express

A text editor or lightweight IDE such as Visual Studio Code

Overview

To allow files to be uploaded, you will:

Create a web page with a form that allows the user to select a file to upload
Create Express route handlers to work with uploaded files

Of course, you will also want to do something with each uploaded file! In this tutorial, we're going to write JavaScript code to display some information about the file, and also to scan it for malware using Verisys Antivirus API.

Verisys Antivirus API is a language-agnostic REST API that allows you to easily add malware scanning to mobile apps, web apps and backend processing.

By scanning user-generated content and file uploads, Verisys Antivirus API can stop dangerous malware at the edge, before it reaches your servers, applications - or end users.

Project Setup

The first step is to create and initialize a new Express project.

Open a terminal or command prompt, navigate to the directory where you want to store the project, and run the following commands:

npx express-generator --view=pug myapp
cd myapp
npm install

The generated app should have the following directory structure:

.
├── app.js
├── package.json
├── bin
│   └── www
├── package.json
├── public
│   ├── images
│   ├── javascripts
│   └── stylesheets
│       └── style.css
├── routes
│   ├── index.js
│   └── users.js
├── views
│   ├── error.pug
│   └── index.pug
│   └── layout.pug

Before we move on, make sure you are able to run the app and view it in a browser

On MacOS, Linux or Git Bash on Windows, run the app with this command:

DEBUG=myapp:* npm start

Or use this command for Windows:

set DEBUG=myapp:* & npm start

Or this command for Windows Powershell:

$env:DEBUG='myapp:*'; npm start

Then navigate to http://localhost:3000 in your browser to access the app - you should see a page that looks like this:

Go ahead and stop the server by hitting CTRL-C at the command prompt
Next we’re going to add a few NPM packages:
- We’ll add a package to deal with file uploads easier. There are several popular choices here, including Multer, Formidable and express-fileupload - they are all fairly similar, and for this tutorial, we’ll use express-fileupload
- For this tutorial, we’re going to scan the file for malware using Verisys Antivirus API, and so we’ll add a package to make it easier to make external HTTP requests. Popular choices include Axios and node-fetch - for this article, we’ll use node-fetch
- We’ll also add the form-data package to allow working with multipart form data, which is used to perform file uploads

npm install express-fileupload
npm install node-fetch@^2.7.0
npm install form-data

Frontend

Before we write JavaScript code to handle the file upload, let’s create a simple web page that lets the end user select a file to upload.

Update the content of myapp/views/index.pug to contain the following:

extends layout

block content

  h2 File Upload

  <form action="/upload" method="POST" enctype="multipart/form-data">
    <input type="file" name="file" required>
    <button type="submit">Upload File</button>
  </form>

  br

  h2 Malware Scan

  <form action="/scan" method="POST" enctype="multipart/form-data">
    <input type="file" name="file" required>
    <button type="submit">Scan File</button>
  </form>

Backend - Simple File Upload

Now we’re going to add a route handler to process uploaded files, and then we’ll wire up the handler to the /upload route.

Create file myapp/routes/upload.js with the following content:

const express = require('express');
const fileUpload = require('express-fileupload');
const router = express.Router();

router.use(fileUpload({
  // Configure file uploads with maximum file size 10MB
  limits: { fileSize: 10 * 1024 * 1024 },

  // Temporarily store uploaded files to disk, rather than buffering in memory
  useTempFiles : true,
  tempFileDir : '/tmp/'
}));

router.post('/', async function(req, res, next) {
  // Was a file submitted?
  if (!req.files || !req.files.file) {
    return res.status(422).send('No files were uploaded');
  }

  const uploadedFile = req.files.file;

  // Print information about the file to the console
  console.log(`File Name: ${uploadedFile.name}`);
  console.log(`File Size: ${uploadedFile.size}`);
  console.log(`File MD5 Hash: ${uploadedFile.md5}`);
  console.log(`File Mime Type: ${uploadedFile.mimetype}`);

  // Return a web page showing information about the file
  res.send(`File Name: ${uploadedFile.name}<br>
  File Size: ${uploadedFile.size}<br>
  File MD5 Hash: ${uploadedFile.md5}<br>
  File Mime Type: ${uploadedFile.mimetype}`);
});

module.exports = router;

This simple handler will both print information about the file to the console and return it in as a web page, so you can see what has been received by your router.

Next, we need to wire up this code to the /upload route.

Update the content of myapp/app.js to contain the following:

var createError = require('http-errors');
var express = require('express');
var path = require('path');
var cookieParser = require('cookie-parser');
var logger = require('morgan');

var indexRouter = require('./routes/index');
var usersRouter = require('./routes/users');
var uploadRouter = require('./routes/upload');

var app = express();

// view engine setup
app.set('views', path.join(__dirname, 'views'));
app.set('view engine', 'pug');

app.use(logger('dev'));
app.use(express.json());
app.use(express.urlencoded({ extended: false }));
app.use(cookieParser());
app.use(express.static(path.join(__dirname, 'public')));

app.use('/', indexRouter);
app.use('/users', usersRouter);
app.use('/upload', uploadRouter);

// catch 404 and forward to error handler
app.use(function(req, res, next) {
  next(createError(404));
});

// error handler
app.use(function(err, req, res, next) {
  // set locals, only providing error in development
  res.locals.message = err.message;
  res.locals.error = req.app.get('env') === 'development' ? err : {};

  // render the error page
  res.status(err.status || 500);
  res.render('error');
});

module.exports = app;

We’ve only added 2 lines to the default code provided by the Express generator (lines #9 and #25 above), telling Express to use our upload.js router for the /upload route.

Testing File Uploads

Now we’re ready to test it! 🎉

Begin by starting your Node.js server using the same command as before
Open your browser and navigate to http://localhost:3000 - you should see a page that looks like this:

Use the File Upload form, Browse to select a file and press the Upload File button

If everything was set up correctly, you should see information about the file being printed to the console, and also shown in a web page.

Backend - Malware Scanning

Now we’re going to add a route handler to perform a virus scan on uploaded files, and then we’ll wire up the handler to the /scan route.

Create file myapp/routes/scan.js with the following content:

const express = require('express');
const fetch = require('node-fetch');
const fileUpload = require('express-fileupload');
const FormData = require('form-data'); 
const fs = require('fs');
const router = express.Router();

router.use(fileUpload({
  // Configure file uploads with maximum file size 10MB
    limits: { fileSize: 10 * 1024 * 1024 },

  // Temporarily store uploaded files to disk, rather than buffering in memory
  useTempFiles : true,
  tempFileDir : '/tmp/'
}));

router.post('/', async function(req, res, next) {
  // Was a file submitted?
  if (!req.files || !req.files.file) {
    return res.status(422).send('No files were uploaded');
  }

  const uploadedFile = req.files.file;

  // Print information about the file to the console
  console.log(`File Name: ${uploadedFile.name}`);
  console.log(`File Size: ${uploadedFile.size}`);
  console.log(`File MD5 Hash: ${uploadedFile.md5}`);
  console.log(`File Mime Type: ${uploadedFile.mimetype}`);

  // Scan the file for malware using the Verisys Antivirus API - the same concepts can be
  // used to work with the uploaded file in different ways
  try {
    // Attach the uploaded file to a FormData instance
    var form = new FormData();
    form.append('file', fs.createReadStream(uploadedFile.tempFilePath), uploadedFile.name);

    const headers = {
      'X-API-Key': '<YOUR API KEY HERE>',
      'Accept': '*/*'
    };

    // Send the file to the Verisys Antivirus API
    const response = await fetch('https://eu1.api.av.ionxsolutions.com/v1/malware/scan/file', {
      method: "POST",
      body: form,
      headers: headers
    });

    // Did we get a response from the API?
    if (response.ok) {
      const result = await response.json();

      // Did the file contain a virus/malware?
      if (result.status === 'clean') {
        return res.send('Uploaded file is clean!');
      } else {
        return res.status(500).send(`Uploaded file contained malware: <b>${result.signals[0]}</b>`);
      }
    } else {
      throw new Error('Unable to scan file: ' + response.statusText);
    }
  } catch (error) {
    // Forward the error to the Express error handler
    return next(error);
  } finally {
    // Remove the uploaded temp file
    fs.rm(uploadedFile.tempFilePath, () => {});
  }
});

module.exports = router;

NOTE:
The X-API-Key in the above code will need to be replaced with a real API key to scan files for real. Don’t have an API key? Subscribe now!

Next, we need to wire up this code to the /scan route.

Update the content of myapp/app.js to contain the following:

var createError = require('http-errors');
var express = require('express');
var path = require('path');
var cookieParser = require('cookie-parser');
var logger = require('morgan');

var indexRouter = require('./routes/index');
var usersRouter = require('./routes/users');
var uploadRouter = require('./routes/upload');
var scanRouter = require('./routes/scan');

var app = express();

// view engine setup
app.set('views', path.join(__dirname, 'views'));
app.set('view engine', 'pug');

app.use(logger('dev'));
app.use(express.json());
app.use(express.urlencoded({ extended: false }));
app.use(cookieParser());
app.use(express.static(path.join(__dirname, 'public')));

app.use('/', indexRouter);
app.use('/users', usersRouter);
app.use('/upload', uploadRouter);
app.use('/scan', scanRouter);

// catch 404 and forward to error handler
app.use(function(req, res, next) {
  next(createError(404));
});

// error handler
app.use(function(err, req, res, next) {
  // set locals, only providing error in development
  res.locals.message = err.message;
  res.locals.error = req.app.get('env') === 'development' ? err : {};

  // render the error page
  res.status(err.status || 500);
  res.render('error');
});

module.exports = app;

We’ve only added two lines to the previous code (lines #10 and #27 above), telling Express to use our scan.js router for the /scan route.

Testing Malware Scanning

Now we’re ready to test malware scanning! 🎉

Begin by starting your Node.js server using the same command as before
Open your browser and navigate to http://localhost:3000 - you should see a page that looks like this:

Use the Malware Scan form, Browse to select a file and press the Scan File button

If everything was set up correctly, as before you should see information about the file being printed to the console, but you should also see a response from Verisys Antivirus API:

Code for this tutorial can be found on GitHub: https://github.com/IonxSolutions/tutorial-file-uploads-express

DEV Community: Ionx Solutions

Safely Handling Malware Samples for API Testing

Who This Guide is For

Start Here: The EICAR Test File

Why You Might Need Real Malware Samples

The Dangers of Handling Live Malware

The Upload-Only Advantage

Architecture Overview

What You'll Need

Setting Up the Host

Creating the Sandbox Virtual Network

Setting Up Shared Directories

Creating the Sandbox VM

Configuring the Sandbox VM

Locking Down the Network

Sourcing Malware Samples

MalwareBazaar

TheZoo

vx-underground

End-to-End Workflow

Interpreting the API Response

Closing Thoughts

How to Handle File Uploads with Node.js and Express - Multer Edition

Why Choose Multer?

Project Scaffold/Setup

Frontend

Backend - Simple File Upload

Testing File Uploads

Backend - Malware Scanning

Testing Malware Scanning

How to Handle File Uploads with Python and FastAPI

Why FastAPI?

Project Scaffold/Setup

Creating the FastAPI App

Starting the FastAPI App

Testing the API

Integrating Verisys Antivirus API

Testing the Completed API

Handling File Uploads Securely

Why Choose Verisys Antivirus API?

Conclusion

Securing File Uploads

Validate the File Extension

Validate the File Size

Validate the Content-Type Header

Validate the File Type Based on Signature

Scan for Malware

Storing Files

Closing Thoughts

How to Handle File Uploads with ASP.NET Core

Project Setup

Running the App

File Upload

Testing File Uploads

Malware Scanning

Testing Malware Scanning

How to Handle File Uploads with Node.js and Express

Overview

Project Setup

Frontend

Backend - Simple File Upload

Testing File Uploads

Backend - Malware Scanning

Testing Malware Scanning

Validate the `Content-Type` Header