Guides

Reports

Reports are an essential pillar of your data security strategy for several reasons:

  • Compliance: Reports demonstrate compliance with security regulations and standards.
  • Trend analysis: Reports help to analyze trends in malware detections and to identify patterns in infected files. This can help organizations to better understand the type of malware they are dealing with and to develop more effective defense strategies.
  • Evidence gathering: In the event of a security breach, reports can provide valuable evidence to help identify the breach’s source and support investigations.
  • Auditing: Reports can be used to perform regular security audits, allowing organizations to identify vulnerabilities and take corrective action.

bucketAV reports are delivered via email and contain the following information:

  • Statistics about scanned files: Number of files scanned, % of clean files, % of infected files, and % of unscannable files.
  • Top 10 threats.
  • CSV reports include all files or only infected and unscannable files.
  • Operational alarms to signal if bucketAV needs your attention.

Example report

The following shows an example report:

Reporting period: 2023-01-30 - 2023-02-05
AWS Region: eu-west-1
AWS Account ID: ***151466***
bucketAV Stack Name: bucketav
Add-On Stack Name: bucketav-reporting


==================================================
Overview
==================================================

358 scanned
49.16% clean
48.88% infected
1.96% unscannable


==================================================
Top 10 infections
==================================================

56x Win.Test.EICAR_HDB-1
35x Doc.Malware.Prince-6784184-0
7x Doc.Dropper.Agent-6460256-0
7x Doc.Dropper.Agent-6496090-0
7x Xls.Dropper.Agent-7505951-0
7x Doc.Dropper.Agent-6361752-0
7x Doc.Dropper.Agent-6507997-0
7x Doc.Dropper.Agent-6997781-0
7x Doc.Dropper.Agent-6488415-0
7x Doc.Dropper.Agent-6609394-0


==================================================
Top 10 buckets
==================================================

bucketav-demo
307 scanned
49.19% clean
48.86% infected
1.95% unscannable

bucketav-demo2
51 scanned
49.02% clean
49.02% infected
1.96% unscannable


==================================================
CSV reports
==================================================

The following CSV reports are available for 27 days:
Infected & unscannable files: <Link to Amazon S3>
All files: <Link to Amazon S3>

CSV example

The following columns are available:

  • timestamp: ISO 8601 format
  • bucket: Name of bucket
  • key: Object key
  • version: Object version or null for unversioned buckets
  • status: clean, infected, no
  • action: delete, tag, no
  • finding: The type of malware detected or Unknown

The following shows an example data set:

"timestamp","bucket","key","version","status","action","finding"
"2023-01-30T20:19:00.051Z","bucketav-demo","clean.xlxs","null","clean","tag","Unknown"
"2023-01-30T20:19:23.674Z","bucketav-demo","infected.pdf","null","infected","delete","Win.Test.EICAR_HDB-1"
"2023-01-31T20:20:10.074Z","bucketav-demo","encrypted.pdf","null","no","tag","Heuristics.Encrypted.PDF"

Setup

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

The ReportCleanFiles configuration parameter must be set to true.

Scan results start being recorded as soon as you install the Add-On.

Install Add-On (requires a running bucketAV installation)

  1. Set the Stack name to bucketav-reporting.
  2. Set the BucketAVStackName parameter to the stack name of bucketAV (if you followed the docs, the name is bucketav).
  3. Set the ReportReceiver1 parameter to your email address.
  4. By default, the ReportingFrequency is set to weekly. Change that if needed.
  5. Select I acknowledge that AWS CloudFormation might create IAM resources.
  6. Click on the Create stack button to save.
  7. You will receive an email (subject: AWS Notification - Subscription Confirmation) with a confirmation link that you have to visit.

Scan results start being recorded as soon as you install the Add-On.

