SecurityHub / Client / batch_update_findings_v2

batch_update_findings_v2¶

SecurityHub.Client.batch_update_findings_v2(**kwargs)¶

Updates information about a customer’s investigation into a finding. Delegated administrator accounts can update findings for their account and their member accounts. Member accounts can update findings for their own account.

BatchUpdateFindings and BatchUpdateFindingsV2 both use securityhub:BatchUpdateFindings in the Action element of an IAM policy statement. You must have permission to perform the securityhub:BatchUpdateFindings action. You can configure IAM policies to restrict access to specific finding fields or field values by using the securityhub:OCSFSyntaxPath/<fieldName> condition key, where <fieldName> is one of the following supported fields: SeverityId, StatusId, or Comment.

To prevent a user from updating a specific field, use a Null condition with securityhub:OCSFSyntaxPath/<fieldName> set to "false". To prevent a user from setting a field to a specific value, use a StringEquals condition with securityhub:OCSFSyntaxPath/<fieldName> set to the disallowed value or list of values.

Updates from BatchUpdateFindingsV2 don’t affect the value of finding_info.modified_time, finding_info.modified_time_dt, time, or time_dt for a finding.

Request Syntax

response = client.batch_update_findings_v2(
    MetadataUids=[
        'string',
    ],
    FindingIdentifiers=[
        {
            'CloudAccountUid': 'string',
            'FindingInfoUid': 'string',
            'MetadataProductUid': 'string'
        },
    ],
    Comment='string',
    SeverityId=123,
    StatusId=123
)

Parameters:

MetadataUids (list) –
The list of finding metadata.uid to indicate findings to update. Finding metadata.uid is a globally unique identifier associated with the finding. Customers cannot use MetadataUids together with FindingIdentifiers.
- (string) –
FindingIdentifiers (list) –
Provides information to identify a specific V2 finding.
- (dict) –
  
  Provides a standard to identify security findings using OCSF.
  - CloudAccountUid (string) – [REQUIRED]
    
    Finding cloud.account.uid, which is a unique identifier in the Amazon Web Services account..
  - FindingInfoUid (string) – [REQUIRED]
    
    Finding finding_info.uid, which is a unique identifier for the finding from the finding provider.
  - MetadataProductUid (string) – [REQUIRED]
    
    Finding metadata.product.uid, which is a unique identifier for the product.
Comment (string) – The updated value for a user provided comment about the finding. Minimum character length 1. Maximum character length 512.
SeverityId (integer) – The updated value for the normalized severity identifier. The severity ID is an integer with the allowed enum values [0, 1, 2, 3, 4, 5, 6, 99]. When customer provides the updated severity ID, the string sibling severity will automatically be updated in the finding.
StatusId (integer) – The updated value for the normalized status identifier. The status ID is an integer with the allowed enum values [0, 1, 2, 3, 4, 5, 99]. When customer provides the updated status ID, the string sibling status will automatically be updated in the finding.

Return type:

dict

Returns:

Response Syntax

{
    'ProcessedFindings': [
        {
            'FindingIdentifier': {
                'CloudAccountUid': 'string',
                'FindingInfoUid': 'string',
                'MetadataProductUid': 'string'
            },
            'MetadataUid': 'string'
        },
    ],
    'UnprocessedFindings': [
        {
            'FindingIdentifier': {
                'CloudAccountUid': 'string',
                'FindingInfoUid': 'string',
                'MetadataProductUid': 'string'
            },
            'MetadataUid': 'string',
            'ErrorCode': 'ResourceNotFoundException'|'ValidationException'|'InternalServerException'|'ConflictException',
            'ErrorMessage': 'string'
        },
    ]
}

Response Structure

(dict) –
- ProcessedFindings (list) –
  
  The list of findings that were updated successfully.
  - (dict) –
    
    The list of findings that were updated.
    - FindingIdentifier (dict) –
      
      The finding identifier of a processed finding.
      - CloudAccountUid (string) –
        
        Finding cloud.account.uid, which is a unique identifier in the Amazon Web Services account..
      - FindingInfoUid (string) –
        
        Finding finding_info.uid, which is a unique identifier for the finding from the finding provider.
      - MetadataProductUid (string) –
        
        Finding metadata.product.uid, which is a unique identifier for the product.
    - MetadataUid (string) –
      
      The metadata.uid of a processed finding.
- UnprocessedFindings (list) –
  
  The list of V2 findings that were not updated.
  - (dict) –
    
    The list of findings that were not updated.
    - FindingIdentifier (dict) –
      
      The finding identifier of an unprocessed finding.
      - CloudAccountUid (string) –
        
        Finding cloud.account.uid, which is a unique identifier in the Amazon Web Services account..
      - FindingInfoUid (string) –
        
        Finding finding_info.uid, which is a unique identifier for the finding from the finding provider.
      - MetadataProductUid (string) –
        
        Finding metadata.product.uid, which is a unique identifier for the product.
    - MetadataUid (string) –
      
      The metadata.uid of an unprocessed finding.
    - ErrorCode (string) –
      
      Indicates the specific type of error preventing successful processing of a finding during a batch update operation.
    - ErrorMessage (string) –
      
      A detailed description of why a finding could not be processed during a batch update operation.

Exceptions

SecurityHub.Client.exceptions.InternalServerException
SecurityHub.Client.exceptions.ValidationException
SecurityHub.Client.exceptions.AccessDeniedException
SecurityHub.Client.exceptions.ThrottlingException
SecurityHub.Client.exceptions.ConflictException