Sending scan job

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

Example: Send scan job

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.

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

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

Run pip install boto3 to install the required dependency.

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 for Amazon S3 powered by ClamAV® version >= 2.9.0, bucketAV for Amazon S3 powered by Sophos® version >= 2.0.0, bucketAV for Cloudflare R2 powered by ClamAV® version >= 2.0.0, or bucketAV for Cloudflare R2 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 required:

{
  "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",
      "download_headers": {
        "Authorization": "Bearer test"
      },
      "callback_url": "https://your-company.com/bucketav/webhook",
      "callback_headers": {
        "Authorization": "Bearer test"
      },
      "trace_id": "TRACE_ID",
      "custom_data": "CUSTOM_DATA"
    }
  ]
}

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—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.
    • download_headers: (object, optional): Headers to send when downloading the file (requires bucketAV powered by ClamAV® version >= 2.17.0 or bucketAV powered by Sophos® version >= 2.8.0).
    • callback_url (string): URL to receive the scan result via HTTPS POST (see Callback).
    • callback_headers: (object, optional): Headers to send when invoking the callback (Content-Type and Content-Length are always added and cannot be changed; requires bucketAV powered by ClamAV® version >= 2.17.0 or bucketAV powered by Sophos® version >= 2.8.0).
    • 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.

Need more help?

Write us, and we'll get back to you as soon as we can.

Send us an email