# API Reference
## Constructs
### ServerlessClamscan
An [aws-cdk](https://github.com/aws/aws-cdk) construct that uses [ClamAV®](https://www.clamav.net/). 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
```json
{
"source": "serverless-clamscan",
"input_bucket": ,
"input_key": ,
"status": <"CLEAN"|"INFECTED"|"N/A">,
"message": ,
}
```
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
```typescript
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. |
---
##### `scope`Required
- *Type:* constructs.Construct
The parent creating construct (usually `this`).
---
##### `id`Required
- *Type:* string
The construct's name.
---
##### `props`Required
- *Type:* ServerlessClamscanProps
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`
```typescript
public toString(): string
```
Returns a string representation of this construct.
##### `addSourceBucket`
```typescript
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'.
###### `bucket`Required
- *Type:* aws-cdk-lib.aws_s3.IBucket
The bucket to add the scanning bucket policy and s3:ObjectCreate* trigger to.
---
##### `getPolicyStatementForBucket`
```typescript
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().
###### `bucket`Required
- *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`~~
```typescript
import { ServerlessClamscan } from 'cdk-serverless-clamscan'
ServerlessClamscan.isConstruct(x: any)
```
Checks if `x` is a construct.
###### `x`Required
- *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. |
---
##### `node`Required
```typescript
public readonly node: Node;
```
- *Type:* constructs.Node
The tree node.
---
##### `errorDest`Required
```typescript
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)].
---
##### `resultDest`Required
```typescript
public readonly resultDest: IDestination;
```
- *Type:* aws-cdk-lib.aws_lambda.IDestination
The Lambda Destination for completed ClamAV scans [CLEAN, INFECTED].
---
##### `scanAssumedPrincipal`Required
```typescript
public readonly scanAssumedPrincipal: ArnPrincipal;
```
- *Type:* aws-cdk-lib.aws_iam.ArnPrincipal
---
##### `cleanRule`Optional
```typescript
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.
---
##### `defsAccessLogsBucket`Optional
```typescript
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).
---
##### `errorDeadLetterQueue`Optional
```typescript
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.
---
##### `errorQueue`Optional
```typescript
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.
---
##### `infectedRule`Optional
```typescript
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.
---
##### `resultBus`Optional
```typescript
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.
---
##### `useImportedBuckets`Optional
```typescript
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
```typescript
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. |
---
##### `logsBucket`Optional
```typescript
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).
---
##### `logsPrefix`Optional
```typescript
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
```typescript
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. |
| scanFunctionTimeout | aws-cdk-lib.Duration | Optionally set the timeout for the scan function. |
---
##### `acceptResponsibilityForUsingImportedBucket`Optional
```typescript
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.
---
##### `buckets`Optional
```typescript
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.
---
##### `defsBucketAccessLogsConfig`Optional
```typescript
public readonly defsBucketAccessLogsConfig: ServerlessClamscanLoggingProps;
```
- *Type:* 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`Optional
```typescript
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.
---
##### `efsEncryption`Optional
```typescript
public readonly efsEncryption: boolean;
```
- *Type:* boolean
Whether or not to enable encryption on EFS filesystem (Default: enabled).
---
##### `efsPerformanceMode`Optional
```typescript
public readonly efsPerformanceMode: PerformanceMode;
```
- *Type:* aws-cdk-lib.aws_efs.PerformanceMode
Set the performance mode of the EFS file system (Default: GENERAL_PURPOSE).
---
##### `efsProvisionedThroughputPerSecond`Optional
```typescript
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).
---
##### `efsThroughputMode`Optional
```typescript
public readonly efsThroughputMode: ThroughputMode;
```
- *Type:* aws-cdk-lib.aws_efs.ThroughputMode
Set the throughput mode of the EFS file system (Default: BURSTING).
---
##### `onError`Optional
```typescript
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).
---
##### `onResult`Optional
```typescript
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).
---
##### `reservedConcurrency`Optional
```typescript
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](https://docs.aws.amazon.com/lambda/latest/operatorguide/reserved-concurrency.html)
---
##### `scanFunctionMemorySize`Optional
```typescript
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](https://docs.aws.amazon.com/lambda/latest/operatorguide/computing-power.html)
---
##### `scanFunctionTimeout`Optional
```typescript
public readonly scanFunctionTimeout: Duration;
```
- *Type:* aws-cdk-lib.Duration
Optionally set the timeout for the scan function.
(Default: 15 minutes).
---