fbpx

Posted on by admin

How exactly to enrich AWS Security Hub findings with account metadata

In this website post, we’ll walk you through how exactly to deploy a remedy to enrich AWS Security Hub findings with additional account-related metadata, like the account name, the business Unit (OU) from the account, security contact information, and account tags. Account metadata might help you search findings, create insights, and react to and remediate findings better.

AWS Security Hub ingests findings from multiple AWS services, including Amazon GuardDuty, Amazon Inspector, Amazon Macie, AWS Firewall Manager, AWS Identity and Access Management (IAM) Access Analyzer, and AWS Systems Manager Patch Manager. Findings from each service are normalized in to the AWS Security Finding Format (ASFF), in order to review findings in a standardized format and do something quickly. You should use AWS Security Hub to supply a single view of most security-related findings, also to create alerts, automate remediation, and export specific findings to third‑party incident management systems.

 

The DevOps or Security teams in charge of investigating, responding to, and remediating Security Hub findings may need additional account metadata beyond the account ID, to determine how to proceed concerning the finding or where you can route it. For instance, determining if the finding comes from a development or production account could be key to determining the priority of the finding and the sort of remediation action needed. Having this metadata information in the finding allows customers to generate custom insights in Security Hub to track which OUs or applications (predicated on account tags) have probably the most open security issues. This website post demonstrates a remedy to enrich your findings with account metadata to greatly help your Security and DevOps teams better understand and enhance their security posture.

Solution Overview

In this solution, you shall work with a mix of AWS Security Hub, Amazon EventBridge and AWS Lambda to ingest the findings and automatically enrich them with account related metadata by querying AWS Organizations and Account management service APIs. The perfect solution is architecture is shown in Figure 1 below:

Figure 1: Solution Architecture and workflow for metadata enrichment

Figure 1: Solution Architecture and workflow for metadata enrichment

The answer includes :&lt the next steps;/p>

  1. New findings and updates to existing Security Hub findings from all of the member accounts flow in to the Security Hub administrator account. Security Hub generates Amazon EventBridge events for the findings.
  2. An EventBridge rule created within the solution in the Security Hub administrator account will trigger a Lambda function configured as a target each time an EventBridge notification for a fresh or updated finding imported into Security Hub matches the EventBridge rule shown below:

    “detail-type”: [“Security Hub Findings – Imported”],
    “source”: [“aws.securityhub”],
    “detail”:
    “findings”:
    “RecordState”: [“ACTIVE”],
    “UserDefinedFields”:
    “findingEnriched”: [
    “exists”: false
    ]

  3. The Lambda function uses the account ID from the function payload to retrieve both username and passwords and the alternate contact information from the AWS Organizations and Account management service API. The next code within the helper.py constructs the account_details object representing the username and passwords to enrich the finding:

     

    def get_account_details(account_id, role_name):

    account_details =
    organizations_client = AwsHelper().get_client(‘organizations’)
    response = organizations_client.describe_account(AccountId=account_id)
    account_details[“Name”] = response[“Account”][“Name”]
    response = organizations_client.list_parents(ChildId=account_id)
    ou_id = response[“Parents”][0][“Id”]
    if ou_id and response[“Parents”][0][“Type”] == “ORGANIZATIONAL_UNIT”:
    response = organizations_client.describe_organizational_unit(OrganizationalUnitId=ou_id)
    account_details[“OUName”] = response[“OrganizationalUnit”][“Name”]
    elif ou_id:
    account_details[“OUName”] = “ROOT”
    if role_name:
    account_client = AwsHelper().get_session_for_role(role_name).client(“account”)
    else:
    account_client = AwsHelper().get_client(‘account’)
    try:
    response = account_client.get_alternate_contact(
    AccountId=account_id,
    AlternateContactType=’SECURITY’
    )
    if response[‘AlternateContact’]:
    print(“contact :”.format(str(response[“AlternateContact”])))
    account_details[“AlternateContact”] = response[“AlternateContact”]
    except account_client.exceptions.AccessDeniedException as error:
    #Potentially because of calling alternate contact on Org Management account
    print(error.response[‘Error’][‘Message’])

         response = organizations_client.list_tags_for_resource(ResourceId=account_id)

    results = response[“Tags”]
    while “NextToken” in response:
    response = organizations_client.list_tags_for_resource(ResourceId=account_id, NextToken=response[“NextToken”])
    results.extend(response[“Tags”])

    account_details[“tags”] = results
    AccountHelper.logger.info(“account_details: %s” , str(account_details))
    return account_details

  5. The Lambda function updates the finding utilizing the Security Hub BatchUpdateFindings API to include the account related data in to the Note and UserDefinedFields attributes of the SecurityHub finding: 
    #lookup and build the finding user and note defined fields predicated on account Id

    enrichment_text, tags_dict = enrich_finding(account_id, assume_role_name)
    logger.debug(“Text to create: %s” , enrichment_text)
    logger.debug(“User defined Fields %s” , json.dumps(tags_dict))
    #add the Note to the finding and put in a userDefinedField to use in the case bridge rule and stop repeat lookups
    response = secHubClient.batch_update_findings(
    FindingIdentifiers=[

            'Id': enrichment_finding_id,
        'ProductArn': enrichment_finding_arn

],
Note=
    'Text': enrichment_text,
    'UpdatedBy': enrichment_author
,
UserDefinedFields=tags_dict

    )

