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

aws parameters

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

ℹ️ 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.

Example configuration

plugins:
  - serverless-cloud-conformity

custom:
  cloudConformityScan:
    apiKey: ${ssm:my-conformity-api-key~true}
    failureThreshold: <LOW | MEDIUM | HIGH | VERY_HIGH | EXTREME>
    warnThreshold: <LOW | MEDIUM | HIGH | VERY_HIGH | EXTREME>
    accountId: <id of account in Cloud Conformity>
    profileId: <id of profile in Cloud Conformity>
    saveFullReport: <true | false>
    enabled: <true | false> # default: true
    stages:
      - <stage_to_run_scan>
    exceptions:
      - <id of Cloud Conformity rule>
    templatePath: <path-to-cloudformation-template>
    aws:
      accountId: 123456789012
      partition: aws
      stackId: stackId
      stackName: ${self:service}-${self:provider.stage}
      urlSuffix: amazonaws.com