Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using BatchUpdateFindings to update a finding

The BatchUpdateFindings action is used to update information related to a customer's processing of findings from finding providers. It can be used by a customer or by a SIEM, ticketing, incident management, or SOAR tool that works on behalf of a customer. You can use BatchUpdateFindings to update specific fields in the Amazon Security Finding Format (ASFF).

You can't use BatchUpdateFindings to create new findings. You can use it to update up to 100 findings at a time.

Whenever Security Hub receives a BatchUpdateFindings request to update a finding, it automatically generates a Security Hub Findings - Imported event in Amazon EventBridge. See Automated response and remediation.

BatchUpdateFindings doesn't change the UpdatedAt field for the finding. UpdatedAt only reflects the most recent update from the finding provider.

Available fields for BatchUpdateFindings

Administrator accounts can use >BatchUpdateFindings to update findings for their account or for their member accounts. Member accounts can use >BatchUpdateFindings to update findings for their account.

Customers can only use >BatchUpdateFindings to update the following fields and objects.

By default, administrator and member accounts have access to all of the above fields and field values. Security Hub also provides context keys to allow you to restrict access to fields and field values.

For example, you might only allow member accounts to set Workflow.Status to RESOLVED. Or you might not want to allow member accounts to change Severity.Label.

Configuring access to BatchUpdateFindings

You can configure IAM policies to restrict access to using BatchUpdateFindings to update fields and field values.

In a statement to restrict access to BatchUpdateFindings, use the following values:

Condition keys

These are the condition keys for restricting access to BatchUpdateFindings.

Disallowing all updates to a field

To prevent a user from making any update to a specific field, use a condition like this:

 "Condition": {
                "Null": {
                    "securityhub:ASFFSyntaxPath/<fieldName>": "false"
               }
}

For example, the following statement indicates that BatchUpdateFindings can't be used to update the workflow status.

{
    "Sid": "VisualEditor0",
    "Effect": "Deny",
    "Action": "securityhub:BatchUpdateFindings",
    "Resource": "*",
    "Condition": {
        "Null": {
            "securityhub:ASFFSyntaxPath/Workflow.Status": "false"
        }
    }
}

Disallowing specific field values

To prevent a user from setting a field to a specific value, use a condition like this:

"Condition": {
                "StringEquals": {
                    "securityhub:ASFFSyntaxPath/<fieldName>": "<fieldValue>"
               }
}

For example, the following statement indicates that BatchUpdateFindings can't be used to set Workflow.Status to SUPPRESSED.

{
    "Sid": "VisualEditor0",
    "Effect": "Deny",
    "Action": "securityhub:BatchUpdateFindings",
    "Resource": "*",
    "Condition": {
    "StringEquals": {
        "securityhub:ASFFSyntaxPath/Workflow.Status": "SUPPRESSED"
    }
}

You can also provide a list of values that are not permitted.

 "Condition": {
                "StringEquals": {
                    "securityhub:ASFFSyntaxPath/<fieldName>": [ "<fieldValue1>", "<fieldValue2>", "<fieldValuen>" ]
               }
}

For example, the following statement indicates that BatchUpdateFindings can't be used to set Workflow.Status to either RESOLVED or SUPPRESSED.

{
    "Sid": "VisualEditor0",
    "Effect": "Deny",
    "Action": "securityhub:BatchUpdateFindings",
    "Resource": "*",
    "Condition": {
    "StringEquals": {
        "securityhub:ASFFSyntaxPath/Workflow.Status": [
            "RESOLVED",
            "NOTIFIED"
        ]
    }
}

Using the batch-update-findings command from the Amazon CLI

In the Amazon Command Line Interface, you use the batch-update-findings command to update the findings.

For each finding to update, you provide both the finding ID and the ARN of the product that generated the finding.

--finding-identifiers ID="<findingID1>",ProductArn="<productARN>" ID="<findingID2>",ProductArn="<productARN2>"

When you provide the attributes to update, you can either use a JSON format or a shortcut format.

Here is an example of an update to the Note object that uses the JSON format:

--note '{"Text": "Known issue that is not a risk.", "UpdatedBy": "user1"}'

Here is the same update that uses the shortcut format:

--note Text="Known issue that is not a risk.",UpdatedBy="user1"

The Amazon CLI Command Reference provides the JSON and shortcut syntax for each field.

The following >batch-update-findings example updates two findings to add a note, change the severity label, and resolve them.

aws securityhub batch-update-findings --finding-identifiers Id="arn:aws-cn:securityhub:us-west-1:123456789012:subscription/pci-dss/v/3.2.1/PCI.Lambda.2/finding/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",ProductArn="arn:aws-cn:securityhub:us-west-2::product/aws/securityhub" Id="arn:aws-cn:securityhub:us-west-1:123456789012:subscription/pci-dss/v/3.2.1/PCI.Lambda.2/finding/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",ProductArn="arn:aws-cn:securityhub:us-west-1::product/aws/securityhub" --note '{"Text": "Known issue that is not a risk.", "UpdatedBy": "user1"}' --severity '{"Label": "LOW"}' --workflow '{"Status": "RESOLVED"}'

This is the same example, but uses the shortcuts instead of JSON.

aws securityhub batch-update-findings --finding-identifiers Id="arn:aws-cn:securityhub:us-west-1:123456789012:subscription/pci-dss/v/3.2.1/PCI.Lambda.2/finding/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",ProductArn="arn:aws-cn:securityhub:us-west-1::product/aws/securityhub" Id="arn:aws-cn:securityhub:us-west-1:123456789012:subscription/pci-dss/v/3.2.1/PCI.Lambda.2/finding/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",ProductArn="arn:aws-cn:securityhub:us-west-1::product/aws/securityhub" --note Text="Known issue that is not a risk.",UpdatedBy="user1" --severity Label="LOW" --workflow Status="RESOLVED"