FAQ

What happened to VirusScan for Amazon S3?

bucketAV - formerly known as S3 Virusscan for Amazon S3 was rebranded in June 2021. The owner stays the same. The functionality remains the same. We just changed the name and reworked the website. Read more about this.

Are my files secure?

All files are scanned on EC2 instances (virtual machines) that run in your AWS account. All infrastructure runs in your AWS account. Only the virus database is fetched from remote servers provided by ClamAV®. We don’t have access to your data and infrastructure.

Can you explain the pricing in more detail?

You don’t pay for the individual files or volume of files that are scanned.

Three dimensions are important: bucketAV Software, AWS Infrastructure, and S3 API.

bucketAV Software: Charged hourly based on the running EC2 instances that scan your files. Get the hourly fee for each supported instance type on the AWS Marketplace .

AWS Infrastructure: The main cost driver is the number of EC2 instances running to scan your files. By default, one m5.large instance is allowed to run. Besides that, you also pay the usual AWS charges for EBS, SNS, SQS, CloudWatch.

S3 API: AWS charges every API call made to the S3 service. Typical API calls are: GetObject, DeleteObject, GetObjectTagging, and PutObjectTagging. Keep in mind that you also pay a monthly fee for every tag.

You only pay for bucketAV while EC2 instances are running. As soon as you uninstall bucketAV, you stop paying for it.

Use our pricing page to calculate your costs.

What’s the maximum file size supported?

ClamAV® can scan files up to 4.2GB in size. The file has to fit into memory as well. Our recommended instance type m5.large comes with enough memory to scan files up to 4.2GB in size.

How can I test the solution with an EICAR test file?

The EICAR test file is the gold standard to test antivirus solutions. Unfortunately, your local antivirus solution on your computer will likely quarantine the EICAR test file before you can upload it to S3. The following steps upload an EICAR test file outside of your local machine.

  1. Open a AWS CloudShell .
  2. Ensure that you are in the correct region where bucketAV runs.
  3. Execute the following commands (replace YOUR_BUCKET_NAME with your S3 bucket name):
    • aws s3 cp s3://bucketav-eicar/deleteme.txt s3://YOUR_BUCKET_NAME Copy
    • aws s3 cp s3://bucketav-eicar/eicar.com s3://YOUR_BUCKET_NAME Copy Step 1
  4. Visit the AWS S3 Console .
  5. Open your S3 bucket (the one you used instead of YOUR_BUCKET_NAME).
  6. You will see a single file deleteme.txt. Open the file details to see the clean tag. Step 2
  7. The eicar.com file was deleted and is therefore not visible.
  8. Delete the deleteme.txt file from your bucket.

My Scan Queue contains many messages and/or is growing steadily. How can I increase the throughput of the system?

By default, the AutoScalingMinSize and AutoScalingMaxSize parameters are set to 1. Therefore, you will only have one worker running to scan files. If you increase AutoScalingMaxSize, the solution will scale out if the Scan Queue grows and scales in if the Scan Queue is empty. The defaults are low to protect your AWS bill.

If the InstanceType parameter is set to t3.* or t3a.*, you should consider changing to m5.* before you scale out by increasing AutoScalingMaxSize.

  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 our docs, the name is bucketav, or s3-virusscan for older installations).
  5. At the top right, click on Update.
  6. In the next step, just click Next.
  7. Increase the AutoScalingMaxSize parameter.
  8. Click Next.
  9. In the next step, just click Next.
  10. At the bottom, check “I acknowledge that AWS CloudFormation might create IAM resources.” and click Update stack.

I already created an S3 Event Notification; how can I still use bucketAV?

Requires bucketAV version >= 1.4.0. To update to the latest version, follow our Update Guide.

Each bucket can only have one S3 Event notification to inform about newly created files. If multiple systems are interested in this information, you need to follow a fan-out approach. Instead of configuring S3 to send events to SQS, you can create an SNS topic and configure S3 to publish events to the SNS topic . You can add as many subscribers to this topic as you wish. Each subscriber will get a copy of the events published from S3.

