Skip to content

Latest commit

 

History

History
544 lines (331 loc) · 23.7 KB

API.md

File metadata and controls

544 lines (331 loc) · 23.7 KB
Raw

API Reference

Constructs

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.

Initializers 

import { ServerlessClamscan } from 'cdk-serverless-clamscan'

new ServerlessClamscan(scope: Construct, id: string, props: ServerlessClamscanProps)
Name Type Description
scope constructs.Construct The parent creating construct (usually this).
id string The construct's name.
props ServerlessClamscanProps A ServerlessClamscanProps interface.
scopeRequired
  • Type: constructs.Construct

The parent creating construct (usually this).

idRequired
  • Type: string

The construct's name.

propsRequired

A ServerlessClamscanProps interface.

Methods

Name Description
toString Returns a string representation of this construct.
addSourceBucket Sets the specified S3 Bucket as a s3:ObjectCreate* for the ClamAV function.
getPolicyStatementForBucket 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().
toString 
public toString(): string

Returns a string representation of this construct.

addSourceBucket 
public addSourceBucket(bucket: IBucket): void

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'.

bucketRequired
  • Type: aws-cdk-lib.aws_s3.IBucket

The bucket to add the scanning bucket policy and s3:ObjectCreate* trigger to.

getPolicyStatementForBucket 
public getPolicyStatementForBucket(bucket: IBucket): PolicyStatement

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

bucketRequired
  • Type: aws-cdk-lib.aws_s3.IBucket

The bucket which you need to protect with the policy.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { ServerlessClamscan } from 'cdk-serverless-clamscan'

ServerlessClamscan.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

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

The tree node.

errorDestRequired 
public readonly errorDest: IDestination;
  • Type: aws-cdk-lib.aws_lambda.IDestination

The Lambda Destination for failed on erred scans [ERROR, IN PROGRESS (If error is due to Lambda timeout)].

resultDestRequired 
public readonly resultDest: IDestination;
  • Type: aws-cdk-lib.aws_lambda.IDestination

The Lambda Destination for completed ClamAV scans [CLEAN, INFECTED].

scanAssumedPrincipalRequired 
public readonly scanAssumedPrincipal: ArnPrincipal;
  • Type: aws-cdk-lib.aws_iam.ArnPrincipal
cleanRuleOptional 
public readonly cleanRule: Rule;
  • Type: aws-cdk-lib.aws_events.Rule

Conditional: An Event Bridge Rule for files that are marked 'CLEAN' by ClamAV if a success destination was not specified.

defsAccessLogsBucketOptional 
public readonly defsAccessLogsBucket: IBucket;
  • Type: aws-cdk-lib.aws_s3.IBucket

Conditional: The Bucket for access logs for the virus definitions bucket if logging is enabled (defsBucketAccessLogsConfig).

errorDeadLetterQueueOptional 
public readonly errorDeadLetterQueue: Queue;
  • Type: aws-cdk-lib.aws_sqs.Queue

Conditional: The SQS Dead Letter Queue for the errorQueue if a failure (onError) destination was not specified.

errorQueueOptional 
public readonly errorQueue: Queue;
  • Type: aws-cdk-lib.aws_sqs.Queue

Conditional: The SQS Queue for erred scans if a failure (onError) destination was not specified.

infectedRuleOptional 
public readonly infectedRule: Rule;
  • Type: aws-cdk-lib.aws_events.Rule

Conditional: An Event Bridge Rule for files that are marked 'INFECTED' by ClamAV if a success destination was not specified.

resultBusOptional 
public readonly resultBus: EventBus;
  • Type: aws-cdk-lib.aws_events.EventBus

Conditional: The Event Bridge Bus for completed ClamAV scans if a success (onResult) destination was not specified.

useImportedBucketsOptional 
public readonly useImportedBuckets: boolean;
  • Type: boolean

Conditional: When true, the user accepted the responsibility for using imported buckets.

Structs

ServerlessClamscanLoggingProps

Interface for ServerlessClamscan Virus Definitions S3 Bucket Logging.

Initializer 

import { ServerlessClamscanLoggingProps } from 'cdk-serverless-clamscan'

const serverlessClamscanLoggingProps: ServerlessClamscanLoggingProps = { ... }

Properties

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

Destination bucket for the server access logs (Default: Creates a new S3 Bucket for access logs).

