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).

BatchImportFindings for finding providers

Finding providers can use the BatchImportFindings operation to create new findings in Amazon Security Hub Cloud Security Posture Management (CSPM). They can also use this operation to update findings that they created. Finding providers can't update findings that they didn't create.

Customers, SIEMs, ticketing, SOAR, and other types of tools must use the BatchUpdateFindings operation to make updates related to their investigation of findings from finding providers. For more information, see BatchUpdateFindings for customers.

When Security Hub CSPM receives a BatchImportFindings request to create or update a finding, it automatically generates a Security Hub Findings - Imported event in Amazon EventBridge. You can take automated action on that event. For more information, see Using EventBridge for automated response and remediation.

Prerequisites for using BatchImportFindings

BatchImportFindings must be called by one of the following:

Security Hub CSPM can only accept finding updates for accounts that have Security Hub CSPM enabled. The finding provider also must be enabled. If Security Hub CSPM is disabled, or the finding provider integration is not enabled, then the findings are returned in the FailedFindings list, with an InvalidAccess error.

Determining whether to create or update a finding

To determine whether to create or update a finding, Security Hub CSPM checks the ID field. If the value of ID doesn't match an existing finding, Security Hub CSPM creates a new finding.

If ID matches an existing finding, Security Hub CSPM checks the UpdatedAt field for the update, and proceeds as follows:

Restrictions on finding updates with BatchImportFindings

Finding providers can't use BatchImportFindings to update the following attributes of an existing finding:

Security Hub CSPM ignores any content provided in a BatchImportFindings request for these attributes. Customers, or entities acting on their behalf (such as ticketing tools), can use BatchUpdateFindings to update these attributes.

Updating findings with FindingProviderFields

Finding providers also shouldn't use BatchImportFindings to update the following top-level attributes in the Amazon Security Finding Format (ASFF):

Instead, finding providers should use the FindingProviderFields object to provide values for these attributes.

Example

"FindingProviderFields": {
    "Confidence": 42,
    "Criticality": 99,
    "RelatedFindings":[
      { 
        "ProductArn": "arn:aws-cn: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 CSPM handles values in the top-level attributes and in FindingProviderFields as follows.