If you already have your SNS topic created, you can skip this step. Otherwise, create an SNS topic in the same AWS account and region as your S3 bucket.

  1. Visit the Amazon SNS Console .
  2. Ensure that you are in the correct region.
  3. Navigate to Topics.
  4. Click on Create topic.
  5. Select Type Standard.
  6. Set a Name.
  7. Open the Access policy box, select Advanced, and enter the following policy:
  • Replace REGION with AWS Region (e.g., us-east-1; get the value from the top right).
  • Replace ACCOUNT_ID with your AWS account id .
  • Replace TOPIC_NAME with the name of the topic that you created before.
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
        "AWS": "*"
    },
    "Action": "SNS:Publish",
    "Resource": "arn:aws:sns:REGION:ACCOUNT_ID:TOPIC_NAME",
    "Condition": {
      "StringEquals": {
        "aws:SourceAccount": "ACCOUNT_ID"
      }
    }
  }]
}
  1. Click on Create topic to save.
  2. In the AWS S3 Management Console , click on the bucket you want to connect to bucketAV. Make sure the bucket’s region matches the bucketAV region.
  3. Click on the Properties tab.
  4. Scroll down to the Event notifications.
  5. Click on Create event notification.
  6. Set the Event Name (e.g., bucketav) and select the All objects create events event type.
  7. Select the destination SNS topic and choose the SNS Topic that you created before.
  8. Click on Save changes.

To connect bucketAV to your SNS topic:

  1. Visit the Amazon SNS Console
  2. Ensure that you are in the correct region.
  3. Navigate to Topics.
  4. Click on the SNS topic that you created before.
  5. Click on Create subscription.
  6. Set the Protocol to Amazon SQS.
  7. Set the Endpoint to:
    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 our docs, the name is bucketav, or s3-virusscan for older installations).
    5. Click on the Outputs tab.
    6. Use the value next to the output key ScanQueueArn.
  8. Click on Create subscription to save.

How can I change the instance type?

By default, the InstanceType parameter is set to m5.large. You can reduce costs in small environments or development environments by switching to the t3 or t3a family.

Keep in mind that a larger instance is not the only option to increase the system’s throughput. You can also increase the maximum number of instances scanning your files by increasing the AutoScalingMaxSize parameter!

  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 our docs, the name is bucketav, or s3-virusscan for older installations).
  5. At the top right, click on Update.
  6. In the next step, just click Next.
  7. Change the InstanceType parameter.
  8. Click Next.
  9. In the next step, just click Next.
  10. At the bottom, check “I acknowledge that AWS CloudFormation might create IAM resources.” and click Update stack.
  11. Wait for the stack update to complete.
  12. Terminate all running bucketAV EC2 instances (if you followed our docs, the name is bucketav, or s3-virusscan for older installations). The terminated EC2 instances will be replaced within minutes.

How can I receive an email for every infected file?

  1. Visit the Amazon SNS Console .
  2. Ensure that you are in the correct region.
  3. Navigate to Topics.
  4. Search for FindingsTopic and click on the found topic.
  5. Click on the Create subscription button.

SNS E-Mail subscription

  1. Set Protocol to Email.
  2. Set Endpoint to your email address.
  3. Set Subscription filter policy to {"status": ["infected", "no"]}
  4. Click on the Create subscription button to save.

You will receive an email (subject: AWS Notification - Subscription Confirmation) with a confirmation link that you have to visit.

If the volume of emails is too high, consider: How can I receive an email if infected files are found?

How can I receive an email if infected files are found?

Sometimes, it is enough to be notified if infected files are found without sending an email for every infected file. Our Reporting Add-On helps you with the setup.

How can I quarantine infected files?

You can move infected files into a quarantine bucket with our Quarantine infected files Add-On.

How can I move clean files into a secure bucket?

You can move clan files into a target bucket with our Move clean files Add-On.

What reporting capabilities are available?

Our Reporting Add-On generates daily, weekly, or monthly CSV reports.

How can I scan files before users can download them?

