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 |

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

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