Using BatchImportFindings to create and update findings
Finding providers use the BatchImportFindings
API operation to create new findings
and to update information about the findings they created. They cannot update findings
that they did not create.
Customers, SIEMs, ticketing tools, and SOAR tools use BatchUpdateFindings
to make updates related to their
investigation of findings from finding providers. See Using
BatchUpdateFindings to update a finding.
Whenever AWS Security Hub receives a BatchImportFindings
request to either create or update a
finding, it automatically generates a Security Hub Findings
- Imported event in Amazon EventBridge. See Automated response and remediation.
Requirements for accounts and batch size
BatchImportFindings
must be called by one of the
following:
-
The account that is associated with the findings. The identifier of the associated account is the value of the
AwsAccountId
attribute for the finding. -
An account that is allow-listed for an official Security Hub partner integration.
Security Hub can only accept finding updates for accounts that have Security Hub enabled. The
finding provider also must be enabled. If Security Hub is disabled, or the finding provider
integration is not enabled, then the findings are returned in the
FailedFindings
list, with an InvalidAccess
error.
BatchImportFindings
accepts up to 100 findings per
batch, up to 240 KB per finding, and up to 6 MB per batch. The throttle rate limit
is 10 TPS per account per Region, with a burst of 30 TPS.
Determining whether to create or update a finding
To determine whether to create or update a finding, Security Hub checks the
ID
field. If the value of ID
does not match an
existing finding, then a new finding is created.
If ID
does match an existing finding, then Security Hub checks the
UpdatedAt
field for the update.
-
If
UpdatedAt
on the update matches or occurs beforeUpdatedAt
on the existing finding, then the update is ignored. -
If
UpdatedAt
on the update occurs afterUpdatedAt
on the existing finding, then the existing finding is updated.
Restricted attributes for BatchImportFindings
For an existing finding, finding providers can't use BatchImportFindings
to update the following
attributes and objects. These attributes can only be updated using BatchUpdateFindings
.
-
Note
-
UserDefinedFields
-
VerificationState
-
Workflow
Security Hub ignores any content provided in a BatchImportFindings
request for those attributes and objects.
Customers, or other providers acting on their behalf, use BatchUpdateFindings
to update them.
Using FindingProviderFields
Finding providers also shouldn't use BatchImportFindings
to update the following
attributes.
-
Confidence
-
Criticality
-
RelatedFindings
-
Severity
-
Types
Instead, finding providers use the FindingProviderFields object to provide values for these attributes.
Example
"FindingProviderFields": { "Confidence": 42, "Criticality": 99, "RelatedFindings":[ { "ProductArn": "arn:aws:securityhub:us-west-2::product/aws/guardduty", "Id": "123e4567-e89b-12d3-a456-426655440000" } ], "Severity": { "Label": "MEDIUM", "Original": "MEDIUM" }, "Types": [ "Software and Configuration Checks/Vulnerabilities/CVE" ] }
For BatchImportFindings
requests, Security Hub handles values in
the top-level attributes and in FindingProviderFields as follows.
- (Preferred)
BatchImportFindings
provides a value for an attribute in FindingProviderFields, but does not provide a value for the corresponding top-level attribute. -
For example,
BatchImportFindings
providesFindingProviderFields.Confidence
, but does not provideConfidence
. This is the preferred option forBatchImportFindings
requests.Security Hub updates the value of the attribute in
FindingProviderFields
.It replicates the value to the top-level attribute only if the attribute wasn't already updated by
BatchUpdateFindings
. BatchImportFindings
provides a value for a top-level attribute, but does not provide a value for the corresponding attribute inFindingProviderFields
.-
For example,
BatchImportFindings
providesConfidence
, but does not provideFindingProviderFields.Confidence
.Security Hub uses the value to update the attribute in
FindingProviderFields
. It overwrites any existing value.Security Hub updates the top-level attribute only if the attribute was not already updated by
BatchUpdateFindings
. BatchImportFindings
provides a value for both a top-level attribute and the corresponding attribute inFindingProviderFields
.-
For example,
BatchImportFindings
provides bothConfidence
andFindingProviderFields.Confidence
.For a new finding, Security Hub uses the value in
FindingProviderFields
to populate both the top-level attribute and the corresponding attribute inFindingProviderFields
. It doesn't use the provided top-level attribute value.For an existing finding, Security Hub uses both values. However, it updates the top-level attribute value only if the attribute was not already updated by
BatchUpdateFindings
.
Using the batch-import-findings command from the AWS CLI
In the AWS Command Line Interface, you use the batch-import-findings
You provide each finding as a JSON object.
Example
aws securityhub batch-import-findings --findings [{ "AwsAccountId": "123456789012", "CreatedAt": "2019-08-07T17:05:54.832Z", "Description": "Vulnerability in a CloudTrail trail", "GeneratorId": "arn:aws:securityhub:::ruleset/cis-aws-foundations-benchmark/v/1.2.0/rule/2.2", "Id": "Id1", "ProductArn": "arn:aws:securityhub:us-west-1:123456789012:product/123456789012/default", "Resources": [ { "Id": "arn:aws:cloudtrail:us-west-1:123456789012:trail/TrailName", "Partition": "aws", "Region": "us-west-1", "Type": "AwsCloudTrailTrail" } ], "SchemaVersion": "2018-10-08", "Title": "CloudTrail trail vulnerability", "UpdatedAt": "2020-06-02T16:05:54.832Z", "Types": [ "Software and Configuration Checks/Vulnerabilities/CVE" ], "Severity": { "Label": "INFORMATIONAL", "Original": "0" } }]'