Skip to content

Latest commit

 

History

History
163 lines (103 loc) · 10.6 KB

API.md

File metadata and controls

163 lines (103 loc) · 10.6 KB
Raw

API Reference

Classes

Name Description
ServerlessClamscan An aws-cdk construct that uses ClamAV®. to scan objects in Amazon S3 for viruses. The construct provides a flexible interface for a system to act based on the results of a ClamAV virus scan.

Structs

Name Description
ServerlessClamscanLoggingProps Interface for ServerlessClamscan Virus Definitions S3 Bucket Logging.
ServerlessClamscanProps Interface for creating a ServerlessClamscan.

class ServerlessClamscan

An aws-cdk construct that uses ClamAV®. to scan objects in Amazon S3 for viruses. The construct provides a flexible interface for a system to act based on the results of a ClamAV virus scan.

The construct creates a Lambda function with EFS integration to support larger files. A VPC with isolated subnets, a S3 Gateway endpoint will also be created.

Additionally creates an twice-daily job to download the latest ClamAV definition files to the Virus Definitions S3 Bucket by utilizing an EventBridge rule and a Lambda function and publishes CloudWatch Metrics to the 'serverless-clamscan' namespace.

Important O&M: When ClamAV publishes updates to the scanner you will see “Your ClamAV installation is OUTDATED” in your scan results. While the construct creates a system to keep the database definitions up to date, you must update the scanner to detect all the latest Viruses.

Update the docker images of the Lambda functions with the latest version of ClamAV by re-running cdk deploy.

Successful Scan Event format

{
    "source": "serverless-clamscan",
    "input_bucket": <input_bucket_name>,
    "input_key": <object_key>,
    "status": <"CLEAN"|"INFECTED"|"N/A">,
    "message": <scan_summary>,
  }

Note: The Virus Definitions bucket policy will likely cause a deletion error if you choose to delete the stack associated in the construct. However since the bucket itself gets deleted, you can delete the stack again to resolve the error.

Implements: IConstruct, IDependable Extends: Construct

Initializer

Creates a ServerlessClamscan construct.

new ServerlessClamscan(scope: Construct, id: string, props: ServerlessClamscanProps)
  • scope (Construct) The parent creating construct (usually this).
  • id (string) The construct's name.
  • props (ServerlessClamscanProps) A ServerlessClamscanProps interface.
    • acceptResponsibilityForUsingImportedBucket (boolean) Allows the use of imported buckets. Optional
    • buckets (Array<aws_s3.IBucket>) An optional list of S3 buckets to configure for ClamAV Virus Scanning; Optional
    • defsBucketAccessLogsConfig (ServerlessClamscanLoggingProps) Whether or not to enable Access Logging for the Virus Definitions bucket, you can specify an existing bucket and prefix (Default: Creates a new S3 Bucket for access logs). Optional
    • efsEncryption (boolean) Whether or not to enable encryption on EFS filesystem (Default: enabled). Optional
    • efsPerformanceMode (aws_efs.PerformanceMode) Set the performance mode of the EFS file system (Default: GENERAL_PURPOSE). Optional
    • onError (aws_lambda.IDestination) The Lambda Destination for files that fail to scan and are marked 'ERROR' or stuck 'IN PROGRESS' due to a Lambda timeout (Default: Creates and publishes to a new SQS queue if unspecified). Optional
    • onResult (aws_lambda.IDestination) The Lambda Destination for files marked 'CLEAN' or 'INFECTED' based on the ClamAV Virus scan or 'N/A' for scans triggered by S3 folder creation events marked (Default: Creates and publishes to a new Event Bridge Bus if unspecified). Optional
    • reservedConcurrency (number) Optionally set a reserved concurrency for the virus scanning Lambda. Optional
    • scanFunctionMemorySize (number) Optionally set the memory allocation for the scan function. Optional

Properties

