SecurityHub / Client / get_finding_history

get_finding_history#

SecurityHub.Client.get_finding_history(**kwargs)#

Returns history for a Security Hub finding in the last 90 days. The history includes changes made to any fields in the Amazon Web Services Security Finding Format (ASFF).

Request Syntax

response = client.get_finding_history(
    FindingIdentifier={
        'Id': 'string',
        'ProductArn': 'string'
    },
    StartTime=datetime(2015, 1, 1),
    EndTime=datetime(2015, 1, 1),
    NextToken='string',
    MaxResults=123
)

Parameters:

FindingIdentifier (dict) –
[REQUIRED]

Identifies which finding to get the finding history for.
- Id (string) – [REQUIRED]
  
  The identifier of the finding that was specified by the finding provider.
- ProductArn (string) – [REQUIRED]
  
  The ARN generated by Security Hub that uniquely identifies a product that generates findings. This can be the ARN for a third-party product that is integrated with Security Hub, or the ARN for a custom integration.
StartTime (datetime) –
A timestamp that indicates the start time of the requested finding history.

If you provide values for both StartTime and EndTime, Security Hub returns finding history for the specified time period. If you provide a value for StartTime but not for EndTime, Security Hub returns finding history from the StartTime to the time at which the API is called. If you provide a value for EndTime but not for StartTime, Security Hub returns finding history from the CreatedAt timestamp of the finding to the EndTime. If you provide neither StartTime nor EndTime, Security Hub returns finding history from the CreatedAt timestamp of the finding to the time at which the API is called. In all of these scenarios, the response is limited to 100 results, and the maximum time period is limited to 90 days.

This field accepts only the specified formats. Timestamps can end with Z or ("+" / "-") time-hour [":" time-minute]. The time-secfrac after seconds is limited to a maximum of 9 digits. The offset is bounded by +/-18:00. Here are valid timestamp formats with examples:
- YYYY-MM-DDTHH:MM:SSZ (for example, 2019-01-31T23:00:00Z)
- YYYY-MM-DDTHH:MM:SS.mmmmmmmmmZ (for example, 2019-01-31T23:00:00.123456789Z)
- YYYY-MM-DDTHH:MM:SS+HH:MM (for example, 2024-01-04T15:25:10+17:59)
- YYYY-MM-DDTHH:MM:SS-HHMM (for example, 2024-01-04T15:25:10-1759)
- YYYY-MM-DDTHH:MM:SS.mmmmmmmmm+HH:MM (for example, 2024-01-04T15:25:10.123456789+17:59)
EndTime (datetime) –
An ISO 8601-formatted timestamp that indicates the end time of the requested finding history.

If you provide values for both StartTime and EndTime, Security Hub returns finding history for the specified time period. If you provide a value for StartTime but not for EndTime, Security Hub returns finding history from the StartTime to the time at which the API is called. If you provide a value for EndTime but not for StartTime, Security Hub returns finding history from the CreatedAt timestamp of the finding to the EndTime. If you provide neither StartTime nor EndTime, Security Hub returns finding history from the CreatedAt timestamp of the finding to the time at which the API is called. In all of these scenarios, the response is limited to 100 results, and the maximum time period is limited to 90 days.

This field accepts only the specified formats. Timestamps can end with Z or ("+" / "-") time-hour [":" time-minute]. The time-secfrac after seconds is limited to a maximum of 9 digits. The offset is bounded by +/-18:00. Here are valid timestamp formats with examples:
- YYYY-MM-DDTHH:MM:SSZ (for example, 2019-01-31T23:00:00Z)
- YYYY-MM-DDTHH:MM:SS.mmmmmmmmmZ (for example, 2019-01-31T23:00:00.123456789Z)
- YYYY-MM-DDTHH:MM:SS+HH:MM (for example, 2024-01-04T15:25:10+17:59)
- YYYY-MM-DDTHH:MM:SS-HHMM (for example, 2024-01-04T15:25:10-1759)
- YYYY-MM-DDTHH:MM:SS.mmmmmmmmm+HH:MM (for example, 2024-01-04T15:25:10.123456789+17:59)
NextToken (string) – A token for pagination purposes. Provide NULL as the initial value. In subsequent requests, provide the token included in the response to get up to an additional 100 results of finding history. If you don’t provide NextToken, Security Hub returns up to 100 results of finding history for each request.
MaxResults (integer) – The maximum number of results to be returned. If you don’t provide it, Security Hub returns up to 100 results of finding history.

