Skip to content

Get Finding History

securityhub_get_finding_history R Documentation

Returns history for a Security Hub finding in the last 90 days

Description

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

Usage

securityhub_get_finding_history(FindingIdentifier, StartTime, EndTime,
  NextToken, MaxResults)

Arguments

FindingIdentifier

[required]

StartTime

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

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

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

The maximum number of results to be returned. If you don’t provide it, Security Hub returns up to 100 results of finding history.

Value

A list with the following syntax: 

list(
  Records = list(
    list(
      FindingIdentifier = list(
        Id = "string",
        ProductArn = "string"
      ),
      UpdateTime = as.POSIXct(
        "2015-01-01"
      ),
      FindingCreated = TRUE|FALSE,
      UpdateSource = list(
        Type = "BATCH_UPDATE_FINDINGS"|"BATCH_IMPORT_FINDINGS",
        Identity = "string"
      ),
      Updates = list(
        list(
          UpdatedField = "string",
          OldValue = "string",
          NewValue = "string"
        )
      ),
      NextToken = "string"
    )
  ),
  NextToken = "string"
)

Request syntax

svc$get_finding_history(
  FindingIdentifier = list(
    Id = "string",
    ProductArn = "string"
  ),
  StartTime = as.POSIXct(
    "2015-01-01"
  ),
  EndTime = as.POSIXct(
    "2015-01-01"
  ),
  NextToken = "string",
  MaxResults = 123
)

Examples

## Not run: 
# The following example retrieves the history of the specified finding
# during the specified time frame. If the time frame permits, Security Hub
# returns finding history for the last 90 days.
svc$get_finding_history(
  EndTime = "2021-09-31T15:53:35.573Z",
  FindingIdentifier = list(
    Id = "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    ProductArn = "arn:aws:securityhub:us-west-2:123456789012:product/123456789012/default"
  ),
  MaxResults = 2L,
  StartTime = "2021-09-30T15:53:35.573Z"
)

## End(Not run)