The easiest way to ensure that only clean files can be download by users is to use two buckets—one for uploads and one for downloads. Our Move Clean Files Add-On moves files once they are scanned.

move-clean

The other, more challenging approach is to only allow downloads from the public if the file is tagged with bucketav=clean using a bucket policy.

  • Replace BUCKET_NAME with the name of the S3 bucket.
{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "bucketAVAllowClean",
    "Effect": "Allow",
    "Principal": "*",
    "Action": "s3:GetObject*",
    "Resource": "arn:aws:s3BUCKET_NAME/*",
    "Condition": {
      "StringEquals": {
        "s3:ExistingObjectTag/bucketav": "clean"
      }
    }
  }
}

How can I keep infected files?

By default, infected files are deleted. You can keep and tag them as infected if you want.

  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 our docs, the name is bucketav, or s3-virusscan for older installations).
  5. At the top right, click on Update.
  6. In the next step, just click Next.
  7. Set the DeleteInfectedFiles parameter to false.
  8. Click Next.
  9. In the next step, just click Next.
  10. At the bottom, check “I acknowledge that AWS CloudFormation might create IAM resources.” and click Update stack.

My SSH connection is not working; what’s wrong?

By default, sshd is running. But you have to whitelist your IP address/range. To do so:

  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 our docs, the name is bucketav, or s3-virusscan for older installations).
  5. At the top right, click on Update.
  6. In the next step, just click Next.
  7. Set the SSHIngressCidrIp parameter to:
  8. Click Next.
  9. In the next step, just click Next.
  10. At the bottom, check “I acknowledge that AWS CloudFormation might create IAM resources.” and click Update stack.

Now, you can connect to the EC2 instances via SSH.

Alternatively, you can set the SystemsManagerAccess parameter to true and use AWS Systems Manager Session Manager to connect to the instance:

  1. Visit the Amazon EC2 Console .
  2. Ensure that you are in the correct region.
  3. Navigate to Instances.
  4. Select the instance and choose Connect.
  5. For Connection method, choose Session Manager.
  6. Click Connect.

Which version am I using?

To find the running version of bucketAV:

  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 our docs, the name is bucketav, or s3-virusscan for older installations).
  5. Click on the Outputs tab.
  6. Check the value next to the output key Version.

What’s my configuration?

bucketAV is configured via AWS CloudFormation. To find out the current settings:

  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 our docs, the name is bucketav, or s3-virusscan for older installations).
  5. Click on the Parameters tab.

Now, you can see the parameters and values that are used to configure bucketAV.

How can I edit the configuration?

bucketAV is configured via AWS CloudFormation. To change the configuration of bucketAV:

  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 our docs, the name is bucketav, or s3-virusscan for older installations).
  5. At the top right, click on Update.
  6. In the next step, just click Next.
  7. Now, you can change the parameters.
  8. Click Next.
  9. In the next step, just click Next.
  10. At the bottom, check “I acknowledge that AWS CloudFormation might create IAM resources.” and click Update stack.

It can take several minutes for an update to finish!

How can I receive SNS messages for infected files only?

By default, the ReportCleanFiles parameter is set to true. If you subscribe to the findings SNS topic, you will receive messages for status: infected, clean, and no.

Option 1 (recommended)

In your SNS subscription, add a subscription filter policy only to receive messages where the attribute status is set to infected. You might be interested in no as well, e.g., the file was too big to scan.

{"status": ["infected", "no"]}

Option 2 (deprecated)

This option is deprecated. Please use option 1 instead!

  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 our docs, the name is bucketav, or s3-virusscan for older installations).
  5. At the top right, click on Update.
  6. In the next step, just click Next.
  7. Change the ReportCleanFiles parameter to false.
  8. Click Next.
  9. In the next step, just click Next.
  10. At the bottom, check “I acknowledge that AWS CloudFormation might create IAM resources.” and click Update stack.

Does the solution work in Cross- / Multi-Account setups?

Yes. If you have a multi-account setup, you might want to run the bucketAV solution in a single AWS account (account a) while you can scan buckets created in accounts b and c.

We recommend running the bucketAV solution in the same account as your S3 buckets to keep the configuration overhead to a minimum.