Return type:

dict

Returns:

Response Syntax

{
    'Records': [
        {
            'FindingIdentifier': {
                'Id': 'string',
                'ProductArn': 'string'
            },
            'UpdateTime': datetime(2015, 1, 1),
            'FindingCreated': True|False,
            'UpdateSource': {
                'Type': 'BATCH_UPDATE_FINDINGS'|'BATCH_IMPORT_FINDINGS',
                'Identity': 'string'
            },
            'Updates': [
                {
                    'UpdatedField': 'string',
                    'OldValue': 'string',
                    'NewValue': 'string'
                },
            ],
            'NextToken': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

(dict) –
- Records (list) –
  
  A list of events that altered the specified finding during the specified time period.
  - (dict) –
    
    A list of events that changed the specified finding during the specified time period. Each record represents a single finding change event.
    - FindingIdentifier (dict) –
      
      Identifies which finding to get the finding history for.
      - Id (string) –
        
        The identifier of the finding that was specified by the finding provider.
      - ProductArn (string) –
        
        The ARN generated by Security Hub that uniquely identifies a product that generates findings. This can be the ARN for a third-party product that is integrated with Security Hub, or the ARN for a custom integration.
    - UpdateTime (datetime) –
      
      A timestamp that indicates when Security Hub processed the updated finding record.
      
      This field accepts only the specified formats. Timestamps can end with Z or ("+" / "-") time-hour [":" time-minute]. The time-secfrac after seconds is limited to a maximum of 9 digits. The offset is bounded by +/-18:00. Here are valid timestamp formats with examples:
      - YYYY-MM-DDTHH:MM:SSZ (for example, 2019-01-31T23:00:00Z)
      - YYYY-MM-DDTHH:MM:SS.mmmmmmmmmZ (for example, 2019-01-31T23:00:00.123456789Z)
      - YYYY-MM-DDTHH:MM:SS+HH:MM (for example, 2024-01-04T15:25:10+17:59)
      - YYYY-MM-DDTHH:MM:SS-HHMM (for example, 2024-01-04T15:25:10-1759)
      - YYYY-MM-DDTHH:MM:SS.mmmmmmmmm+HH:MM (for example, 2024-01-04T15:25:10.123456789+17:59)
    - FindingCreated (boolean) –
      
      Identifies whether the event marks the creation of a new finding. A value of True means that the finding is newly created. A value of False means that the finding isn’t newly created.
    - UpdateSource (dict) –
      
      Identifies the source of the event that changed the finding. For example, an integrated Amazon Web Service or third-party partner integration may call BatchImportFindings, or an Security Hub customer may call BatchUpdateFindings.
      - Type (string) –
        
        Describes the type of finding change event, such as a call to BatchImportFindings (by an integrated Amazon Web Service or third party partner integration) or BatchUpdateFindings (by a Security Hub customer).
      - Identity (string) –
        
        The identity of the source that initiated the finding change event. For example, the Amazon Resource Name (ARN) of a partner that calls BatchImportFindings or of a customer that calls BatchUpdateFindings.
    - Updates (list) –
      
      An array of objects that provides details about the finding change event, including the Amazon Web Services Security Finding Format (ASFF) field that changed, the value of the field before the change, and the value of the field after the change.
      - (dict) –
        
        An array of objects that provides details about a change to a finding, including the Amazon Web Services Security Finding Format (ASFF) field that changed, the value of the field before the change, and the value of the field after the change.
        
        UpdatedField (string) –
        
        The ASFF field that changed during the finding change event.
        
        OldValue (string) –
        
        The value of the ASFF field before the finding change event.
        
        NewValue (string) –
        
        The value of the ASFF field after the finding change event. To preserve storage and readability, Security Hub omits this value if FindingHistoryRecord exceeds database limits.
    - NextToken (string) –
      
      A token for pagination purposes. Provide this token in the subsequent request to GetFindingsHistory to get up to an additional 100 results of history for the same finding that you specified in your initial request.
- NextToken (string) –
  
  A token for pagination purposes. Provide this token in the subsequent request to GetFindingsHistory to get up to an additional 100 results of history for the same finding that you specified in your initial request.

Exceptions

SecurityHub.Client.exceptions.InternalException
SecurityHub.Client.exceptions.InvalidInputException
SecurityHub.Client.exceptions.InvalidAccessException
SecurityHub.Client.exceptions.LimitExceededException