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 before UpdatedAt on the existing finding, then the update is ignored.

• If UpdatedAt on the update occurs after UpdatedAt 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 provides FindingProviderFields.Confidence, but does not provide Confidence. This is the preferred option for BatchImportFindings 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 in FindingProviderFields.

For example, BatchImportFindings provides Confidence, but does not provide FindingProviderFields.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 in FindingProviderFields.

For example, BatchImportFindings provides both Confidence and FindingProviderFields.Confidence.

For a new finding, Security Hub uses the value in FindingProviderFields to populate both the top-level attribute and the corresponding attribute in FindingProviderFields. 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 command to create or update 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"
        }
    }]'