Note: All state change events published by AWS services through Amazon Event Bridge are cost free. Monthly the AWS Lambda free tier includes 1M free requests, and 400,monthly during publication of the post 000 GB-seconds of compute time. Per month in the event that you process 2M requests, the estimated cost because of this solution will be approximately $7.per month 20 USD.

Prerequisites

  • This solution requires that you have AWS Security Hub enabled within an AWS multi-account environment that is integrated with AWS Organizations . The AWS Organizations management account must designate a Security Hub administrator account, that may view data from and manage configuration because of its member accounts. Follow these steps to designate a Security Hub administrator take into account your AWS organization.
  • All of the members accounts are tagged per your organization’s tagging strategy and their security alternate contact is filled. If the tags or alternate contacts aren’t available, the enrichment will be limited by the Account Name and the Organizational Unit name.
  • Trusted access should be enabled with AWS Organizations for AWS Account Management service . This can enable the AWS Organizations management account to call the AWS Account Management API operations (such as for example GetAlternateContact ) for other member accounts in the business. Trusted access could be enabled either through the use of AWS Management Console or through the use of AWS SDKs and CLI.The next AWS CLI example enables trusted access for AWS Account Management in the calling account’s organization. 
         aws organizations enable-aws-service-access --service-principal account.amazonaws.com
  • An IAM role with a read only usage of lookup the GetAlternateContact  details should be created in the Organizations management account, with a trust policy which allows the Security Hub administrator account to assume the role.

Solution Deployment

This solution includes two parts:

  • Create an IAM role in your Organizations management account, giving it necessary permissions as described in the Create the IAM role procedure below.
  • Deploy the Lambda function and another associated resources to your Security Hub administrator account

Create the IAM role

Using console, AWS CLI or AWS API

Follow the Developing a role to delegate permissions to an IAM user instructions to make a IAM role utilizing the console, AWS CLI or AWS API in the AWS Organization management account with role name as account-contact-readonly , in line with the permission and trust policy template provided below. You shall need the account ID of one’s Security Hub administrator account.

the Security is allowed by

The IAM trust policy Hub administrator account to assume the role in your company management account.

IAM Role trust policy


  "Version": "2012-10-17",
  "Statement": [


  "Effect": "Allow",
  "Principal": 
    "AWS": "arn:aws:iam::                                        :root"
  ,
  "Action": "sts:AssumeRole",
  "Condition":

]