Name Type Description
errorDest aws_lambda.IDestination The Lambda Destination for failed on erred scans [ERROR, IN PROGRESS (If error is due to Lambda timeout)].
resultDest aws_lambda.IDestination The Lambda Destination for completed ClamAV scans [CLEAN, INFECTED].
scanAssumedPrincipal aws_iam.ArnPrincipal
cleanRule? aws_events.Rule Conditional: An Event Bridge Rule for files that are marked 'CLEAN' by ClamAV if a success destination was not specified.
Optional
defsAccessLogsBucket? aws_s3.IBucket Conditional: The Bucket for access logs for the virus definitions bucket if logging is enabled (defsBucketAccessLogsConfig).
Optional
errorDeadLetterQueue? aws_sqs.Queue Conditional: The SQS Dead Letter Queue for the errorQueue if a failure (onError) destination was not specified.
Optional
errorQueue? aws_sqs.Queue Conditional: The SQS Queue for erred scans if a failure (onError) destination was not specified.
Optional
infectedRule? aws_events.Rule Conditional: An Event Bridge Rule for files that are marked 'INFECTED' by ClamAV if a success destination was not specified.
Optional
resultBus? aws_events.EventBus Conditional: The Event Bridge Bus for completed ClamAV scans if a success (onResult) destination was not specified.
Optional
useImportedBuckets? boolean Conditional: When true, the user accepted the responsibility for using imported buckets.
Optional

Methods

addSourceBucket(bucket)

Sets the specified S3 Bucket as a s3:ObjectCreate* for the ClamAV function.

Grants the ClamAV function permissions to get and tag objects. Adds a bucket policy to disallow GetObject operations on files that are tagged 'IN PROGRESS', 'INFECTED', or 'ERROR'.

addSourceBucket(bucket: IBucket): void
  • bucket (aws_s3.IBucket) The bucket to add the scanning bucket policy and s3:ObjectCreate* trigger to.

getPolicyStatementForBucket(bucket)

Returns the statement that should be added to the bucket policy in order to prevent objects to be accessed when they are not clean or there have been scanning errors: this policy should be added manually if external buckets are passed to addSourceBucket().

getPolicyStatementForBucket(bucket: IBucket): PolicyStatement
  • bucket (aws_s3.IBucket) The bucket which you need to protect with the policy.

Returns:

struct ServerlessClamscanLoggingProps

Interface for ServerlessClamscan Virus Definitions S3 Bucket Logging.

Name Type Description
logsBucket? boolean | aws_s3.IBucket Destination bucket for the server access logs (Default: Creates a new S3 Bucket for access logs).
Optional
logsPrefix? string Optional log file prefix to use for the bucket's access logs, option is ignored if logs_bucket is set to false.
Optional

struct ServerlessClamscanProps

Interface for creating a ServerlessClamscan.

Name Type Description
acceptResponsibilityForUsingImportedBucket? boolean Allows the use of imported buckets.
Optional
buckets? Array<aws_s3.IBucket> An optional list of S3 buckets to configure for ClamAV Virus Scanning;
Optional
defsBucketAccessLogsConfig? ServerlessClamscanLoggingProps Whether or not to enable Access Logging for the Virus Definitions bucket, you can specify an existing bucket and prefix (Default: Creates a new S3 Bucket for access logs).
Optional
efsEncryption? boolean Whether or not to enable encryption on EFS filesystem (Default: enabled).
Optional
efsPerformanceMode? aws_efs.PerformanceMode Set the performance mode of the EFS file system (Default: GENERAL_PURPOSE).
Optional
onError? aws_lambda.IDestination The Lambda Destination for files that fail to scan and are marked 'ERROR' or stuck 'IN PROGRESS' due to a Lambda timeout (Default: Creates and publishes to a new SQS queue if unspecified).
Optional
onResult? aws_lambda.IDestination The Lambda Destination for files marked 'CLEAN' or 'INFECTED' based on the ClamAV Virus scan or 'N/A' for scans triggered by S3 folder creation events marked (Default: Creates and publishes to a new Event Bridge Bus if unspecified).
Optional
reservedConcurrency? number Optionally set a reserved concurrency for the virus scanning Lambda.
Optional
scanFunctionMemorySize? number Optionally set the memory allocation for the scan function.
Optional