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

Object 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).

Since bucketAV version >= 2.9.0, 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"
    }    
  ]
}

Please consider the following details:

• objects: List of up to 10 objects.
  • bucket: The name of the S3 bucket.
  • key: The object key has to be URL encoded (e.g., via encodeURIComponent()).
  • version: Only required if the bucket is versioned.
  • trace_id: 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: Optional custom data that bucketAV passes through to SNS together with the scan result—maximum of 16 KB in UTF-8.

For bucketAV versions < 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.