BatchImportFindings for finding providers - AWS Security Hub
Prerequisites for using BatchImportFindingsDetermining whether to create or update a findingRestrictions on finding updates with BatchImportFindingsUpdating findings with FindingProviderFields

BatchImportFindings for finding providers

Finding providers can use the BatchImportFindings operation to create new Security Hub findings and update findings they created. They can't update findings that they didn't create.

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

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. You can take automated action on that event. For information, see Using EventBridge for automated response and remediation.

Prerequisites for using BatchImportFindings

BatchImportFindings must be called by one of the following:

  • The account that is associated with the findings. The identifier of the associated account must match the value of the AwsAccountId attribute for the finding.

  • An account that is allow-listed as 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.

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 doesn't match an existing finding, Security Hub creates a new finding.

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

  • If UpdatedAt on the update matches or occurs before UpdatedAt on the existing finding, Security Hub ignores the update request.

  • If UpdatedAt on the update occurs after UpdatedAt on the existing finding, Security Hub updates the existing finding.

Restrictions on finding updates with BatchImportFindings

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

  • Note

  • UserDefinedFields

  • VerificationState

  • Workflow

Security Hub 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 AWS Security Finding Format (ASFF):

  • Confidence

  • Criticality

  • RelatedFindings

  • Severity

  • Types

Instead, finding providers should 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.