Note: Replace the with the account ID of one’s Security Hub administrator account. The perfect solution is is deployed once, you should update the main in the trust policy shown above to utilize the brand new IAM role designed for the solution.

IAM Permission Policy


    "Version": "2012-10-17",
    "Statement": [


        "Effect": "Allow",
        "Action": [
            "account:GetAlternateContact"
        ],
        "Resource": "arn:aws:account::                                        :account/o-          /          "

]

The IAM permission policy allows the Security Hub administrator account to check up the alternate contact information for the member accounts.

Take note of the Role ARN for the IAM role such as this format:

     arn:aws:iam::                                        :role/account-contact-readonly.

You shall need this as the deploying the solution within the next procedure.

Using AWS CloudFormation

Alternatively, the &nbsp may be used by you; provided CloudFormation template to generate the role in the management account. The IAM role ARN comes in the Outputs portion of the created CloudFormation stack.

Deploy the answer to your Security Hub administrator account

It is possible to deploy the perfect solution is using either the AWS Management Console, or from the GitHub repository utilizing the AWS SAM CLI .

Note: when you have designated an aggregation Region within the Security Hub administrator account, it is possible to deploy this solution only in the aggregation Region, otherwise you will need to deploy this solution separately in each Region of the Security Hub administrator account where Security Hub is enabled.

To deploy the answer utilizing the AWS Management Console

  1. In your Security Hub administrator account, launch the template by choosing the Launch Stack button below, which creates the stack the in us-east-1 Region.

    Note: if your Security Hub aggregation region differs than us-east-1 or desire to deploy the perfect solution is in another AWS Region, it is possible to deploy the answer from the GitHub repository described within the next section.

    Select this image to open a link that starts building the CloudFormation stack

  2. On the Quick create stack page, for Stack name, enter a distinctive stack name because of this account; for instance, aws-security-hub-findings-enrichment-stack , as shown in Figure 2 below.
    Figure 2: Quick Create CloudFormation stack for the Solution

Figure 2: Quick Create CloudFormation stack for the perfect solution is

  • For ManagementAccount , enter the AWS Organizations management account ID.
  • For OrgManagementAccountContactRole , enter the role ARN of the role you created previously in the Create IAM role procedure.
  • Choose Create stack.
  • After the stack is created, go directly to the Resources tab and observe the name of the IAM Role that was created.
  • Update the principal part of the IAM role trust policy that you previously created in the business management account in the Create the IAM role procedure above, replacing it with the role name you noted down, as shown below.

    Figure 3 Update Management Account Role’s Trust

    Figure 3 Update Management Account Role’s Trust

To deploy the answer from the GitHub AWS and Repository SAM CLI

    1. Install the AWS SAM CLI

clone or

    1. Download the github repository utilizing the following commands 
           $ git clone https://github.com/aws-samples/aws-security-hub-findings-account-data-enrichment.git

      $ cd aws-security-hub-findings-account-data-enrichment

    1. Update this content of the profile.txt file with the profile name you intend to use for the deployment

develop a new bucket for deployment artifacts

    1. To, run create-bucket.sh by specifying below the spot as argument as. 
           $ ./create-bucket.sh us-east-1
    1. Deploy the perfect solution is to the account by running the deploy.sh script by specifying the spot as argument 
           $ ./deploy.sh us-east-1
    1. After the stack is created, go directly to the Resources tab and observe the name of the IAM Role that was created.
    1. Update the main component of the IAM role trust policy that you previously created in the business management account in the Create the IAM role procedure above, replacing it with the role name you noted down, as shown below. 
           "AWS": "arn:aws:iam::: role/"

Utilizing the enriched attributes

To check that the answer is working needlessly to say, you can develop a standalone security group having an ingress rule which allows traffic from the web. This can trigger a finding in Security Hub, which is populated with the enriched attributes. You should use these enriched attributes to filter and create custom insights then, or take specific remediation or response actions.

