serverless-cloud-conformity

A serverless plugin to scan serverless applications with
Cloud Conformity pre-deployment.

The plugin makes use of
Cloud Conformity's Cloudformation Template Scanner,
to scan the Cloudformation template built as part of serverless deployment
process. The plugin hooks into the serverless deployment process _after_ the
Cloudformation template is created and _before_ any resources are deployed in
AWS. It will produce a report with the number of successes and failures for each
severity level (LOW, MEDIUM, HIGH, VERY_HIGH or EXTREME), based on the
resources defined in the Cloudformation template. If there are failures at the
severity level set by the failureThreshold field or higher, it will stop the
deployment of the application. By default, the failure threshold is set to
HIGH.

> Currently this plugin is specific to serverless applications deployed on AWS
> because Cloud Conformity's Cloudformation Template Scanner is only available
> for AWS.

Installation

The serverless-cloud-conformity plugin is available on NPM. To install, simply
run: npm install serverless-cloud-conformity

Usage

To use the serverless plugin in your serverless application, you will require a
Cloud Conformity account and an API-Key to
access that account. In your application's serverless.yml you will need to
install the plugin and provide your Cloud Conformity api-key.

> Note: It is not recommended to hard-code API Keys in plaintext in your
> serverless.yaml configuration. API Keys can be stored in AWS Parameter Store
> and accessed at deployment time using the name of the parameter as shown
> below. The ~true retrieves the plaintext value of the parameter for use by
> the plugin, but the value is never logged anywhere or stored in your generated
> Cloud Formation template.

Optionally you may change the failure threshold to one of LOW, MEDIUM,
HIGH, VERY_HIGH or EXTREME. The default threshold is HIGH if left
unspecified. The scan will fail if it finds vulnerabilities at the set severity
level or higher, which will stop your serverless deployment. Optionally, you may
also specify a set of rules to scan with by configuring either an accountId or
profileId (but not both). If both accountId and profileId are left unspecified,
the scan will run using the default rule set. You can use the
Cloud Conformity APIs to
find your accountId or profileId. You may also choose to save the full Cloud
Conformity scan report, which will create a file under your project's
.serverless directory called
.serverless/serverless-cloud-conformity-report.json. The full report is not
saved by default and must be enabled. You can also include a list of exceptions,
consisting of ids for Conformity rules specific to a resource (ex.
ccc:AccountId:S3-011:S3:us-east-1:ServerlessDeploymentBucket). These should
only be used if you are unable to use profiles to create a rule set for
scanning. Any failures that have a corresponding exception will be counted as
successes.

If you specify a value for warnThreshold, only failures with a severity
greater than or equal the given level will be logged.

You can explicitly disable the scan with the enabled parameter set to false;
enabled defaults to true.

You can also specify the deployment stages (specified by the --stage parameter
during serverless deploy) for which the scan should run by including the stage
in a list using the stages parameter. The scan will run for all stages
specified in the list, and will not run for those that aren't included. If no
stages are specified, the scan will run for all stages.

The path to the CloudFormation template file to be scanned can also be
overridden with the templatePath parameter. This is useful when you want to
scan a template that has been moved from the default path where
serverless package outputs the template.

If you wish to change the number of times this plugin retries on 5xx or 429
errors, you can set the numberOfRetries parameter. Keep in mind that the
retries are done with
exponential backoff,
so setting this value fairly high will result in a long wait between retries.

| Parameter | Type | Required | Default Value |
| ---------------- | ------ | -------- | ------------------------------------------------------- |
| apiKey | String | Yes | N/A |
| failureThreshold | String | No | HIGH |
| warnThreshold | String | No | LOW |
| accountId | String | No | N/A |
| profileId | String | No | N/A |
| saveFullReport | Bool | No | false |
| enabled | Bool | No | true |
| stages | List | No | N/A |
| exceptions | List | No | N/A |
| templatePath | String | No | ./.serverless/cloudformation-template-update-stack.json |
| numberOfRetries | Number | No | 3 |
| aws | Object | No | see detail |

$3

The Conformity template scanner supports providing the values of
CloudFormation pseudo-parameters
that you may be using in your stack. You can override the defaults by setting
values in the plugin parameters.

| Parameter | Type | Required | Default Value |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| accountId | String | No | 123456789012 |
| partition | String | No | aws |
| stackId | String | No | arn:${partition}:cloudformation:${region}:${accountID}:stack/example/51af3dc0-da77-11e4-872e-1234567db123 |
| stackName | String | No | stackName |
| urlSuffix | String | No | amazonaws.com |

> :information_source: In addition to the configurable parameters above, the
> plugin sets the value for the AWS::Region pseudo-parameter to the region
> option you provide to the Serverless Framework.

$3

``yaml
plugins:
- serverless-cloud-conformity

custom:
cloudConformityScan:
apiKey: ${ssm:my-conformity-api-key~true}
failureThreshold:
warnThreshold:
accountId:
profileId:
saveFullReport:
enabled: # default: true
stages:
-
exceptions:
-
templatePath:
aws:
accountId: 123456789012
partition: aws
stackId: stackId
stackName: ${self:service}-${self:provider.stage}
urlSuffix: amazonaws.com
``