🚀 Solution Landing Page | 🚧 Feature request | 🐛 Bug Report
Automated Security Response (ASR) on AWS is a solution that enables AWS Security Hub customers to remediate findings with a single click using sets of predefined response and remediation actions called Playbooks. The remediations are implemented as AWS Systems Manager automation documents. The solution includes remediations for issues such as unused access keys, open security groups, weak account password policies, VPC flow logging configurations, and public S3 buckets. Remediations can also be configured to trigger automatically when findings appear in AWS Security Hub.
The solution includes the playbook remediations for some of the security controls defined as part of the following standards:
A Playbook called Security Control is included that allows operation with AWS Security Hub's Consolidated Control Findings feature.
Note: To deploy the solution without building from the source code, use the CloudFormation templates linked from the Solution Landing Page.
Detailed instructions for creating a new automated remediation in an existing Playbook can be found in the Implementation Guide. Instructions for creating an entirely new Playbook are below.
Note: If you choose to continue, please be aware that reading and adjusting the source code will be necessary.
Building from GitHub source will allow you to modify the solution to suit your specific needs. The process consists of downloading the source from GitHub, creating buckets to be used for deployment, building the solution, and uploading the artifacts needed for deployment.
Clone or download the repository to a local directory on your linux client. Note: if you intend to modify the solution you may wish to create your own fork of the GitHub repo and work from that. This allows you to check in any changes you make to your private copy of the solution.
Git Clone example:
git clone https://github.com/aws-solutions/automated-security-response-on-aws.git
Download Zip example:
wget https://github.com/aws-solutions/automated-security-response-on-aws/archive/main.zip
Go to source/playbooks in the solution source downloaded above. In this folder is a Playbook skeleton, NEWPLAYBOOK. Copy this entire folder and its contents as a new folder under source/playbooks. The naming convention is the security standard abbreviation followed by the version number, as they appear in the StandardsControlArn in the AWS Standard Finding Format for the security control.
Example
For PCI-DSS, we used "PCI" for the standard abbreviation. The version is 321: PCI321
"StandardsControlArn": "arn:aws:securityhub:us-east-1:111111111111:control/pci-dss/v/3.2.1/PCI.IAM.7"
For CIS AWS Foundations Benchmark, we use "CIS". The version is 120: CIS120
"StandardsControlArn": "arn:aws:securityhub:us-east-1:111111111111:control/cis-aws-foundations-benchmark/v/1.2.0/2.4"
Unless noted, all of the following changes are within the folder you just created for your new playbook.
Edit bin/\<standard>.ts. The following 3 lines are critical to definition of the Playbook. These values enable ASR to map from the StandardsControlArn in a finding to your remediations.
const standardShortName = "NPB";
const standardLongName = "New Playbook";
const standardVersion = "1.1.1"; // DO NOT INCLUDE 'V'
standardShortName can be as you wish. General recommendation is to make it short and meaningful. Ex. PCI, CIS, FSBP. This is the name used in many labels throughout the solution. standardLongName must match the StandardsControlArn, as pci-dss in the above example. standardVersion must match the StandardsControlArn version, as .../v/3.2.1/... in the above example.
Having established these values, your runbooks in /ssmdocs will be named:
As you write your SSM runbooks, you will add them to the stack in the following code, where control must match the field from the StandardsControlArn:
const remediations: IControl[] = [{ control: "RDS.6" }];
Edit playbooks/playbook-index.ts to include the new playbook.
Add the new playbook to the end of the standardPlaybookProps
array.
Important Do not change the order of the items in this array. Doing so will change the App Registry logical IDs for the nested stacks. This will cause an error when updating the solution.
Interface:
export interface PlaybookProps {
name: string; // Playbook short name
useAppRegistry: boolean; // Add this playbook's nested stack to app registry for the solution
defaultParameterValue?: 'yes' | 'no'; // Default value for enabling this playbook in CloudFormation. Will default to 'no' if not provided.
description?: string; // Description for the CloudFormation parameter. Solution will provide a generated description if left blank.
}
Remediations are executed using SSM Automation Runbooks. Each control has a specific runbook. ASR Runbooks must follow the naming convention in the /ssmdocs folder:
|-.github/ [ GitHub pull request template, issue templates, and workflows ] |-deployment/ [ Scripts used to build, test, and upload templates for the solution ] |-simtest/ [ Tool and sample data used to simulate findings for testing ] |-source/ [ Solution source code and tests ] |-layer/ [ Common functions used by the Orchestrator and custom resource providers ] |-lib/ [ Solution CDK ] |-appregistry/ [ Resources for integration with Service Catalog AppRegistry ] |-cdk-helper/ [ CDK helper functions ] |-member/ [ Member stack helper functions ] |-tags/ [ Resource tagging helper functions ] |-Orchestrator/ [ Orchestrator Step Function Lambda Functions ] |-playbooks/ [ Playbooks ] |-AFSBP/ [ AWS FSBP v1.0.0 playbook ] |-CIS120/ [ CIS v1.2.0 playbook ] |-CIS140/ [ CIS v1.4.0 playbook ] |-common/ [ Common scripts used by multiple playbooks ] |-NEWPLAYBOOK/ [ Example playbook ] |-bin/ [ Playbook CDK App ] |-ssmdocs/ [ Control runbooks ] |-PCI321/ [ PCI-DSS v3.2.1 playbook ] |-SC/ [ Security Control playbook ] |-remediation_runbooks/ [ Shared remediation runbooks ] |-scripts/ [ Scripts used by remediation runbooks ] |-solution_deploy/ [ Solution CDK App and custom resource providers ] |-bin/ [ Solution CDK App ] |-source/ [ Custom resource providers ] |-test/ [ CDK and SSM document unit tests ]## Collection of operational metrics This solution collects anonymized operational metrics to help AWS improve the quality of features of the solution. For more information, including how to disable this capability, please see the [Implementation Guide](https://docs.aws.amazon.com/solutions/latest/automated-security-response-on-aws/collection-of-operational-metrics.html) ## License Distributed under the Apache License Version 2.0. For more information, see [LICENSE.txt](LICENSE.txt).