To generate an example Security Hub finding using AWS CLI

    1. Develop a Security Group using following AWS CLI command: 
           aws ec2 create-security-group --group-name TestSecHubEnrichmentSG--description "Test Security Hub enrichment function"
    1. Take note of the security group ID from the output, and utilize it in Step three 3 below.
    1. Add an ingress rule to the security group that allows unrestricted traffic on port 100: 
           aws ec2 authorize-security-group-ingress --group-id <                    Replace Security group ID                    > --protocol tcp --port 100 --cidr 0.0.0.0/0

Within short while, a fresh finding will undoubtedly be generated in Security Hub, warning concerning the unrestricted ingress rule in the TestSecHubEnrichmentSG security group. For just about any new or updated findings which don’t have the UserDefinedFields attribute  findingEnriched set to true , the perfect solution is will enrich the finding with account related fields in both Note and UserDefinedFields sections in the Security Hub finding.

To see and filter the enriched finding

    1. Head to Security Hub and select Findings on the left-hand navigation.
    1. Click in the filter field at the very top to include additional filters. Select a filter field of  AWS Account ID , a filter match type of  is , and a value of the AWS Account ID where you created the TestSecHubEnrichmentSG security group.
    1. Add yet another filter. Select a filter field of Resource type , a filter match kind of is , and the worthiness of AwsEc2SecurityGroup .
    1. Identify the finding for security group TestSecHubEnrichmentSG with updates to notice and UserDefinedFields , as shown in Figures 4 and 5 below:

      Figure 4: Account metadata enrichment in Security Hub finding’s Note field

      Figure 4: Account metadata enrichment in Security Hub finding’s Note field

      Figure 5: Account metadata enrichment in Security Hub finding’s UserDefinedFields field

      Figure 5: Account metadata enrichment in Security Hub finding’s UserDefinedFields field

      Note : The specific attributes you will notice within the UserDefinedFields could be different from the aforementioned screenshot. Attributes shown depends on your tagging configuration and the alternate contact configuration. At the very least, you shall start to see the AccountName and OU fields.

    1. Once you concur that the answer is working needlessly to say, delete the stand-alone security group TestSecHubEnrichmentSG , that was designed for testing purposes.

Create custom insights utilizing the enriched attributes

You should use the attributes obtainable in the UserDefinedFields in the Security Hub finding to filter the findings. Allowing you generate custom Security Hub reports and Insight tailored to fit your organization’s needs. The example shown in Figure 6 below creates a custom Security Hub Insight for findings grouped by severity for a particular owner, utilizing the Owner attribute within the UserDefinedFields object of the Security Hub finding.

Figure 6: Custom Insight with Account metadata filters

Figure 6: Custom Insight with Account metadata filters

Event Bridge rule for response or remediation action using enriched attributes

You can even utilize the attributes in the UserDefinedFields object of the Security Hub finding within the EventBridge rule to take specific response or remediation actions predicated on values in the attributes. In the example below, you can view the way the Environment attribute may be used within the EventBridge rule configuration to trigger specific actions only once value matches PROD .


  "detail-type": ["Security Hub Findings - Imported"],
  "source": ["aws.securityhub"],
  "detail": 
    "findings": 
      "RecordState": ["ACTIVE"],
      "UserDefinedFields": 
        "Environment": "PROD"

Conclusion

This website post walks you by way of a treatment for enrich AWS Security Hub findings with AWS account related metadata using Amazon EventBridge notifications and AWS Lambda. By enriching the Security Hub findings with account related information, your security teams have better visibility, additional insights and improved capability to create targeted reports for specific business or account teams, helping them prioritize and improve overall security response. For more information, see:

When you have feedback concerning this post, submit comments in the Comments section below. If any questions are had by you concerning this post, take up a thread on the AWS Security Hub forum.

 

Want more AWS Security news? Follow us on Twitter.