Virus and Malware Scan API (SaaS)

API key (#)

To access the API, an API key is required. Subcribe to one of the following plans to get a license key, also used as API key.

Get API key by creating a subscription!

API definition (#)

Accessing the API requires an API key. Pass the API key via a x-api-key HTTP header.

POST /v1/scan/sync/download (#)

Download a file from a remote location (HTTP/HTTPS), scan the file, and return the scan result.

Maximum file size is 200 MB. The request timeout is 60 seconds.

The request body is JSON formatted with these properties:

• download_url (string): URL to download and scan via HTTP(S) GET.
• download_headers: (object, optional): Headers to send when downloading the file.

The response status code is 200, and the body is JSON formatted with these properties:

• status (string (clean, infected, no)): The scan result.
• finding (string, optional): For infected files, the type of virus/malware that was detected.
• size (number, optional): The file size in bytes.

Example:

curl \
  -X POST \
  -H 'x-api-key: XXX' \
  -H 'Content-Type: application/json' \
  -d '{"download_url": "https://download.yourcompany.com/path/to/file.pdf"}' \
  'https://eu.developer.attachmentav.com/v1/scan/sync/download'

{"status":"clean","size":2903045}

POST /v1/scan/sync/binary (#)

Upload a file, scan the file, and return the scan result.

Maximum file size is 10 MB. The request timeout is 60 seconds.

The request body contains the binary data (application/octet-stream).

The response status code is 200, and the body is JSON formatted with these properties:

• status (string (clean, infected, no)): The scan result.
• finding (string, optional): For infected files, the type of virus/malware that was detected.
• size (number, optional): The file size in bytes.

Example:

curl \
  -X POST \
  -H 'x-api-key: XXX' \
  -H 'Content-Type: application/octet-stream' \
  -d '@path/to/file' \
  https://eu.developer.attachmentav.com/v1/scan/sync/binary

{"status":"clean","size":73928372}

POST /v1/scan/sync/form (#)

Upload a file, scan the file, and return the scan result.

Maximum file size is 10 MB. The request timeout is 60 seconds.

The request body is multipart/form-data formatted and contains one file.

The response status code is 200, and the body is JSON formatted with these properties:

• status (string (clean, infected, no)): The scan result.
• finding (string, optional): For infected files, the type of virus/malware that was detected.
• size (number, optional): The file size in bytes.

Example:

curl \
  -H 'x-api-key: XXX' \
  -F file=@path/to/file \
  https://eu.developer.attachmentav.com/v1/scan/sync/form

{"status":"clean","size":73928372}

POST /v1/scan/sync/s3 (#)

Download a file from S3, scan the file, and return the scan result. A bucket policy is required to grant attachmentAV access to the S3 objects.

Maximum file size is 200 MB. The request timeout is 60 seconds.

The request body is JSON formatted with these properties:

• bucket (string): The bucket name.
• key (string): The object key.
• version (string, optional): If versioning is turned on, the object version.

The response status code is 200, and the body is JSON formatted with these properties:

• status (string (clean, infected, no)): The scan result.
• finding (string, optional): For infected files, the type of virus/malware that was detected.
• size (number, optional): The file size in bytes.

Example:

curl \
  -X POST \
  -H 'x-api-key: XXX' \
  -H 'Content-Type: application/json' \
  -d '{"bucket": "you-bucket", "key": "path/to/file.pdf"}' \
  'https://eu.developer.attachmentav.com/v1/scan/sync/s3'

{"status":"clean","size":105255200}

POST /api/v1/scan/async/download (#)

Download a file from a remote location (HTTP/HTTPS), scan the file, and post the scan result to your callback URL.

Maximum file size is 5 GB. The request timeout is 29 seconds, the asynchronous scan job is not affected by this limit.

The request body is JSON formatted with these properties:

• download_url (string): URL to download and scan via HTTP(S) GET.
• download_headers: (object, optional): Headers to send when downloading the file.
• callback_url (string): URL to receive the scan result via HTTPS POST.
• callback_headers: (object, optional): Headers to send when invoking the callback. The headers Content-Type and Content-Length are always added and can not be changed.
• trace_id (string, optional): ID allowing you to trace the scan request with a custom ID.
• custom_data (string, optional): Custom data that bucketAV passes through-maximum of 16 KB in UTF-8.

The response status code is 204. See Callback URL for response format.

Example:

curl \
  -vvv \
  -X POST \
  -H 'x-api-key: XXX' \
  -H 'Content-Type: application/json' \
  -d '{"download_url": "https://download.yourcompany.com/path/to/file.pdf", "callback_url": "https://api.yourcompany.com/bucketav/callback"}' \
  'https://eu.developer.attachmentav.com/v1/scan/async/download'

POST /api/v1/scan/async/s3 (#)

Download a file from S3, scan the file, and post the scan result to your callback URL. A bucket policy is required to grant attachmentAV access to the S3 objects.

Maximum file size is 5 GB. The request timeout is 29 seconds, the asynchronous scan job is not affected by this limit.

The request body is JSON formatted with these properties:

• bucket (string): The bucket name.
• key (string): The object key.
• version (string, optional): If versioning is turned on, the object version.
• callback_url (string): URL to receive the scan result via HTTPS POST.
• trace_id (string, optional): ID allowing you to trace the scan request with a custom ID.
• custom_data (string, optional): Custom data that bucketAV passes through-maximum of 16 KB in UTF-8.

The response status code is 204. See Callback URL for response format.

Example:

curl \
  -vvv \
  -X POST \
  -H 'x-api-key: XXX' \
  -H 'Content-Type: application/json' \
  -d '{"bucket": "you-bucket", "key": "path/to/file.pdf", "callback_url": "https://api.yourcompany.com/bucketav/callback"}' \
  'https://eu.developer.attachmentav.com/v1/scan/async/s3'

Callback URL (#)

The callback URL is called by bucketAV via an HTTPS POST request with a JSON payload with these properties:

• status (string (clean, infected, no)): The scan result.
• finding (string, optional): For infected files, the type of virus/malware that was detected.
• size (number): The file size in bytes.
• download_time (number): Time to download the file in seconds.
• scan_time (number): Time to scan the file in seconds.
• download_url (string): The downloaded URL.
• trace_id (string, optional): ID to trace custom scan jobs.
• custom_data (string, optional): Custom data defined when submitting a custom scan job.

S3 Bucket Policy (#)

In case you want to use POST /api/v1/scan/async/s3 or POST /api/v1/scan/sync/s3 it is neccessary to grant attachmentAV access to download the object from S3. Therefore, you need to attach the following bucket policy. Ensure to replace BUCKET_NAME with the name of the bucket.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "attachmentAV",
    "Effect": "Allow",
    "Principal": {
      "AWS": "arn:aws:iam::450892694845:root"
    },
    "Action": "s3:GetObject*",
    "Resource": "arn:aws:s3:::BUCKET_NAME/*"
  }]
}

Please note, attachmentAV does not support scanning S3 objects encrypted with KMS.