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 AWS 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 does not 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.

• Confidence

• Criticality

• Note

• RelatedFindings

• Severity

• Types

• UserDefinedFields

• VerificationState

• Workflow

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:

• Action is securityhub:BatchUpdateFindings

• Effect is Deny

• For Condition, you can deny a BatchUpdateFindings request based on the following:

  • The finding includes a specific field.

  • The finding includes a specific field value.

Condition keys

These are the condition keys for restricting access to BatchUpdateFindings.

ASFF field

The condition key for an ASFF field is as follows:

securityhub:ASFFSyntaxPath/<fieldName>

Replace <fieldName> with the ASFF field. When configuring access to BatchUpdateFindings, include one or more specific ASFF fields in your IAM policy rather than a parent-level field. For example, to restrict access to the Workflow.Status field, you must include securityhub:ASFFSyntaxPath/Workflow.Status in your policy instead of the Workflow parent-level field.

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": {
                "ForAnyValue: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": {
    "ForAnyValue:StringEquals": {
        "securityhub:ASFFSyntaxPath/Workflow.Status": [
            "RESOLVED",
            "NOTIFIED"
        ]
    }
}

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

In the AWS 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 AWS 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:securityhub:us-west-1:123456789012:subscription/pci-dss/v/3.2.1/PCI.Lambda.2/finding/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",ProductArn="arn:aws:securityhub:us-west-2::product/aws/securityhub" Id="arn:aws:securityhub:us-west-1:123456789012:subscription/pci-dss/v/3.2.1/PCI.Lambda.2/finding/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",ProductArn="arn:aws: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:securityhub:us-west-1:123456789012:subscription/pci-dss/v/3.2.1/PCI.Lambda.2/finding/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",ProductArn="arn:aws:securityhub:us-west-1::product/aws/securityhub" Id="arn:aws:securityhub:us-west-1:123456789012:subscription/pci-dss/v/3.2.1/PCI.Lambda.2/finding/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",ProductArn="arn:aws:securityhub:us-west-1::product/aws/securityhub" --note Text="Known issue that is not a risk.",UpdatedBy="user1" --severity Label="LOW" --workflow Status="RESOLVED"