Whitelist accounts b and c by modifying the AWSAccountRestriction parameter in your bucketAV stack in account a.

Add the following bucket policy statements to each S3 bucket in accounts b and c to allow bucketAV from account a to access the buckets in b and c.

  • Replace ROLE_ARN with the ScanRoleArn output of the CloudFormation bucketav stack from account a.
  • Replace BUCKET_NAME with the name of the S3 bucket.
{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "bucketAVRequired1",
    "Effect": "Allow",
    "Principal": {
      "AWS": "ROLE_ARN"
    },
    "Action": "s3:ListBucket*",
    "Resource": "arn:aws:s3BUCKET_NAME"
  }, {
    "Sid": "bucketAVRequired2",
    "Effect": "Allow",
    "Principal": {
      "AWS": "ROLE_ARN"
    },
    "Action": "s3:GetObject*",
    "Resource": "arn:aws:s3BUCKET_NAME/*"
  }, {
    "Sid": "bucketAVOnlyIfYouDeleteInfectedFiles",
    "Effect": "Allow",
    "Principal": {
      "AWS": "ROLE_ARN"
    },
    "Action": "s3:DeleteObject*",
    "Resource": "arn:aws:s3BUCKET_NAME/*"
  }, {
    "Sid": "bucketAVOnlyIfYouTagFilesWithScanResult",
    "Effect": "Allow",
    "Principal": {
      "AWS": "ROLE_ARN"
    },
    "Action": [
      "s3:GetObjectTagging",
      "s3:GetObjectVersionTagging",
      "s3:PutObjectTagging",
      "s3:PutObjectVersionTagging"
    ],
    "Resource": "arn:aws:s3BUCKET_NAME/*"
  }]
}

If you use SSE-KMS to encrypt your buckets, you must ensure that the KMS Key Policy allows access from the ScanRoleArn. If you use AWS-managed KMS CMKs, you can not edit the key policy. Therefore, only customer-managed CMKs are supported.

One specialty needs to be considered when you configure the S3 Bucket Event Notification according to the Setup Guide. Instead of selecting the SQS queue from the drop-down, select Add SQS queue ARN and enter the ScanQueueArn output of the CloudFormation bucketav stack from account a.

How can I be notified if a new release becomes available?

Subscribe to our Atom feed or newsletter to stay up-to-date!

What’s the SNS message format for findings?

Scan results are published to the Findings Topic. The topic name is prefixed by the CloudFormation stack name you defined during setup (if you followed our docs, the prefix is bucketav, or s3-virusscan for older installations).

The following message attributes are part of every message:

  • bucket: The bucket name (string)
  • key: The object key (string)
  • version: The object version if versioning is turned on (string, optional)
  • status: The scan result (string (clean, infected, no))
  • action: The action that was taken (string (delete, tag, no))
  • finding: For infected files, the type of virus/malware that was detected (string, optional, since version 1.7.0)

What’s the SQS message format to submit scan jobs?

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 our docs, the prefix is bucketav, or s3-virusscan for older installations).