Install Add-On (requires a running bucketAV installation)

  1. Set the Stack name to bucketav-reporting.
  2. Set the BucketAVStackName parameter to the stack name of bucketAV (if you followed the docs, the name is bucketav).
  3. Set the ReportReceiver1 parameter to your email address.
  4. By default, the ReportingFrequency is set to weekly. Change that if needed.
  5. Select I acknowledge that AWS CloudFormation might create IAM resources.
  6. Click on the Create stack button to save.
  7. You will receive an email (subject: AWS Notification - Subscription Confirmation) with a confirmation link that you have to visit.

Run Lambda in a VPC

By default, the add-on deploys Lambda functions with access to the Internet. In case you want to deploy the Lambda functions into a VPC, configure the LambdaVpc and LambdaSubnets parameters.

The add-on requires access to the following endpoints (replace REGION with the AWS region like eu-west-1):

https://s3.REGION.amazonaws.com
https://sns.REGION.amazonaws.com
https://monitoring.REGION.amazonaws.com
https://ssm.REGION.amazonaws.com

Ensure that the subnets configured in the LambdaSubnets parameter have access to these endpoints via a NAT Gateway or VPC Endpoints.

CloudFormation snippet

# [...]
Resources:
  # [...]
  Reporting:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        BucketAVStackName: 'bucketav' # if you followed the docs, the name is bucketav
        ReportReceiver1: 'name@domain.todo' # TODO replace email address
      TemplateURL: 'https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.19.0/bucketav-add-on-reporting.yaml'

# [...]
Resources:
  # [...]
  Reporting:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        BucketAVStackName: 'bucketav' # if you followed the docs, the name is bucketav
        ReportReceiver1: 'name@domain.todo' # TODO replace email address
      TemplateURL: 'https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/cloudflare/v2.19.0/bucketav-add-on-reporting-cloudflare.yaml'

Terraform snippet

resource "aws_cloudformation_stack" "bucketav_add_on_reporting" {
  name         = "bucketav-reporting"
  template_url = "https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.19.0/bucketav-add-on-reporting.yaml"
  capabilities = ["CAPABILITY_IAM"]
  parameters = {
    BucketAVStackName = "bucketav" # if you followed the docs, the name is bucketav
    ReportReceiver1   = "name@domain.todo" # TODO replace email address
  }
}

resource "aws_cloudformation_stack" "bucketav_add_on_reporting" {
  name         = "bucketav-reporting"
  template_url = "https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/cloudflare/v2.19.0/bucketav-add-on-reporting-cloudflare.yaml"
  capabilities = ["CAPABILITY_IAM"]
  parameters = {
    BucketAVStackName = "bucketav" # if you followed the docs, the name is bucketav
    ReportReceiver1   = "name@domain.todo" # TODO replace email address
  }
}

Update

Which version am I using?

  1. To update this Add-On to version v2.19.0, go to the AWS CloudFormation Management Console.
  2. Double-check the region at the top right.
  3. Search for bucketav-reporting, otherwise search for the name you specified.
  4. Select the stack and press the Update stack button; press Make a direct update.
  5. Select Replace existing template and set the Amazon S3 URL to https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.19.0/bucketav-add-on-reporting.yaml Copy
  6. Click on Next.
  7. Scroll to the bottom of the page and click on Next.
  8. Scroll to the bottom of the page, enable I acknowledge that AWS CloudFormation might create IAM resources, and click on Next.
  9. Scroll to the bottom of the page and click on Submit.
  10. While the update runs, the stack status is UPDATE_IN_PROGRES. Reload the table from time to time and …
  11. … wait until the CloudFormation stack status switches to UPDATE_COMPLETE.
  1. To update this Add-On to version v2.19.0, go to the AWS CloudFormation Management Console.
  2. Double-check the region at the top right.
  3. Search for bucketav-reporting, otherwise search for the name you specified.
  4. Select the stack and press the Update stack button; press Make a direct update.
  5. Select Replace existing template and set the Amazon S3 URL to https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/cloudflare/v2.19.0/bucketav-add-on-reporting-cloudflare.yaml Copy
  6. Click on Next.
  7. Scroll to the bottom of the page and click on Next.
  8. Scroll to the bottom of the page, enable I acknowledge that AWS CloudFormation might create IAM resources, and click on Next.
  9. Scroll to the bottom of the page and click on Submit.
  10. While the update runs, the stack status is UPDATE_IN_PROGRES. Reload the table from time to time and …
  11. … wait until the CloudFormation stack status switches to UPDATE_COMPLETE.

