Sending scan job

Scan jobs are sent to the SQS Scan Queue. Learn more about the message format.

Example: Send scan job

JavaScript

Run npm i aws-sdk to install the required dependency.

To get the Scan Queue URL:

1. Visit the AWS CloudFormation Console
2. Ensure that you are in the correct region.
3. Navigate to Stacks.
4. Click on the bucketAV stack (if you followed the docs, the name is bucketav).
5. Click on the Outputs tab.
6. Check the value next to the output key ScanQueueUrl.

const AWS = require('aws-sdk');
const sqs = new AWS.SQS({ apiVersion: '2012-11-05' });

function scan (queueUrl, bucket, key, cb) {
  sqs.sendMessage({
    MessageBody: JSON.stringify({
      objects: [{
        bucket,
        key
      }]
    }),
    QueueUrl: queueUrl
  }, (err) => {
    if (err) {
      cb(err);
    } else {
      cb();
    }
  });
}

scan('your-scan-queue-url', 'your-bucket', 'path/to/file.pdf', (err) => {
  if (err) {
    console.error('something went wrong', err);
  } else {
    console.log('done');
  }
});

GitHub: https://github.com/widdix/bucketav-developer-examples/blob/main/javascript/send-scan-job.js

Python

Run pip install boto3 to install the required dependency.

To get the Scan Queue URL:

1. Visit the AWS CloudFormation Console
2. Ensure that you are in the correct region.
3. Navigate to Stacks.
4. Click on the bucketAV stack (if you followed the docs, the name is bucketav).
5. Click on the Outputs tab.
6. Check the value next to the output key ScanQueueUrl.

import boto3
import json

sqs = boto3.client('sqs')

def scan(queue_url, bucket, key):
    sqs.send_message(
        QueueUrl=queue_url,
        MessageBody=json.dumps({
            'objects': [{
                'bucket': bucket,
                'key': key
            }]
        })
    )

scan('your-scan-queue-url', 'your-bucket', 'path/to/file.pdf')

print('Done')

GitHub: https://github.com/widdix/bucketav-developer-examples/blob/main/python/send-scan-job.py

SQS message format

Scan jobs can be submitted to the Scan Queue programmatically. The queue name is prefixed by the CloudFormation stack name you defined during setup (if you followed the docs, the prefix is bucketav).

Requires bucketAV powered by ClamAV® version >= 2.9.0 or bucketAV powered by Sophos® version >= 2.0.0. To update to the latest version, follow the Update Guide.

The following structure of the message body is recommended:

{
  "objects": [
    {
      "bucket": "BUCKET_NAME",
      "key": "OBJECT_KEY",
      "version": "OBJECT_VERSION",
      "trace_id": "TRACE_ID",
      "custom_data": "CUSTOM_DATA"
    }    
  ]
  "downloads": [
    {
      "download_url": "https://your-company.com/path/to/file.zip",
      "callback_url": "https://your-company.com/bucketav/webhook"
    }
  ]
}

Please consider the following details:

• objects (array): List of up to 10 objects.
  • bucket (string): The name of the S3 bucket.
  • key (string): The object key has to be URL encoded (e.g., via encodeURIComponent()).
  • version (string, optional): Only required if the bucket is versioned.
  • trace_id (string, optional): ID allowing you to trace the scan request with a custom ID, which could be a Step Functions task token, for example.
  • custom_data (string, optional): Custom data that bucketAV passes through to SNS together with the scan result—maximum of 16 KB in UTF-8.
• downloads: List of up to 10 downloads (requires bucketAV powered by ClamAV® version >= 2.14.0 or bucketAV powered by Sophos® version >= 2.4.0).
  • download_url (string): URL to download and scan via HTTP(S) GET.
  • 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.

You can include objects and/or downloads, but not any of them.

The downloads.callback_url is called by bucketAV via an HTTPS POST request with a JSON paylod with this 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.

For bucketAV powered by ClamAV® version < 2.9.0, you must use the following message body, which is a subset of the official S3 event message structure:

{
  "Records": [{
    "s3": {
      "bucket": {
        "name": "BUCKET_NAME"
      },
      "object": {
        "key": "OBJECT_KEY",
        "versionId": "OBJECT_VERSION",
        "size": 123456
      }
    }
  }]
}

Please consider the following details:

• key: Has to be URL encoded (e.g., via encodeURIComponent()).
• versionId: Only required if the bucket is versioned.
• size: In bytes.