The following message body is expected (a subset of the official 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.

EC2 Instance launch failure: Client.InternalError: Client error on launch

If no EC2 instances are started, and the Auto Scaling Group shows the error “Client.InternalError: Client error on launch” it is likely an issue with your KMS key that you use for EBS default encryption . Please modify the KMS key policy of your KMS key used for default encryption. The EC2 Instances will start after a couple of minutes.

ScanQueueEmptyAlarm and ScanQueueFullAlarm

Don’t be worried by the alarms ScanQueueEmptyAlarm and ScanQueueFullAlarm. They are used to trigger auto-scaling policies. To hide those alarms, in the CloudWatch Management Console, select Hide Auto Scaling alarms.

Hide Auto Scaling alarms

Required outbound ports

The only outbound port that is required is TCP/443. If you use Delivery Method Existing VPC in a VPC with enableDnsSupport set to false, you also have to allow TCP/53 and UDP/53.

The following outbound requests are made (replace REGION with AWS Region, e.g., us-east-1; get the value from the top right).

  • https://database.clamav.net to update the threat database.
  • https://sns.REGION.amazonaws.com: SNS API to publish scan results to the Findings Topic.
  • https://sqs.REGION.amazonaws.com: SQS API to read from the Scan Queue.
  • https://s3.REGION.amazonaws.com: S3 API to interact with files; also required for cfn-init and cfn-signal tools.
  • https://s3.amazonaws.com: S3 API to interact with files; also required for cfn-init and cfn-signal tools.
  • https://monitoring.REGION.amazonaws.com: CloudWatch API to publish memory, disk, and swap metrics.
  • https://logs.REGION.amazonaws.com: CloudWatch Logs API to publish logs.
  • https://cloudformation.REGION.amazonaws.com: CloudFormation API required for cfn-init and cfn-signal tools.
  • https://ssm.REGION.amazonaws.com: SSM API for Session Manager (if SystemsManagerAccess is set to true).
  • https://ssmmessages.REGION.amazonaws.com: SSM API for Session Manager (if SystemsManagerAccess is set to true).
  • https://ec2messages.REGION.amazonaws.com: SSM API for Session Manager (if SystemsManagerAccess is set to true).

You can’t restrict the IP address range. The resolved IP addresses change frequently.

All those DNS names must be resolvable. Additionally, the name current.cvd.clamav.net is resolved.

How to run a performance test?

The scan time depends heavily on file size, file type, and file content. To get accurate throughput numbers for your particular workload, we recommend running a performance test described in the following.

  1. Install bucketAV by following our Setup Guide using the default values.
  2. Generate load by installing our Scan bucket at regular intervals add-on.
    1. Install Add-On
    2. Set the Stack name to bucketav-performance-test.
    3. Set the BucketAVStackName parameter to the stack name of bucketAV (if you followed our docs, the name is bucketav, or s3-virusscan for older installations).
    4. Set the BucketName parameter to the name of an S3 bucket that contains at least 10,000 files. Keep in mind that infected files will be deleted by default!
    5. Set the ScheduleExpression parameter to a value in 10 minutes from now (UTC timezone ) by using the expression cron(mm hh dd MM ? yyyy) filled with:
      1. mm: Minute (0-59).
      2. hh: Hour (0-23).
      3. dd: Day (1-31).
      4. MM: Month (1-12).
      5. ?: Please leave the question mark as it is.
      6. yyyy: Year (1970-2199).
    6. Set the PagingBatchSize parameter to 1000.
    7. Set the PagingWaitInSeconds parameter to 0.
    8. Select I acknowledge that AWS CloudFormation might create IAM resources.
    9. Click on the Create stack button to save.
  3. Within the next 10 minutes, your Scan Queue should grow. You can observe that in the CloudWatch Dashboard . Select the dashboard (if you followed our docs, the name is bucketav-${region}). The Scan Queue tile shows the data of interest. You should see the Queue Length go up.
  4. Wait another 15 minutes to capture data.
  5. Reload the dashboard. In the Scan Queue tile, click on the Files processed legend. Now you only see the metric of importance. Zoom into the area of interest. Now you see the number of files scanned per minute (axis on the right). This is the throughput of one m5.large EC2 instance for your workload. Scan Queue tile
  6. To clean up, remove the CloudFormation stack named bucketav-performance-test.

Uninstall bucketAV

Uninstalling bucketAV does not delete your files stored on S3.

  1. Visit the AWS CloudFormation Console .
  2. Ensure that you are in the correct region.
  3. Navigate to Stacks.
  4. If you use our add-ons, uninstall them in the same way as described next.
  5. Click on the bucketAV stack (if you followed our docs, the name is bucketav, or s3-virusscan for older installations).
  6. At the top right, click on Delete.

After deleting the stack, you can cancel your AWS Marketplace subscription:

  1. Visit the AWS Marketplace Console .
  2. Click on the bucketAV subscription.
  3. Click on Actions and Cancel subscription.

Known issues

  • RAR files are not supported and not flagged as infected.

Need more help?

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

Send us an email