Architecture

The following AWS services are used:

  • SNS Subscription to connect to the Findings Topic.
  • Kinesis Firehose Delivery Stream to store the messages from SNS on S3.
  • Athena to generate CSV files.
  • S3 Bucket to store the data and reports.
  • StepFunction State Machine to orchestrate report generation.
  • Lambda Function to send out the report email.
  • EventBridge Cron Rule to trigger the report daily/weekly/monthly.
  • SNS Topic & Subscription to send out report emails.
  • CloudWatch Alarms to monitor the used AWS services.
  • CloudWatch Logs to store logs.

On-demand report

Requires version >= 2.9.0 of this Add-On. To update to the latest version, follow the update instructions.

If you need a report now, follow these steps:

  1. Follow the setup instructions.
  2. Visit the AWS Step Functions Management Console.
  3. Ensure that you are in the correct region.
  4. Navigate to State machines.
  5. Click on the reporting state machine (if you followed the docs, the name is bucketav-reporting).
  6. Click the Start execution button.
  7. Keep the defaults and click the Start execution button.
  8. Wait for the Execution Status to switch to Succeeded (this can take a few minutes).

Release Notes

Subscribe to our Atom feed or newsletter to stay up-to-date! We also publish a machine-readable JSON file.

v2.19.0

Changes:

  • Fix VPC config for Lambda function StateMachineNameGeneratorFunction

Release date:2025-05-22

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.19.0/bucketav-add-on-reporting.yaml

v2.18.0

Changes:

  • Optionally run Lambda functions in a VPC

Release date:2025-04-15

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.18.0/bucketav-add-on-reporting.yaml

v2.17.0

Changes:

  • Comply with SecurityHub Control [StepFunctions.1] Step Functions state machines should have logging turned on
  • Enrich CSV with Real File Type
  • Update Lambda Node.js runtime to version 22

Release date:2025-01-25

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.17.0/bucketav-add-on-reporting.yaml

v2.16.0

Changes:

  • Save HTML report
  • Comply with AWS Security Hub Control [Athena.4] Athena workgroups should have logging enabled

Release date:2025-01-25

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.16.0/bucketav-add-on-reporting.yaml

v2.15.0

Changes:

  • Reserved Concurrent Execution for Lambda functions

Release date:2024-11-19

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.15.0/bucketav-add-on-reporting.yaml

v2.14.1

Changes:

  • Bug fixes

Release date:2024-09-27

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.14.1/bucketav-add-on-reporting.yaml

v2.14.0

Changes:

  • Add parameters to configure report hour of day and day of week

Release date:2024-08-11

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.14.0/bucketav-add-on-reporting.yaml

v2.13.0

Changes:

  • Enable SSE on Amazon Data Firehose stream

Release date:2024-07-17

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.13.0/bucketav-add-on-reporting.yaml

v2.12.1

Changes:

  • Bug fixes

Release date:2024-07-09

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.12.1/bucketav-add-on-reporting.yaml

v2.12.0

Changes:

  • Update Lambda runtime to Node.js 20

Release date:2024-02-14

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.12.0/bucketav-add-on-reporting.yaml

v2.11.0

Changes:

  • Add Service Discovery

Release date:2023-12-07

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.11.0/bucketav-add-on-reporting.yaml

v2.10.0

Changes:

  • Support for bucket scan report

Release date:2023-09-14

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.10.0/bucketav-add-on-reporting.yaml

v2.9.0

Changes:

  • Update Lambda runtime to Node.js 18

