Adding new remediations

Remediations can be added manually by updating the appropriate playbook files, or programmatically by extending the solution through CDK constructs, depending on your preferred workflow.

Overview of manually workflow

Automated Security Response on AWS runbooks must follow the following standard naming:

ASR-<standard>-<version>-<control>

Standard: The abbreviation for the security standard. This must match standards supported by ASR. It must be one of "CIS", "AFSBP", "PCI", "NIST", or "SC".

Version: The version of the standard. Again, this must match the version supported by ASR and the version in the finding data.

Control: The control ID of the control to be remediated. This must match the finding data.

Step 1. Create a runbook in the member account(s)

Step 2. Create an IAM role in the member account(s)

At this point, your remediation is active and available for automated remediation from the ASR Custom Action in AWS Security Hub.

Step 3: (Optional) Create an automatic remediation rule in the admin account

Automatic (not "automated") remediation is the immediate execution of the remediation as soon as the finding is received by AWS Security Hub. Carefully consider the risks before using this option.

Overview of CDK workflow

In summary, the following files in the ASR repo will be modified or added. In this example, a new remediation for ElastiCache.2 was added to the SC and AFSBP playbooks.

In this example, ElastiCache.2 is included in the following Security Hub Standards:

Since, by default, ASR only implements playbooks for AFSBP and NIST.800-53, we will add this new remediation to those playbooks in addition to SC.

Modify

Add

Development steps

Step 1: Create the Remediation Runbook

This is the SSM document used to remediate resources. It must include the AutomationAssumeRole parameter, which is the IAM role with permissions to execute the remediation. View the existing file source/remediation_runbooks/EnableElastiCacheVersionUpgrades.yaml as a reference when creating new remediation runbooks.

All new runbooks should be added to the source/remediation_runbooks/ directory.

Step 2: Create the Control Runbooks

A control runbook is a playbook-specific runbook that parses the finding data from the given standard and executes the appropriate Remediation Runbook. Since we are adding the ElastiCache.2 remediation to the SC, AFSBP, and NIST80053 playbooks, we must create a new control runbook for each. The following files are created:

Some playbooks in ASR support IaC control runbooks in TypeScript, while others must be written in raw YAML. Reference the existing remediations in the respective playbook as examples. In this example, we will cover the SC playbook, which uses IaC.

In the SC playbook, your new control runbook should export a class that extends ControlRunbookDocument and matches the name of your remediation runbook. Take a look at the example below:

export class EnableElastiCacheVersionUpgrades extends ControlRunbookDocument {
  constructor(scope: Construct, id: string, props: ControlRunbookProps) {
    super(scope, id, {
      ...props,
      securityControlId: 'ElastiCache.2',
      remediationName: 'EnableElastiCacheVersionUpgrades',
      scope: RemediationScope.REGIONAL,
      resourceIdRegex: <Regex>,
      resourceIdName: 'ClusterId',
      updateDescription: new StringFormat('Automatic minor version upgrades enabled for cluster %s.', [
        StringVariable.of(`ParseInput.ClusterId`),
      ]),
    });
  }
}

You must also export a function called createControlRunbook which returns a new instance of your class. For ElastiCache.2, this looks like:

export function createControlRunbook(scope: Construct, id: string, props: PlaybookProps): ControlRunbookDocument {
  return new EnableElastiCacheVersionUpgrades(scope, id, { ...props, controlId: 'ElastiCache.2' });
}

where controlId is the control ID as defined in the Security Standard associated with the playbook under which you are operating.

If the Security Hub control has parameters that you would like to pass to your remediation runbook, you can pass them by adding overrides to the following methods: - getExtraSteps: defines default values for each parameter implemented for the control in Security Hub

To view an example, navigate to the source/playbooks/SC/ssmdocs/SC_DynamoDB.1.ts file.

Step 3: Integrate Each Control Runbook with a Playbook

For each control runbook created in the previous step, you must now integrate it with the infrastructure definitions in the associated playbook. Follow the steps below for each control runbook.

In /<playbook_name>/control_runbooks-construct.ts Import your newly created control runbook file like:

import * as elasticache_2 from '../ssmdocs/SC_ElastiCache.2';

Next, go to the array for

const controlRunbooksRecord: Record<string, any>

And add a new entry mapping the control ID (playbook-specific) to the createControlRunbook method you’ve created:

'ElastiCache.2': elasticache_2.createControlRunbook,

Add the playbook-specific control ID to the list of remediations in <playbook_name>\_remediations.ts like below:

{ control: 'ElastiCache.2', versionAdded: '2.3.0' },

The versionAdded field should be the latest version of the solution. If adding the remediation breaches the template size limit, increase the versionAdded. You can adjust the number of remediations included in each playbook member stack in solution_env.sh.

Step 4: Create the Remediation IAM Role & Integrate Remediation Runbook

Each remediation has its own IAM role with custom permissions required to execute the remediation runbook. In addition, the RunbookFactory.createRemediationRunbook method needs to be invoked to add the remediation runbook you created in Step 1 to the solution’s CloudFormation templates.

In the remediation-runook-stack.ts, each remediation has its own code block in the RemediationRunbookStack class. The following code block shows the creation of a new IAM role and remediation runbook integration for the ElastiCache.2 remediation:

    //-----------------------
    // EnableElastiCacheVersionUpgrades
    //
    {
      const remediationName = 'EnableElastiCacheVersionUpgrades'; // should match the name of your remediation runbook
      const inlinePolicy = new Policy(props.roleStack, `ASR-Remediation-Policy-${remediationName}`);

      const remediationPolicy = new PolicyStatement();
      remediationPolicy.addActions('elasticache:ModifyCacheCluster');
      remediationPolicy.effect = Effect.ALLOW;
      remediationPolicy.addResources(`arn:${this.partition}:elasticache:*:${this.account}:cluster:*`);
      inlinePolicy.addStatements(remediationPolicy);

      new SsmRole(props.roleStack, 'RemediationRole ' + remediationName, { // creates the remediation IAM role
        solutionId: props.solutionId,
        ssmDocName: remediationName,
        remediationPolicy: inlinePolicy,
        remediationRoleName: `${remediationRoleNameBase}${remediationName}`,
      });

      RunbookFactory.createRemediationRunbook(this, 'ASR ' + remediationName, { // adds the remediation runbook to the solution's cloudformation templates
        ssmDocName: remediationName,
        ssmDocPath: ssmdocs,
        ssmDocFileName: `${remediationName}.yaml`,
        scriptPath: `${ssmdocs}/scripts`,
        solutionVersion: props.solutionVersion,
        solutionDistBucket: props.solutionDistBucket,
        solutionId: props.solutionId,
        namespace: namespace,
      });
    }

Step 5: Update Unit Tests

We recommend updating and running the unit tests after adding a new remediation.

First, you must add any new regular expressions (that are not already added) into the source/test/regex_registry.ts file. This file enforces testing for each new regular expression included in the solution’s runbooks. Take a look at the addElastiCacheClusterTestCases function as an example, which is used to test regular expressions used in ElastiCache remediations.

Finally, you’ll need to update the snapshots for each stack. Snapshots are version-controlled CloudFormation template definitions that are used to track changes made to ASR’s infrastructure. You can update these snapshot files by running the following command from the deployment directory:

./run-unit-tests.sh update

Now you are ready to deploy your new remediation! Navigate to the Build and Deploy section below for instructions on building and deploying the solution with your new changes.