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
issecurityhub:BatchUpdateFindings
-
Effect
isDeny
-
For
Condition
, you can deny aBatchUpdateFindings
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
with the ASFF field. When configuring access to<fieldName>
BatchUpdateFindings
, include one or more specific ASFF fields in your IAM policy rather than a parent-level field. For example, to restrict access to theWorkflow.Status
field, you must includesecurityhub:ASFFSyntaxPath/Workflow.Status
in your policy instead of theWorkflow
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": { "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 AWS CLI
In the AWS Command Line Interface, you use the batch-update-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"