Receiving scan result
Scan results are published to the an SNS topic -called findings topic- and EventBridge. Additionally, we tag the scanned object with the scan result. The following examples demonstrate how you can use the scan result in your applications.
Example: Generate a pre-signed URL for download if the file is tagged as clean
The following example queries the object’s tags and extracts the scan result before generating a pre-signed URL for download.
JavaScript
Run npm i aws-sdk to install the required dependency.
const AWS = require('aws-sdk');
const s3 = new AWS.S3({ apiVersion: '2006-03-01' });
function getSignedUrl (bucket, key, cb) {
s3.getObjectTagging({
Bucket: bucket,
Key: key
}, (err, data) => {
if (err) {
cb(err);
} else {
const tag = data.TagSet.find(tag => tag.Key === 'bucketav');
if (tag !== undefined && tag.Value === 'clean') {
s3.getSignedUrl('getObject', {
Bucket: bucket,
Key: key
}, (err, signedUrl) => {
if (err) {
cb(err);
} else {
cb(null, signedUrl);
}
});
} else {
cb(null, null);
}
}
});
}
getSignedUrl('your-bucket', 'path/to/file.pdf', (err, signedUrl) => {
if (err) {
console.error('something went wrong', err);
} else {
if (signedUrl === null) {
console.log('download not possible (file infected, unscannable, or not yet scanned)');
} else {
console.log(signedUrl);
}
}
});
Python
Run pip install boto3 to install the required dependency.
import boto3
s3 = boto3.client('s3')
def get_signed_url(bucket, key):
response = s3.get_object_tagging(
Bucket=bucket,
Key=key
)
tags = response['TagSet']
tag = next((t for t in tags if t['Key'] == 'bucketav'), None)
if tag is not None and tag['Value'] == 'clean':
signed_url = s3.generate_presigned_url(
'get_object',
Params={
'Bucket': bucket,
'Key': key
}
)
return signed_url
else:
return None
signed_url = get_signed_url('your-bucket', 'path/to/file.pdf')
if signed_url is None:
print('Download not possible (file infected, unscannable, or not yet scanned)')
else:
print(signed_url)
Example: Subscribe to Findings Topic and store results in DynamoDB
The following example:
- Subscribes to the Findings Topic
- Stores scan results in DynamoDB
- Queries DynamoDB and extracts the scan result before generating a pre-signed URL for download.
Please find the example on GitHub: https://github.com/widdix/bucketav-developer-examples/tree/main/javascript/subscribe-to-findings-topic
SNS message format
The SNS topic name is prefixed by the CloudFormation stack name you defined during setup (if you followed the docs, the prefix is bucketav).
If the subscription protocol is set to email, the body contains a human-readable string. Otherwise, the body is formatted in JSON with the following keys/structure.
JSON payloads require bucketAV for Amazon S3 powered by ClamAV® version >= 2.1.0 or bucketAV for Amazon S3 powered by Sophos® version >= 2.0.0, or any version of bucketAV for Cloudflare R2. To update to the latest version, follow the Update Guide.
bucket(string): The bucket name.key(string): The object key.version(string, optional): If versioning is turned on, the object version (requires bucketAV powered by ClamAV® version >= 2.3.0 or bucketAV powered by Sophos® version >= 2.0.0).size(number): The object size in bytes (requires bucketAV powered by ClamAV® version >= 2.13.0 or bucketAV powered by Sophos® version >= 2.2.0).status(string (clean,infected,no)): The scan result.action(string (delete,tag,no)): The action that was taken.finding(string, optional): For infected files, the type of virus/malware that was detected.trace_id(string, optional): ID to trace custom scan jobs (requires bucketAV powered by ClamAV® version >= 2.9.0 or bucketAV powered by Sophos® version >= 2.0.0).custom_data(string, optional): Custom data defined when submitting a custom scan job (requires bucketAV powered by ClamAV® version >= 2.9.0 or bucketAV powered by Sophos® version >= 2.0.0).realfiletype(string, optional): The Real File Type detected by the Sophos engine (Sophos only, requires bucketAV powered by Sophos® version >= 2.18.0 or bucketAV for Cloudflare R2 powered by Sophos® >= 2.5.0).
{
"bucket": "testbucket",
"key": "bucketav/test/file.pdf",
"version": "optional_qAKVCwsELNe_pDHtdIIzX_jRJAcKVQaG",
"status": "infected",
"action": "delete",
"finding": "optional_TestWorm",
"trace_id": "1234567",
"custom_data": "...",
"realfiletype": "Adobe Portable Document Format (PDF)"
}
The following message attributes are part of every message and can be used for message filtering:
SNS attribute values must not contain surrogate characters (e.g., some emojis). Therefore, we replace them with the
#character. Inspect the JSON body to get the raw data.
bucket(string): The bucket name.key(string): The object keyversion(string, optional): If versioning is turned on, the object version.size(number): The object size in bytes (requires bucketAV powered by ClamAV® version >= 2.13.0 or bucketAV powered by Sophos® version >= 2.2.0).status(string (clean,infected,no)): The scan result.action(string (delete,tag,no)): The action that was taken.finding(string, optional): For infected files, the type of virus/malware that was detected (requires bucketAV powered by ClamAV® version >= 1.7.0 or bucketAV powered by Sophos® version >= 2.0.0).trace_id(string, optiona): ID to trace custom scan jobs (requires bucketAV powered by ClamAV® version >= 2.9.0 or bucketAV powered by Sophos® version >= 2.0.0).
EventBridge message format
To emit events to EventBridge, set the ReportEventBridge configuration parameter to true. The source of events is com.bucketav and the type is Scan Result. The event body contains the following fields.
bucket(string): The bucket name.key(string): The object key.version(string, optional): If versioning is turned on, the object version.size(number): The object size in bytes.status(string (clean,infected,no)): The scan result.action(string (delete,tag,no)): The action that was taken.finding(string, optional): For infected files, the type of virus/malware that was detected.trace_id(string, optional): ID to trace custom scan jobs.custom_data(string, optional): Custom data defined when submitting a custom scan job.realfiletype(string, optional): The Real File Type detected by the Sophos engine (Sophos only, requires bucketAV powered by Sophos® version >= 2.18.0 or bucketAV for Cloudflare R2 powered by Sophos® >= 2.5.0).
{
"version": "0",
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"detail-type": "Scan Result",
"source": "com.bucketav",
"account": "111111111111",
"time": "2024-10-22T00:00:00Z",
"region": "eu-west-1",
"resources": [],
"detail": {
"bucket": "testbucket",
"key": "bucketav/test/file.pdf",
"version": "optional_qAKVCwsELNe_pDHtdIIzX_jRJAcKVQaG",
"status": "infected",
"action": "delete",
"finding": "optional_TestWorm",
"trace_id": "1234567",
"custom_data": "...",
"realfiletype": "Adobe Portable Document Format (PDF)"
}
}