Release date:2023-08-30

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.9.0/bucketav-add-on-reporting.yaml

v2.8.0

Changes:

  • Support on-demand reports

Release date:2023-08-24

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.8.0/bucketav-add-on-reporting.yaml

v2.7.0

Changes:

  • Update Athena engine to version 3

Release date:2023-03-31

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.7.0/bucketav-add-on-reporting.yaml

v2.6.0

Changes:

  • Improve table and text

Release date:2023-01-30

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.6.0/bucketav-add-on-reporting.yaml

v2.5.0

Changes:

  • Harden S3 config
  • Performance improvements

Release date:2022-11-08

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.5.0/bucketav-add-on-reporting.yaml

v2.4.0

Changes:

  • Update Lambda runtime to Node.js 16

Release date:2022-06-08

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.4.0/bucketav-add-on-reporting.yaml

v2.3.0

Changes:

  • Comply with AWS Foundational Security Best Practices v1.0.0 S3.5 and S3.8

Release date:2022-05-12

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.3.0/bucketav-add-on-reporting.yaml

v2.2.2

Changes:

  • Improve Lambda config

Release date:2021-12-22

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.2.2/bucketav-add-on-reporting.yaml

v2.2.1

Changes:

  • Bug fixes

Release date:2021-10-04

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.2.1/bucketav-add-on-reporting.yaml

v2.2.0

Changes:

  • Improve report message

Release date:2021-09-30

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.2.0/bucketav-add-on-reporting.yaml

v2.1.1

Changes:

  • Bug fixes

Release date:2021-06-09

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.1.1/bucketav-add-on-reporting.yaml

v2.1.0

Changes:

  • Add AWS context and top buckets to report

Release date:2021-06-07

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.1.0/bucketav-add-on-reporting.yaml

v2.0.0

Changes:

  • Initial release

Release date:2021-06-06

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/v2.0.0/bucketav-add-on-reporting.yaml

Subscribe to our Atom feed or newsletter to stay up-to-date! We also publish a machine-readable JSON file.

v2.19.0

Changes:

  • Fix VPC config for Lambda function StateMachineNameGeneratorFunction

Release date:2025-05-22

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/cloudflare/v2.19.0/bucketav-add-on-reporting-cloudflare.yaml

v2.18.0

Changes:

  • Optionally run Lambda functions in a VPC

Release date:2025-04-15

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/cloudflare/v2.18.0/bucketav-add-on-reporting-cloudflare.yaml

v2.17.0

Changes:

  • Comply with SecurityHub Control [StepFunctions.1] Step Functions state machines should have logging turned on
  • Enrich CSV with Real File Type
  • Update Lambda Node.js runtime to version 22

Release date:2025-01-25

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/cloudflare/v2.17.0/bucketav-add-on-reporting-cloudflare.yaml

v2.16.0

Changes:

  • Save HTML report
  • Comply with AWS Security Hub Control [Athena.4] Athena workgroups should have logging enabled

Release date:2025-01-25

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/cloudflare/v2.16.0/bucketav-add-on-reporting-cloudflare.yaml

v2.15.0

Changes:

  • Reserved Concurrent Execution for Lambda functions

Release date:2024-11-19

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/cloudflare/v2.15.0/bucketav-add-on-reporting-cloudflare.yaml

v2.14.1

Changes:

  • Bug fixes

Release date:2024-09-27

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/cloudflare/v2.14.1/bucketav-add-on-reporting-cloudflare.yaml

v2.14.0

Changes:

  • Add parameters to configure report hour of day and day of week

Release date:2024-08-11

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/cloudflare/v2.14.0/bucketav-add-on-reporting-cloudflare.yaml

v2.13.0

Changes:

  • Enable SSE on Amazon Data Firehose stream

Release date:2024-07-17

Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/reporting/cloudflare/v2.13.0/bucketav-add-on-reporting-cloudflare.yaml

Need more help?

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

Send us an email