logsPrefixOptional 
public readonly logsPrefix: string;
  • Type: string

Optional log file prefix to use for the bucket's access logs, option is ignored if logs_bucket is set to false.

ServerlessClamscanProps

Interface for creating a ServerlessClamscan.

Initializer 

import { ServerlessClamscanProps } from 'cdk-serverless-clamscan'

const serverlessClamscanProps: ServerlessClamscanProps = { ... }

Properties

Name Type Description
acceptResponsibilityForUsingImportedBucket boolean Allows the use of imported buckets.
buckets aws-cdk-lib.aws_s3.IBucket[] An optional list of S3 buckets to configure for ClamAV Virus Scanning;
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).
defsBucketAllowPolicyMutation boolean Allow for non-root users to modify/delete the bucket policy on the Virus Definitions bucket.
efsEncryption boolean Whether or not to enable encryption on EFS filesystem (Default: enabled).
efsPerformanceMode aws-cdk-lib.aws_efs.PerformanceMode Set the performance mode of the EFS file system (Default: GENERAL_PURPOSE).
efsProvisionedThroughputPerSecond aws-cdk-lib.Size Provisioned throughput for the EFS file system.
efsThroughputMode aws-cdk-lib.aws_efs.ThroughputMode Set the throughput mode of the EFS file system (Default: BURSTING).
onError aws-cdk-lib.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).
onResult aws-cdk-lib.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).
reservedConcurrency number Optionally set a reserved concurrency for the virus scanning Lambda.
scanFunctionMemorySize number Optionally set the memory allocation for the scan function.
acceptResponsibilityForUsingImportedBucketOptional 
public readonly acceptResponsibilityForUsingImportedBucket: boolean;
  • Type: boolean

Allows the use of imported buckets.

When using imported buckets the user is responsible for adding the required policy statement to the bucket policy: getPolicyStatementForBucket() can be used to retrieve the policy statement required by the solution.

bucketsOptional 
public readonly buckets: IBucket[];
  • Type: aws-cdk-lib.aws_s3.IBucket[]

An optional list of S3 buckets to configure for ClamAV Virus Scanning;

buckets can be added later by calling addSourceBucket.

defsBucketAccessLogsConfigOptional 
public readonly 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).

defsBucketAllowPolicyMutationOptional 
public readonly defsBucketAllowPolicyMutation: boolean;
  • Type: boolean
  • Default: false

Allow for non-root users to modify/delete the bucket policy on the Virus Definitions bucket.

Warning: changing this flag from 'false' to 'true' on existing deployments will cause updates to fail.

efsEncryptionOptional 
public readonly efsEncryption: boolean;
  • Type: boolean

Whether or not to enable encryption on EFS filesystem (Default: enabled).

efsPerformanceModeOptional 
public readonly efsPerformanceMode: PerformanceMode;
  • Type: aws-cdk-lib.aws_efs.PerformanceMode

Set the performance mode of the EFS file system (Default: GENERAL_PURPOSE).

efsProvisionedThroughputPerSecondOptional 
public readonly efsProvisionedThroughputPerSecond: Size;
  • Type: aws-cdk-lib.Size

Provisioned throughput for the EFS file system.

This is a required property if the throughput mode is set to PROVISIONED. Must be at least 1MiB/s (Default: none).

efsThroughputModeOptional 
public readonly efsThroughputMode: ThroughputMode;
  • Type: aws-cdk-lib.aws_efs.ThroughputMode

Set the throughput mode of the EFS file system (Default: BURSTING).

onErrorOptional 
public readonly onError: IDestination;
  • Type: aws-cdk-lib.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).

onResultOptional 
public readonly onResult: IDestination;
  • Type: aws-cdk-lib.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).

reservedConcurrencyOptional 
public readonly reservedConcurrency: number;
  • Type: number

Optionally set a reserved concurrency for the virus scanning Lambda.

https://docs.aws.amazon.com/lambda/latest/operatorguide/reserved-concurrency.html

scanFunctionMemorySizeOptional 
public readonly scanFunctionMemorySize: number;
  • Type: number

Optionally set the memory allocation for the scan function.

Note that low memory allocations may cause errors. (Default: 10240).

https://docs.aws.amazon.com/lambda/latest/operatorguide/computing-power.html