Skip to content

Latest commit

 

History

History
402 lines (251 loc) · 14.6 KB

API.md

File metadata and controls

402 lines (251 loc) · 14.6 KB

NPM version Release

cdk-ecr-image-scan-handler

Amazon ECR image scanning helps in identifying software vulnerabilities in your container images.

With this CDK construct you can get automated notifications from ECR images that contain security findings when the AWS ECR image scan finishes.

Usage

In your ECR repository setup, create a SNS topic:

  const onImageScanCompletedTopic = new sns.Topic(stack, 'RepositoryScanTopic', {
    topicName: 'ecr-repository-scan-completed-topic',
    displayName: 'Notifications about ECR Repository scans',
  });

Hook each ECR repository to report image scan results to the previously created topic:

  const ecrRepository = new ecr.Repository(stack, 'DemoEcrRepository', {
    repositoryName: name,
    imageScanOnPush: true,
  });
  ecrRepository.onImageScanCompleted('DemoScanCompleted', {
    target: new targets.SnsTopic(onImageScanCompletedTopic),
  });

Microsoft Teams reporting for ECR Image scan

To get notifications using Microsoft Teams Webhook, set up the handler for the previously created topic:

import { EcrImageScanTeamsWebhookHandler } from 'cdk-ecr-image-scan-handler';

const mockApp = new App();
const stack = new Stack(mockApp, 'app-stack');

new EcrImageScanTeamsWebhookHandler(stack, 'ecr-scan-result-handler', {
  webhookUrl: 'https://outlook.office.com/webhook/xxxxx',
  notificationTopicArn: 'arn:aws:sns:eu-central-1:112233445566:ecr-repository-scan-completed-topic',
});

Email results for ECR Image scan

To get reports via email, set up the handler for the previously created topic:

import { EcrImageScanResultHandler } from 'cdk-ecr-image-scan-handler';

const mockApp = new App();
const stack = new Stack(mockApp, 'app-stack');

new EcrImageScanResultHandler(stack, 'ecr-scan-result-handler', {
  fromAddress: 'from@address.com', // Use SES for validating the addresses
  toAddress: 'to@address.com',
  notificationTopicArn: 'arn:aws:sns:eu-central-1:112233445566:ecr-repository-scan-completed-topic',
});

API Reference

Constructs

EcrImageScanResultHandler

A construct for handling ECR image scan complete events and for reporting found vulnerabilities.

Initializers 

import { EcrImageScanResultHandler } from 'cdk-ecr-image-scan-handler'

new EcrImageScanResultHandler(scope: Construct, id: string, props: EcrImageScanResultHandlerProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props EcrImageScanResultHandlerProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { EcrImageScanResultHandler } from 'cdk-ecr-image-scan-handler'

EcrImageScanResultHandler.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

EcrImageScanTeamsWebhookHandler

A construct for handling ECR image scan complete events and for reporting found vulnerabilities in Microsoft Teams using a webhook.

Initializers 

import { EcrImageScanTeamsWebhookHandler } from 'cdk-ecr-image-scan-handler'

new EcrImageScanTeamsWebhookHandler(scope: Construct, id: string, props: EcrImageScanTeamsWebhookHandlerProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props EcrImageScanTeamsWebhookHandlerProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { EcrImageScanTeamsWebhookHandler } from 'cdk-ecr-image-scan-handler'

EcrImageScanTeamsWebhookHandler.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

Structs

EcrImageScanResultHandlerProps

Initializer 

import { EcrImageScanResultHandlerProps } from 'cdk-ecr-image-scan-handler'

const ecrImageScanResultHandlerProps: EcrImageScanResultHandlerProps = { ... }

Properties

Name Type Description
fromAddress string The sender address.
notificationTopicArn string The notification topic ARN that delivers the event when a scan is finished.
toAddress string The receiver address.
fromAddressRequired 
public readonly fromAddress: string;
  • Type: string

The sender address.

notificationTopicArnRequired 
public readonly notificationTopicArn: string;
  • Type: string

The notification topic ARN that delivers the event when a scan is finished.

toAddressRequired 
public readonly toAddress: string;
  • Type: string

The receiver address.

EcrImageScanTeamsWebhookHandlerProps

Initializer 

import { EcrImageScanTeamsWebhookHandlerProps } from 'cdk-ecr-image-scan-handler'

const ecrImageScanTeamsWebhookHandlerProps: EcrImageScanTeamsWebhookHandlerProps = { ... }

Properties

Name Type Description
notificationTopicArn string The notification topic ARN that delivers the event when a scan is finished.
webhookUrl string The Teams webhook URL where to report the results to.
notificationTopicArnRequired 
public readonly notificationTopicArn: string;
  • Type: string

The notification topic ARN that delivers the event when a scan is finished.

webhookUrlRequired 
public readonly webhookUrl: string;
  • Type: string

The Teams webhook URL where to report the results to.