Automated Security Response on AWS

🚀 Solution Landing Page \| 🚧 Feature request \| 🐛 Bug Report

Note: If you want to use the solution without building from source, navigate to Solution Landing Page

Table of contents

• Automated Security Response on AWS
• Table of contents
• Solution Overview
  • Architecture Diagram
• AWS Solutions Constructs
• Customizing the Solution
  • Prerequisites for Customization
  • Obtaining Source Code
  • Custom Playbooks
  • Configure the Playbook
  • Create the Remediations
  • Build and Deploy
  • Build the solution
  • Run Unit Tests
  • Upload to your buckets
• Deploy
• File structure
• Collection of operational metrics
• License

Solution Overview

Automated Security Response on AWS is an add-on solution that enables AWS Security Hub customers to remediate security findings with a single click using predefined response and remediation actions called “Playbooks”. Alternately the playbooks can also be configured to remediate findings in AWS Security Hub automatically. The remediation is performed using AWS Lambda and in some cases using AWS Systems Manager, the playbooks execute steps to remediate security issues, such as unused keys, open security groups, password policies, VPC configurations and public S3 buckets. The solution contains the playbook remediations for some of the security standards defined as part of CIS AWS Foundations Benchmark v1.2.0, CIS AWS Foundations Benchmark v1.4.0, AWS Foundational Security Best Practices v1.0.0, and PCI-DSS v3.2.1.

Architecture Diagram

AWS Solutions Constructs

• aws-events-rule-lambda - creates event rules that trigger the appropriate remediation, as well as any necessary permissions.

Customizing the Solution

Note: If your goal is just to deploy the solution, please use the template on the Automated Security Response on AWS Landing Page. There is no need to build the solution from source.

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.

Prerequisites for Customization

• a Linux client with the following software
• AWS CLI v2
• Python 3.7+ with pip
• AWS CDK 1.155.0+
• Node.js with npm
• source code downloaded from GitHub
• two S3 buckets (minimum): 1 global and 1 for each region where you will deploy
• An Amazon S3 Bucket for solution templates - accessed globally via https.
• An Amazon S3 Bucket for source code - regional.

Obtaining Source Code

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:

bash git clone https://github.com/aws-solutions/aws-security-hub-automated-response-and-remediation.git

Download Zip example:

bash wget https://github.com/aws-solutions/aws-security-hub-automated-response-and-remediation/archive/main.zip

Custom Playbooks

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

yaml "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

yaml "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.

1. Rename the typescript file in bin to match the (lower case) name of your new playbook. Ex. pci321.ts
2. Update cdk.json with the new file name
3. Rename the test typescript in the test subfolder similarly. Ex. pci321_stack.test.ts
4. Update the description.txt, README.md, and support.txt, following the example within.
5. Rename ssmdocs/scripts/newplaybook_parse_input.py as desired. This script parses the finding data. You will likely not need to modify it, as it's fairly robust. See other Playbooks for examples of its use.

Configure the 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.

typescript 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, AFSBP. 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: -.yaml

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:

typescript const remediations: IControl[] = [ { "control": "RDS.6" } ]

Create the Remediations

Remediations are executed using SSM Automation Runbooks. Each control has a specific runbook. ASR Runbooks must follow the naming convention in the /ssmdocs folder:

-.yaml

Follow examples from other Playbooks. Your ASR runbook must parse the finding data, extract the fields needed for remediation, and execute a remediation runbook, passing the role name.

Remediation runbooks are defined in the /source/remediation_runbooks and /source/solution_deploy/remediation_runbooks-stack.ts. The remediation examples provided with the solution are fairly robust and self-documenting. Each definition creates an IAM role and an SSM runbook that is called by the ASR runbook.

Build and Deploy

AWS Solutions use two buckets: a bucket for global access to templates, which is accessed via HTTPS, and regional buckets for access to assets within the region, such as Lambda code. You will need:

• One global bucket that is access via the http end point. AWS CloudFormation templates are stored here. It must end with "-reference. Ex. "mybucket-reference"
• One regional bucket for each region where you plan to deploy using the name of the global bucket as the root, and suffixed with the region name. Ex. "mybucket-us-east-1"
• Your buckets should be encrypted and disallow public access

Note: When creating your buckets, ensure they are not publicly accessible. Use random bucket names. Disable public access. Use KMS encryption. And verify bucket ownership before uploading.

