Virus Scan for Python Guide

Python applications that handle file uploads, process attachments, or download content from external sources are exposed to a serious risk: malware. Whether files arrive through a web form, an API integration, or a cloud storage bucket, a single infected file can compromise your infrastructure and endanger your users’ data. Compliance standards like GDPR, HIPAA, and SOC 2 increasingly require organizations to scan files for viruses before processing them. Building virus scanning directly into your Python application ensures every file is verified before it enters your pipeline.

In this guide, you will learn how to integrate virus and malware scanning into your Python application using the attachmentAV API. The API is powered by Sophos, requires no local antivirus installation, and offers both synchronous and asynchronous scanning modes to fit different use cases.

Install the Virus and Malware Scan SDK

The attachmentAV Python SDK is available on PyPI. Install it with pip to add virus scan capabilities to your project.

pip install attachmentav-virus-malware-scan-sdk

Create a subscription

An active subscription and API key is required to access the attachmentAV API. Choose a plan that fits your scanning volume—Small (10,000 requests/month), Medium (50,000), or Large (100,000)—and you will receive an API key. Replace <API_KEY_PLACEHOLDER> in the code examples below with your key. See the Setup Guide for details.

Choose a response mode

The attachmentAV API supports two response modes:

• Synchronous – The virus scan result is returned directly in the HTTP response. This mode is the simplest to integrate and works well for files up to 10 MB (binary upload) or 200 MB (URL/S3) with a 60-second timeout.
• Asynchronous – The scan result is delivered later, either by polling a result endpoint or via a callback URL. This mode supports files up to 5 GB and is ideal for large files or background processing.

Upload file for synchronous scan

To scan a local file, read its binary content and send it to the synchronous binary scan endpoint. The API returns the virus scan result immediately, making this approach ideal for validating user uploads in Python before storing them.

import attachmentav

configuration = attachmentav.Configuration()
configuration.api_key['apiKeyAuth'] = "<API_KEY_PLACEHOLDER>"

with attachmentav.ApiClient(configuration) as api_client:
  api_instance = attachmentav.AttachmentAVApi(api_client)

with open("/path/to/file", "rb") as file:
    file_content = file.read()
    scan_result = api_instance.scan_sync_binary_post(file_content)
    print(scan_result)

The response contains a status field with one of three values: clean, infected, or no (when the file could not be scanned). For infected files, the finding field identifies the specific threat detected.

Synchronously scan URL

If the file you want to virus scan is available at a public URL, you can let attachmentAV download and scan it directly. This avoids downloading the file to your Python application first.

import attachmentav

configuration = attachmentav.Configuration()
configuration.api_key['apiKeyAuth'] = "<API_KEY_PLACEHOLDER>"

with attachmentav.ApiClient(configuration) as api_client:
  api_instance = attachmentav.AttachmentAVApi(api_client)

sync_download_scan_request = attachmentav.SyncDownloadScanRequest(
  download_url = "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
)
scan_result = api_instance.scan_sync_download_post(sync_download_scan_request)
print(scan_result)

Scan URL asynchronously

For larger files or when you want to decouple virus scanning from request handling, use the asynchronous response mode. Submit the URL for scanning with a unique trace_id, then poll the result endpoint until the scan completes. The API returns a 404 while the scan is still in progress, so the code retries every 5 seconds up to 10 times before giving up.

import attachmentav
import sys
import time
import uuid

configuration = attachmentav.Configuration()
configuration.api_key['apiKeyAuth'] = "<API_KEY_PLACEHOLDER>"

with attachmentav.ApiClient(configuration) as api_client:
  api_instance = attachmentav.AttachmentAVApi(api_client)

trace_id = str(uuid.uuid4())

async_download_scan_request = attachmentav.AsyncDownloadScanRequest(
  download_url = "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  trace_id = trace_id
)
api_instance.scan_async_download_post(async_download_scan_request)
print("Async download submitted. Start to poll for scan result...")

i = 0
while True:
  print('.')
  try:
    scan_result = api_instance.scan_async_result_get(trace_id)
    print(scan_result)
    sys.exit(0)
  except attachmentav.exceptions.NotFoundException:
    i += 1
    if i < 10:
      time.sleep(5)
    else:
      print('Async download scan result not found')
      sys.exit(1)

Instead of polling, you can also pass a callback_url when submitting the scan job. attachmentAV will then POST the virus scan result directly to your endpoint once the scan is complete. See the callback documentation for details on the payload and how to verify its signature.

Scan S3 object asynchronously

If your files are stored in Amazon S3, attachmentAV can fetch and virus scan them directly—no need to download and re-upload. A bucket policy granting attachmentAV read access is required.

import attachmentav

configuration = attachmentav.Configuration()
configuration.api_key['apiKeyAuth'] = "<API_KEY_PLACEHOLDER>"

with attachmentav.ApiClient(configuration) as api_client:
  api_instance = attachmentav.AttachmentAVApi(api_client)

async_s3_scan_request = attachmentav.AsyncS3ScanRequest(
  bucket = "<BUCKET_NAME_PLACEHOLDER>",
  key = "<OBJECT_KEY_PLACEHOLDER>",
  callback_url = "https://api.yourcompany.com/attachmentav/callback"
)
api_instance.scan_async_s3_post(async_s3_scan_request)
print("Async S3 submitted")

Get started with virus scanning in Python

Adding virus and malware scanning to a Python application takes only a few lines of code with the attachmentAV SDK. Whether you need to scan user uploads synchronously or process large files asynchronously from URLs and S3, attachmentAV and its Sophos-powered engine have you covered.

Ready to protect your Python application? Sign up for attachmentAV and start scanning files for viruses and malware today.