SecurityHub / Paginator / GetFindingHistory

GetFindingHistory#

class SecurityHub.Paginator.GetFindingHistory#

paginator = client.get_paginator('get_finding_history')

paginate(**kwargs)#

Creates an iterator that will paginate through responses from SecurityHub.Client.get_finding_history().

Request Syntax

response_iterator = paginator.paginate(
    FindingIdentifier={
        'Id': 'string',
        'ProductArn': 'string'
    },
    StartTime=datetime(2015, 1, 1),
    EndTime=datetime(2015, 1, 1),
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)

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) –
An ISO 8601-formatted timestamp that indicates the start time of the requested finding history. A correctly formatted example is 2020-05-21T20:16:34.724Z. The value cannot contain spaces, and date and time should be separated by T. For more information, see RFC 3339 section 5.6, Internet Date/Time Format.

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.
EndTime (datetime) –
An ISO 8601-formatted timestamp that indicates the end time of the requested finding history. A correctly formatted example is 2020-05-21T20:16:34.724Z. The value cannot contain spaces, and date and time should be separated by T. For more information, see RFC 3339 section 5.6, Internet Date/Time Format.

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.
PaginationConfig (dict) –
A dictionary that provides parameters to control pagination.
- MaxItems (integer) –
  
  The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.
- PageSize (integer) –
  
  The size of each page.
- StartingToken (string) –
  
  A token to specify where to start paginating. This is the NextToken from a previous response.

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'
        },
    ],

}

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) –
      
      An ISO 8601-formatted timestamp that indicates when Security Hub processed the updated finding record.
      
      A correctly formatted example is 2020-05-21T20:16:34.724Z. The value cannot contain spaces, and date and time should be separated by T. For more information, see RFC 3339 section 5.6, Internet Date/Time Format.
    - 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.