{"id":13541618,"url":"https://github.com/aws-solutions/automated-security-response-on-aws","last_synced_at":"2025-04-04T20:16:17.301Z","repository":{"id":38812247,"uuid":"285372365","full_name":"aws-solutions/automated-security-response-on-aws","owner":"aws-solutions","description":"Automated Security Response on AWS is an add-on solution that works with AWS Security Hub to provide a ready-to-deploy architecture and a library of automated playbooks. The solution makes it easier for AWS Security Hub customers to resolve common security findings and to improve their security posture in AWS.","archived":false,"fork":false,"pushed_at":"2024-06-20T17:03:15.000Z","size":2773,"stargazers_count":371,"open_issues_count":9,"forks_count":104,"subscribers_count":34,"default_branch":"main","last_synced_at":"2024-08-31T18:51:38.032Z","etag":null,"topics":["aws","aws-security-automation","aws-security-hub"],"latest_commit_sha":null,"homepage":"https://aws.amazon.com/solutions/implementations/aws-security-hub-automated-response-and-remediation/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-solutions.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-05T18:27:35.000Z","updated_at":"2024-08-28T02:31:37.000Z","dependencies_parsed_at":"2023-02-15T03:16:34.548Z","dependency_job_id":"4fa4d9a0-8863-412f-8c3f-3eba01b092d4","html_url":"https://github.com/aws-solutions/automated-security-response-on-aws","commit_stats":null,"previous_names":["aws-solutions/automated-security-response-on-aws","aws-solutions/aws-security-hub-automated-response-and-remediation"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fautomated-security-response-on-aws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fautomated-security-response-on-aws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fautomated-security-response-on-aws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fautomated-security-response-on-aws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-solutions","download_url":"https://codeload.github.com/aws-solutions/automated-security-response-on-aws/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246970317,"owners_count":20862509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-security-automation","aws-security-hub"],"created_at":"2024-08-01T10:00:52.104Z","updated_at":"2025-04-04T20:16:17.283Z","avatar_url":"https://github.com/aws-solutions.png","language":"Python","funding_links":[],"categories":["Projects","aws","Python"],"sub_categories":["Incident Response"],"readme":"# Automated Security Response on AWS\n\n[🚀 Solution Landing Page](https://aws.amazon.com/solutions/implementations/automated-security-response-on-aws/) \\| [🚧\nFeature\nrequest](https://github.com/aws-solutions/automated-security-response-on-aws/issues/new?assignees=\u0026labels=feature-request%2C+enhancement\u0026template=feature_request.md\u0026title=)\n\\| [🐛 Bug\nReport](https://github.com/aws-solutions/automated-security-response-on-aws/issues/new?assignees=\u0026labels=bug%2C+triage\u0026template=bug_report.md\u0026title=)\n\nAutomated Security Response (ASR) on AWS is a solution that enables AWS Security Hub customers to remediate findings\nwith a single click using sets of predefined response and remediation actions called Playbooks. The remediations are\nimplemented as AWS Systems Manager automation documents. The solution includes remediations for issues such as unused\naccess keys, open security groups, weak account password policies, VPC flow logging configurations, and public S3\nbuckets. Remediations can also be configured to trigger automatically when findings appear in AWS Security Hub.\n\nThe solution includes the playbook remediations for some of the security controls defined as part of the following\nstandards:\n\n- AWS Foundational Security Best Practices (FSBP) v1.0.0\n- Center for Internet Security (CIS) AWS Foundations Benchmark v1.2.0\n- Center for Internet Security (CIS) AWS Foundations Benchmark v1.4.0\n- Center for Internet Security (CIS) AWS Foundations Benchmark v3.0.0\n- Payment Card Industry (PCI) Data Security Standard (DSS) v3.2.1\n- National Institute of Standards and Technology (NIST) Special Publication 800-53 Revision 5\n\nA Playbook called Security Control is included that allows operation with AWS Security Hub's Consolidated Control\nFindings feature.\n\n**Note**: To deploy the solution without building from the source code, use the CloudFormation templates linked from the\n[Solution Landing Page](https://aws.amazon.com/solutions/implementations/automated-security-response-on-aws/).\n\n## Architecture Diagram\n\n![](./docs/architecture_diagram.png)\n\n## Customizing the Solution\n\nDetailed instructions for creating a new automated remediation in an existing Playbook can be found in the\nImplementation Guide. Instructions for creating an entirely new Playbook are below.\n\n**Note**: If you choose to continue, please be aware that reading and adjusting the source code will be necessary.\n\n### Prerequisites for Customization\n\n- a Linux client with the following software\n  - AWS CLI v2\n  - Python 3.11+ with pip\n  - AWS CDK 2.171.1+\n  - Node.js 20+ with npm\n- source code downloaded from GitHub\n\n\n#### Obtaining Source Code\n\nBuilding from GitHub source will allow you to modify the solution to suit your specific needs. The process consists of\ndownloading the source from GitHub, creating buckets to be used for deployment, building the solution, and uploading the\nartifacts needed for deployment.\n\nClone or download the repository to a local directory on your linux client. Note: if you intend to modify the solution\nyou may wish to create your own fork of the GitHub repo and work from that. This allows you to check in any changes you\nmake to your private copy of the solution.\n\n**Git Clone example:**\n\n```bash\ngit clone https://github.com/aws-solutions/automated-security-response-on-aws.git\n```\n\n**Download Zip example:**\n\n```bash\nwget https://github.com/aws-solutions/automated-security-response-on-aws/archive/main.zip\n```\n\n### Custom Playbooks\n\nGo to source/playbooks in the solution source downloaded above. In this folder is a Playbook skeleton, **NEWPLAYBOOK**.\nCopy this entire folder and its contents as a new folder under source/playbooks. The naming convention is the security\nstandard abbreviation followed by the version number, as they appear in the StandardsControlArn in the AWS Standard\nFinding Format for the security control.\n\n**Example**\n\nFor PCI-DSS, we used \"PCI\" for the standard abbreviation. The version is 321: **PCI321**\n\n```yaml\n\"StandardsControlArn\": \"arn:aws:securityhub:us-east-1:111111111111:control/pci-dss/v/3.2.1/PCI.IAM.7\"\n```\n\nFor CIS AWS Foundations Benchmark, we use \"CIS\". The version is 120: **CIS120**\n\n```yaml\n\"StandardsControlArn\": \"arn:aws:securityhub:us-east-1:111111111111:control/cis-aws-foundations-benchmark/v/1.2.0/2.4\"\n```\n\nUnless noted, all of the following changes are within the folder you just created for your new playbook.\n\n1. Rename the typescript file in **bin** to match the (lower case) name of your new playbook. Ex. **pci321.ts**\n2. Update cdk.json with the new file name\n3. Rename the test typescript in the **test** subfolder similarly. Ex. **pci321_stack.test.ts**\n4. Update the description.txt, README.md, and support.txt, following the example within.\n5. Rename ssmdocs/scripts/newplaybook_parse_input.py as desired. This script parses the finding data. You will likely\n   not need to modify it, as it's fairly robust. See other Playbooks for examples of its use.\n\n#### Configure the Playbook\n\nEdit **bin/\\\u003cstandard\\\u003e.ts**. The following 3 lines are critical to definition of the Playbook. These values enable ASR\nto map from the StandardsControlArn in a finding to your remediations.\n\n```typescript\nconst standardShortName = \"NPB\";\nconst standardLongName = \"New Playbook\";\nconst standardVersion = \"1.1.1\"; // DO NOT INCLUDE 'V'\n```\n\n**standardShortName** can be as you wish. General recommendation is to make it short and meaningful. Ex. PCI, CIS,\nFSBP. This is the name used in many labels throughout the solution. **standardLongName** must match the\nStandardsControlArn, as _pci-dss_ in the above example. **standardVersion** must match the StandardsControlArn version,\nas _.../v/3.2.1/..._ in the above example.\n\nHaving established these values, your runbooks in **/ssmdocs** will be named: \u003cstandardShortName\u003e-\u003ccontrol\u003e.yaml\n\nAs you write your SSM runbooks, you will add them to the stack in the following code, where control must match the field\nfrom the StandardsControlArn:\n\n```typescript\nconst remediations: IControl[] = [{ control: \"RDS.6\" }];\n```\n\n#### Add your playbook as a new nested stack in the solution template\n\nEdit **playbooks/playbook-index.ts** to include the new playbook.\n\nAdd the new playbook to the end of the `standardPlaybookProps` array.\n\n**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. \nThis will cause an error when updating the solution.\n\nInterface:\n\n```typescript\nexport interface PlaybookProps {\n  name: string; // Playbook short name\n  useAppRegistry: boolean; // Add this playbook's nested stack to app registry for the solution\n  defaultParameterValue?: 'yes' | 'no'; // Default value for enabling this playbook in CloudFormation. Will default to 'no' if not provided.\n  description?: string; // Description for the CloudFormation parameter. Solution will provide a generated description if left blank.\n}\n```\n\n#### Create the Remediations\n\nRemediations are executed using SSM Automation Runbooks. Each control has a specific runbook. ASR Runbooks must follow\nthe naming convention in the **/ssmdocs** folder:\n\n\u003cstandardShortName\u003e-\u003ccontrol\u003e.yaml\n\nFollow examples from other Playbooks. Your ASR runbook must parse the finding data, extract the fields needed for\nremediation, and execute a remediation runbook, passing the role name.\n\nRemediation runbooks are defined in the /source/remediation_runbooks and\n/source/solution_deploy/remediation_runbooks-stack.ts. The remediation examples provided with the solution are fairly\nrobust and self-documenting. Each definition creates an IAM role and an SSM runbook that is called by the ASR runbook.\n\n### Build and Deploy\n\nAWS Solutions use two buckets: a bucket for global access to templates, which is accessed via HTTPS, and regional\nbuckets for access to assets within the region, such as Lambda code. \n\n- Pick a unique bucket name, `e.g. asr-staging`. Set two environment variables on your terminal, one should be the base bucket name with `-reference` as suffix, the other with your intended deployment region as suffix:\n\n```bash\nexport BASE_BUCKET_NAME=asr-staging-$(date +%s)\nexport TEMPLATE_BUCKET_NAME=$BASE_BUCKET_NAME-reference\nexport REGION=us-east-1\nexport ASSET_BUCKET_NAME=$BASE_BUCKET_NAME-$REGION\n```\n\n- In your AWS account, create two buckets with these names,\n  e.g. `asr-staging-reference` and `asr-staging-us-east-1`. (The reference bucket will hold the CloudFormation templates, the regional bucket will hold all other assets like the lambda code bundle.)\n- Your buckets should be encrypted and disallow public access\n\n```bash\naws s3 mb s3://$TEMPLATE_BUCKET_NAME/\naws s3 mb s3://$ASSET_BUCKET_NAME/\n```\n\n**Note**: When creating your buckets, ensure they are not publicly accessible. Use random bucket names. Disable public\naccess. Use KMS encryption. And verify bucket ownership before uploading.\n\n#### Build the solution\n\nFirst ensure that you've run `npm install` in the _source_ folder.\n\nNext from the _deployment_ folder in your cloned repo, run build-s3-dist.sh, passing the root name of your bucket (ex.\nmybucket) and the version you are building (ex. v1.0.0). We recommend using a semver version based on the version\ndownloaded from GitHub (ex. GitHub: v1.0.0, your build: v1.0.0.mybuild)\n\n```bash\nchmod +x build-s3-dist.sh\nexport SOLUTION_NAME=automated-security-response-on-aws\nexport SOLUTION_VERSION=v1.0.0.mybuild\n./build-s3-dist.sh -b $BASE_BUCKET_NAME -v $SOLUTION_VERSION\n```\n\n#### Unit Tests\n\n##### Prerequisites\n\nIn order to run the unit tests locally, you must first install and configure Poetry. Poetry is a tool used for managing dependencies and packaging within Python projects.\nWe recommend using [pipx](https://pipx.pypa.io/stable/installation/) to install and manage Poetry. You can find other ways to install Poetry in the [Poetry installation guide](https://python-poetry.org/docs/#installation).\n**Note**: You must install Poetry version 1.8.3 to execute the `run-unit-tests.sh` script. The `export` command has been removed in version 2.0.0 of Poetry meaning the script will not execute successfully.\n\nFollow these steps to install and setup Poetry on your local machine:\n- Install version 1.8.3 of Poetry by running `pipx install poetry==1.8.3`\n- Set the `POETRY_HOME` environment variable to be the path to your local installation of Poetry. E.g., `POETRY_HOME=/Users/YOUR_USERNAME/.local/pipx/venvs/poetry`\n\n##### Run Unit Tests\n\nSome Python unit tests execute AWS API calls. The calls that create, read, or modify resources are stubbed, but some\ncalls to APIs that do not require any permissions execute against the real AWS APIs (e.g. STS GetCallerIdentity). The\nrecommended way to run the unit tests is to configure your credentials for a no-access console role.\n\nAll stubbed AWS API calls expect the local partition to be `us-east-1`, meaning you must either run the `export AWS_DEFAULT_REGION=us-east-1` command before running the unit tests, \nor set your AWS config file to use `us-east-1` region while running the tests.\n\n```bash\ncd ./deployment\nexport AWS_DEFAULT_REGION=us-east-1\nchmod +x ./run-unit-tests.sh\n./run-unit-tests.sh\n```\n\nConfirm that all unit tests pass.\n\n### Upload to your buckets\n\n**Note**: Verify bucket ownership before uploading.\n\nBy default, the templates created by build-s3-dist.sh expect the software to be stored in\n**automated-security-response-on-aws/\\\u003cversion\\\u003e**. If in doubt, view the template.\n\nUpload the build artifacts from `global-s3-assets/` to the template bucket and the artifacts from `regional-s3-assets/` to the regional bucket:\n\n```bash\naws s3 ls s3://$TEMPLATE_BUCKET_NAME # test that bucket exists - should not give an error\naws s3 ls s3://$ASSET_BUCKET_NAME # test that bucket exists - should not give an error\ncd ./deployment\naws s3 cp global-s3-assets/  s3://$TEMPLATE_BUCKET_NAME/$SOLUTION_NAME/$SOLUTION_VERSION/ --recursive --acl bucket-owner-full-control\naws s3 cp regional-s3-assets/  s3://$ASSET_BUCKET_NAME/$SOLUTION_NAME/$SOLUTION_VERSION/ --recursive --acl bucket-owner-full-control\n```\n\n_✅ All assets are now staged on your S3 buckets. You or any user may use S3 links for deployments_\n\n## Deploy\n\nConsult the [Automated Security Response on AWS Implementation\nGuide](https://docs.aws.amazon.com/solutions/latest/automated-security-response-on-aws/solution-overview.html) for detailed \ndeployment instructions and set all deployment parameters according to your needs. \nWhen following the instructions, keep in mind to use the URLs to the templates in your own bucket.\n\nIf you anticipate that you will need to deploy multiple times during your development iterations, you can alternatively compose an `aws cloudformation create-stack` command with your desired parameter values, and deploy from the terminal.\nFor example:\n\n```bash\n  export ADMIN_TEMPLATE_URL=https://$TEMPLATE_BUCKET_NAME.s3.amazonaws.com/$SOLUTION_NAME/$SOLUTION_VERSION/aws-sharr-deploy.template\n  aws cloudformation create-stack \\\n  --capabilities CAPABILITY_NAMED_IAM \\\n  --stack-name ASR-Admin-$(date +%s) \\\n  --template-url $ADMIN_TEMPLATE_URL \\\n  --parameters \\\n    ParameterKey=LoadSCAdminStack,ParameterValue=yes \\\n    ParameterKey=LoadAFSBPAdminStack,ParameterValue=no \\\n    ParameterKey=LoadCIS120AdminStack,ParameterValue=no \\\n    ParameterKey=LoadCIS140AdminStack,ParameterValue=no \\\n    ParameterKey=LoadCIS300AdminStack,ParameterValue=no \\\n    ParameterKey=LoadNIST80053AdminStack,ParameterValue=no \\\n    ParameterKey=LoadPCI321AdminStack,ParameterValue=no \\\n    ParameterKey=ReuseOrchestratorLogGroup,ParameterValue=no \\\n    ParameterKey=UseCloudWatchMetrics,ParameterValue=yes \\\n    ParameterKey=UseCloudWatchMetricsAlarms,ParameterValue=yes \\\n    ParameterKey=RemediationFailureAlarmThreshold,ParameterValue=5 \\\n    ParameterKey=EnableEnhancedCloudWatchMetrics,ParameterValue=no \\\n    ParameterKey=TicketGenFunctionName,ParameterValue= \n    \n  export NAMESPACE=$(date +%s | tail -c 9)\n  export MEMBER_TEMPLATE_URL=https://$TEMPLATE_BUCKET_NAME.s3.amazonaws.com/$SOLUTION_NAME/$SOLUTION_VERSION/aws-sharr-member.template\n  aws cloudformation create-stack \\\n  --capabilities CAPABILITY_NAMED_IAM \\\n  --stack-name ASR-Member-$(date +%s) \\\n  --template-url $MEMBER_TEMPLATE_URL \\\n  --parameters \\\n    ParameterKey=LoadSCMemberStack,ParameterValue=yes \\\n    ParameterKey=LoadAFSBPMemberStack,ParameterValue=no \\\n    ParameterKey=LoadCIS120MemberStack,ParameterValue=no \\\n    ParameterKey=LoadCIS140MemberStack,ParameterValue=no \\\n    ParameterKey=LoadNIST80053MemberStack,ParameterValue=no \\\n    ParameterKey=LoadPCI321MemberStack,ParameterValue=no \\\n    ParameterKey=CreateS3BucketForRedshiftAuditLogging,ParameterValue=no \\\n    ParameterKey=LogGroupName,ParameterValue=random-log-group-123456789012 \\\n    ParameterKey=Namespace,ParameterValue=$NAMESPACE \\\n    ParameterKey=SecHubAdminAccount,ParameterValue=123456789012\n    \n  export MEMBER_ROLES_TEMPLATE_URL=https://$TEMPLATE_BUCKET_NAME.s3.amazonaws.com/$SOLUTION_NAME/$SOLUTION_VERSION/aws-sharr-member-roles.template\n  aws cloudformation create-stack \\\n  --capabilities CAPABILITY_NAMED_IAM \\\n  --stack-name ASR-Member-Roles-$(date +%s) \\\n  --template-url $MEMBER_ROLES_TEMPLATE_URL \\\n  --parameters \\\n    ParameterKey=Namespace,ParameterValue=$NAMESPACE \\\n    ParameterKey=SecHubAdminAccount,ParameterValue=123456789012\n```\n\n## Directory structure\n\n\u003cpre\u003e\n|-.github/                [ GitHub pull request template, issue templates, and workflows ]\n|-deployment/             [ Scripts used to build, test, and upload templates for the solution ]\n|-simtest/                [ Tool and sample data used to simulate findings for testing ]\n|-source/                 [ Solution source code and tests ]\n  |-layer/                [ Common functions used by the Orchestrator and custom resource providers ]\n  |-lib/                  [ Solution CDK ]\n    |-appregistry/        [ Resources for integration with Service Catalog AppRegistry ]\n    |-cdk-helper/         [ CDK helper functions ]\n    |-member/             [ Member stack helper functions ]\n    |-tags/               [ Resource tagging helper functions ]\n  |-Orchestrator/         [ Orchestrator Step Function Lambda Functions ]\n  |-playbooks/            [ Playbooks ]\n    |-AFSBP/              [ AWS FSBP v1.0.0 playbook ]\n    |-CIS120/             [ CIS v1.2.0 playbook ]\n    |-CIS140/             [ CIS v1.4.0 playbook ]\n    |-common/             [ Common scripts used by multiple playbooks ]\n    |-NEWPLAYBOOK/        [ Example playbook ]\n      |-bin/              [ Playbook CDK App ]\n      |-ssmdocs/          [ Control runbooks ]\n    |-PCI321/             [ PCI-DSS v3.2.1 playbook ]\n    |-SC/                 [ Security Control playbook ]\n  |-remediation_runbooks/ [ Shared remediation runbooks ]\n    |-scripts/            [ Scripts used by remediation runbooks ]\n  |-solution_deploy/      [ Solution CDK App and custom resource providers ]\n    |-bin/                [ Solution CDK App ]\n    |-source/             [ Custom resource providers ]\n  |-test/                 [ CDK and SSM document unit tests ]\n\u003c/pre\u003e\n\n## Collection of operational metrics\n\nThis solution collects anonymized operational metrics to help AWS improve the quality of features of the solution. For\nmore information, including how to disable this capability, please see the [Implementation\nGuide](https://docs.aws.amazon.com/solutions/latest/automated-security-response-on-aws/collection-of-operational-metrics.html)\n\n## License\n\nDistributed under the Apache License Version 2.0. For more information, see [LICENSE.txt](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-solutions%2Fautomated-security-response-on-aws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-solutions%2Fautomated-security-response-on-aws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-solutions%2Fautomated-security-response-on-aws/lists"}