Build the solution

First ensure that you've run npm install in the source folder.

Next from the deployment folder in your cloned repo, run build-s3-dist.sh, passing the root name of your bucket (ex. mybucket) and the version you are building (ex. v1.0.0). We recommend using a semver version based on the version downloaded from GitHub (ex. GitHub: v1.0.0, your build: v1.0.0.mybuild)

bash chmod +x build-s3-dist.sh build-s3-dist.sh -b <bucketname> -v <version>

Run Unit Tests

Some Python unit tests execute AWS API calls. The calls that create, read, or modify resources are stubbed, but some calls to APIs that do not require any permissions execute against the real AWS APIs (e.g. STS GetCallerIdentity). The recommended way to run the unit tests is to configure your credentials for a no-access console role.

bash cd ./deployment chmod +x ./run-unit-tests.sh ./run-unit-tests.sh

Confirm that all unit tests pass.

Upload to your buckets

Note: Verify bucket ownership before uploading.

By default, the templates created by build-s3-dist.sh expect the software to be stored in aws-security-hub-automated-response-and-remediation/v\<version>. If in doubt, view the template.

Use a tool such as the AWS S3 CLI "sync" command to upload your templates to the reference bucket and code to the regional bucket.

Deploy

See the Automated Security Response on AWS Implementation Guide for deployment instructions, using the link to the SolutionDeployStack.template from your bucket, rather than the one for AWS Solutions. Ex. https://mybucket-reference.s3.amazonaws.com/aws-security-hub-automated-response-and-remediation/v1.3.0.mybuild/aws-sharr-deploy.template

File structure

aws-security-hub-automated-response-and-remediation uses AWS CDK for generating the cloudformation templates.

|-source/
  |-Lambdalayer                  [ Common functions loaded as an AWS Lambda Layer for Orchestrator lambdas ]
  |-Orchestrator                 [ AWS Step Function and supporting lambdas ]
  |-playbooks                    [ Playbooks CloudDevelopment Kit Code and lambda source code]
    |- AFSBP/                    [ AFSBP v1.0.0 playbook code ]
    |- CIS120/                   [ CIS v1.2.0 playbook code ]
    |- CIS140/                   [ CIS v1.4.0 playbook code ]
    |- PCI321/                   [ PCI-DSS v3.2.1 playbook code ]
    |- SC/                       [ SC v2.0.0 playbook code ]
  |-remediation_runbooks         [ Shared remediation runbooks ]
  |-solution_deploy              [ Solution Cloud Development Kit node module ]
  |-test                         [ CDK unit tests ]

Collection of operational metrics

This solution collects anonymous 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

License

See license here

Issues

Update readme and changelog

opened on 2023-03-13 20:21:47 by hearde

• update changelog
• formatting
• v2.0.0 release date
• update readme
• word wrapping
• remove table of contents
• overview
• supported standards
• directory structure
• relative link to license

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Release v2.0.0

opened on 2023-03-02 22:19:52 by hearde

• move solution to GitHub-first, add workflows
• add support for Security Controls View (consolidated control findings)
• add support for CIS v1.4.0 standard
• add Service Catalog AppRegistry integration
• fixes for sonarqube complexity and code smells to meet quality bar
• add protections to avoid deployment failure due to SSM document throttling

Newly supported AWS FSBP controls: - CloudFormation.1 - EC2.15 - SNS.1 - SNS.2 - SQS.1

Newly supported CIS v1.2.0 controls: - 1.20

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Support remediations for the new Consolidated Control Findings format from AWS Security Hub

opened on 2023-02-27 18:21:35 by rakshb

The solution's upcoming version will add support for the new Consolidated Control Findings format from AWS Security Hub.

https://aws.amazon.com/about-aws/whats-new/2023/02/aws-security-hub-consolidated-control-findings-view/

Support for AWSFBP EC2.19 remediation. "Security groups should not allow unrestricted access to ports with high risk"

opened on 2022-11-21 16:40:12 by jacobtb23

Is your feature request related to a problem? Please describe. Out of the box the SHARR solution does not include a number of remediations that we feel would be extremely useful. Namely, AWS foundational best practices control EC2.19. "EC2.19 Security groups should not allow unrestricted access to ports with high risk". This is a fairly difficult rule to keep compliant if it is not being checked for automatically. Describe the feature you'd like We would love to see support for an automatic remediation for this rule. We have already deployed SHARR and implemented a number of controls and thus would like to avoid redeploying the solution with custom modified code to remediate EC2.19. A remediation that, if enabled, would close down offending security groups (as described n the control description) would be extremely useful, possible even the ability to add custom rules regarding security group configurations that we would disallow in our organization.

Additional context If there is any simple way to add this remediation to my existing solution without modifying existing architecture, I would love to know about it.

Add new remediation for Payment Card Industry Data Security Standard (PCI DSS) V3.2.1 control

opened on 2022-11-17 22:39:38 by rakshb

Remediation for the following PCI DSS control will be available in V2.0.0:

• Lambda.2 - Lambda functions should be in a VPC

Add new remediations for AWS Foundational Security Best Practices (AFSBP) V1.0.0 controls

opened on 2022-11-17 22:37:52 by rakshb

Remediations for the following AFSBP controls will be available in V2.0.0:

• SQS.1 - Amazon SQS queues should be encrypted at rest
• CloudFormation.1 - CloudFormation stacks should be integrated with Simple Notification Service (SNS)
• SNS.1 - SNS topics should be encrypted at rest using AWS KMS
• SNS.2 - Logging of delivery status should be enabled for notification messages sent to a topic
• S3.9 - S3 bucket server access logging should be enabled
• S3.13 - S3 buckets should have lifecycle policies configured
• SecretsManager.1 - Secrets Manager secrets should have automatic rotation enabled
• EC2.15 - EC2 subnets should not automatically assign public IP addresses
• ECS.5 - ECS containers should be limited to read-only access to root filesystems

Stretch goals: * SecretsManager.3 - Remove unused Secrets Manager secrets * SecretsManager.4 - Secrets Manager secrets should be rotated within a specified number of days * SSM.2 - All EC2 instances managed by Systems Manager should be compliant with patching requirements * SSM.4 - SSM documents should not be public * Lambda.5 - VPC Lambda functions should operate in more than one Availability Zone * KMS.1 - IAM customer managed policies should not allow decryption and re-encryption actions on all KMS keys * ECS.1 to ECS.12

Releases

Release v1.5.1 2022-12-22 18:08:39

[1.5.1] - 2022-12-22

Changed

• Changed SSM document name prefixes from SHARR to ASR to support stack update
• Upgraded Lambda Python runtimes to 3.9

Fixed

• Reverted SSM document custom resource provider to resolve intermittent deployment errors
• Fixed bug in AFSBP AutoScaling.1 and PCI.AutoScaling.1 remediation regexes

v1.5.0 2022-06-02 18:45:35

[1.5.0] - 2022-05-31

Added

• New remediations - see Implementation Guide

Changed

• Improved cross-region remediation using resource region from Resources[0].Id
• Added custom resource provider for SSM documents to allow in-place stack upgrades

Refer to changelog for more information

Full Changelog: https://github.com/aws-solutions/aws-security-hub-automated-response-and-remediation/compare/v1.4.2...v1.5.0

Release v1.4.2 2022-01-21 16:14:29

Changed

• Fix to correct the generator id pattern for CIS 1.2.0 Ruleset.

Release v1.4.1 2022-01-07 20:09:12

Changed

• Bug Fix for issue 47
• Bug Fix for issue 48

Release v1.4.0 2021-12-20 21:25:25

Changed

• Bug fixes for AFSBP EC2.1, CIS 3.x
• Separated Member roles from the remediations so that roles can be deployed once per account
• Roles are now global
• Cross-region remediation is now supported
• Deployment using stacksets is documented in the IG and supported by the templates
• Member account roles for remediation runbooks are now retained when the stack is deleted so that remediations that use these roles continue to function if the solution is removed

Added

• Added a get_approval_requirement lambda that customers can use to implement custom business logic
• Added the ability for customers to route findings to an alterate runbook when the finding meets criteria. For example, potentially destructive remediations can be sent to a runbook that sends the finding data to Incident Manager.
• New remediation for AFSBP & PCI S3.5

Release v1.3.2 2021-11-15 21:35:50

Changed:

• Corrected CIS 3.1 filter pattern
• Corrected SNS Access Policy for SO0111-SHARR-LocalAlarmNotification
• Corrected KMS CMK Access Policy used by the SNS topic to allow CloudWatch use
• EvaluationPeriods for CIS 3.x alarms changed from 240 (20 hours) to 12 (1 hour)