Amazon GuardDuty

2024/09/11 - Amazon GuardDuty - 1 updated api methods

Changes  Add support for new statistic types in GetFindingsStatistics.

GetFindingsStatistics (updated) Link ΒΆ
Changes (request, response)
Request
{'GroupBy': 'ACCOUNT | DATE | FINDING_TYPE | RESOURCE | SEVERITY',
 'MaxResults': 'integer',
 'OrderBy': 'ASC | DESC'}
Response
{'FindingStatistics': {'GroupedByAccount': [{'AccountId': 'string',
                                             'LastGeneratedAt': 'timestamp',
                                             'TotalFindings': 'integer'}],
                       'GroupedByDate': [{'Date': 'timestamp',
                                          'LastGeneratedAt': 'timestamp',
                                          'Severity': 'double',
                                          'TotalFindings': 'integer'}],
                       'GroupedByFindingType': [{'FindingType': 'string',
                                                 'LastGeneratedAt': 'timestamp',
                                                 'TotalFindings': 'integer'}],
                       'GroupedByResource': [{'AccountId': 'string',
                                              'LastGeneratedAt': 'timestamp',
                                              'ResourceId': 'string',
                                              'ResourceType': 'string',
                                              'TotalFindings': 'integer'}],
                       'GroupedBySeverity': [{'LastGeneratedAt': 'timestamp',
                                              'Severity': 'double',
                                              'TotalFindings': 'integer'}]},
 'NextToken': 'string'}

Lists GuardDuty findings statistics for the specified detector ID.

You must provide either findingStatisticTypes or groupBy parameter, and not both. You can use the maxResults and orderBy parameters only when using groupBy .

There might be regional differences because some flags might not be available in all the Regions where GuardDuty is currently supported. For more information, see Regions and endpoints.

See also: AWS API Documentation

Request Syntax

client.get_findings_statistics(
    DetectorId='string',
    FindingStatisticTypes=[
        'COUNT_BY_SEVERITY',
    ],
    FindingCriteria={
        'Criterion': {
            'string': {
                'Eq': [
                    'string',
                ],
                'Neq': [
                    'string',
                ],
                'Gt': 123,
                'Gte': 123,
                'Lt': 123,
                'Lte': 123,
                'Equals': [
                    'string',
                ],
                'NotEquals': [
                    'string',
                ],
                'GreaterThan': 123,
                'GreaterThanOrEqual': 123,
                'LessThan': 123,
                'LessThanOrEqual': 123
            }
        }
    },
    GroupBy='ACCOUNT'|'DATE'|'FINDING_TYPE'|'RESOURCE'|'SEVERITY',
    OrderBy='ASC'|'DESC',
    MaxResults=123
)
type DetectorId

string

param DetectorId

[REQUIRED]

The ID of the detector whose findings statistics you want to retrieve.

type FindingStatisticTypes

list

param FindingStatisticTypes

The types of finding statistics to retrieve.

  • (string) --

type FindingCriteria

dict

param FindingCriteria

Represents the criteria that is used for querying findings.

  • Criterion (dict) --

    Represents a map of finding properties that match specified conditions and values when querying findings.

    • (string) --

      • (dict) --

        Contains information about the condition.

        • Eq (list) --

          Represents the equal condition to be applied to a single field when querying for findings.

          • (string) --

        • Neq (list) --

          Represents the not equal condition to be applied to a single field when querying for findings.

          • (string) --

        • Gt (integer) --

          Represents a greater than condition to be applied to a single field when querying for findings.

        • Gte (integer) --

          Represents a greater than or equal condition to be applied to a single field when querying for findings.

        • Lt (integer) --

          Represents a less than condition to be applied to a single field when querying for findings.

        • Lte (integer) --

          Represents a less than or equal condition to be applied to a single field when querying for findings.

        • Equals (list) --

          Represents an equal condition to be applied to a single field when querying for findings.

          • (string) --

        • NotEquals (list) --

          Represents a not equal condition to be applied to a single field when querying for findings.

          • (string) --

        • GreaterThan (integer) --

          Represents a greater than condition to be applied to a single field when querying for findings.

        • GreaterThanOrEqual (integer) --

          Represents a greater than or equal condition to be applied to a single field when querying for findings.

        • LessThan (integer) --

          Represents a less than condition to be applied to a single field when querying for findings.

        • LessThanOrEqual (integer) --

          Represents a less than or equal condition to be applied to a single field when querying for findings.

type GroupBy

string

param GroupBy

Displays the findings statistics grouped by one of the listed valid values.

type OrderBy

string

param OrderBy

Displays the sorted findings in the requested order. The default value of orderBy is DESC .

You can use this parameter only with the groupBy parameter.

type MaxResults

integer

param MaxResults

The maximum number of results to be returned in the response. The default value is 25.

You can use this parameter only with the groupBy parameter.

rtype

dict

returns

Response Syntax

{
    'FindingStatistics': {
        'CountBySeverity': {
            'string': 123
        },
        'GroupedByAccount': [
            {
                'AccountId': 'string',
                'LastGeneratedAt': datetime(2015, 1, 1),
                'TotalFindings': 123
            },
        ],
        'GroupedByDate': [
            {
                'Date': datetime(2015, 1, 1),
                'LastGeneratedAt': datetime(2015, 1, 1),
                'Severity': 123.0,
                'TotalFindings': 123
            },
        ],
        'GroupedByFindingType': [
            {
                'FindingType': 'string',
                'LastGeneratedAt': datetime(2015, 1, 1),
                'TotalFindings': 123
            },
        ],
        'GroupedByResource': [
            {
                'AccountId': 'string',
                'LastGeneratedAt': datetime(2015, 1, 1),
                'ResourceId': 'string',
                'ResourceType': 'string',
                'TotalFindings': 123
            },
        ],
        'GroupedBySeverity': [
            {
                'LastGeneratedAt': datetime(2015, 1, 1),
                'Severity': 123.0,
                'TotalFindings': 123
            },
        ]
    },
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • FindingStatistics (dict) --

      The finding statistics object.

      • CountBySeverity (dict) --

        Represents a list of map of severity to count statistics for a set of findings.

        • (string) --

          • (integer) --

      • GroupedByAccount (list) --

        Represents a list of map of accounts with a findings count associated with each account.

        • (dict) --

          Represents a list of map of accounts with the number of findings associated with each account.

          • AccountId (string) --

            The ID of the Amazon Web Services account.

          • LastGeneratedAt (datetime) --

            The timestamp at which the finding for this account was last generated.

          • TotalFindings (integer) --

            The total number of findings associated with an account.

      • GroupedByDate (list) --

        Represents a list of map of dates with a count of total findings generated on each date per severity level.

        • (dict) --

          Represents list a map of dates with a count of total findings generated on each date.

          • Date (datetime) --

            The timestamp when the total findings count is observed.

            For example, Date would look like "2024-09-05T17:00:00-07:00" whereas LastGeneratedAt would look like 2024-09-05T17:12:29-07:00".

          • LastGeneratedAt (datetime) --

            The timestamp at which the last finding in the findings count, was generated.

          • Severity (float) --

            The severity of the findings generated on each date.

          • TotalFindings (integer) --

            The total number of findings that were generated per severity level on each date.

      • GroupedByFindingType (list) --

        Represents a list of map of finding types with a count of total findings generated for each type.

        Based on the orderBy parameter, this request returns either the most occurring finding types or the least occurring finding types. If the orderBy parameter is ASC , this will represent the least occurring finding types in your account; otherwise, this will represent the most occurring finding types. The default value of orderBy is DESC .

        • (dict) --

          Information about each finding type associated with the groupedByFindingType statistics.

          • FindingType (string) --

            Name of the finding type.

          • LastGeneratedAt (datetime) --

            The timestamp at which this finding type was last generated in your environment.

          • TotalFindings (integer) --

            The total number of findings associated with generated for each distinct finding type.

      • GroupedByResource (list) --

        Represents a list of map of top resources with a count of total findings.

        • (dict) --

          Information about each resource type associated with the groupedByResource statistics.

          • AccountId (string) --

            The ID of the Amazon Web Services account.

          • LastGeneratedAt (datetime) --

            The timestamp at which the statistics for this resource was last generated.

          • ResourceId (string) --

            ID associated with each resource. The following list provides the mapping of the resource type and resource ID.

            Mapping of resource and resource ID

            • AccessKey - resource.accessKeyDetails.accessKeyId

            • Container - resource.containerDetails.id

            • ECSCluster - resource.ecsClusterDetails.name

            • EKSCluster - resource.eksClusterDetails.name

            • Instance - resource.instanceDetails.instanceId

            • KubernetesCluster - resource.kubernetesDetails.kubernetesWorkloadDetails.name

            • Lambda - resource.lambdaDetails.functionName

            • RDSDBInstance - resource.rdsDbInstanceDetails.dbInstanceIdentifier

            • S3Bucket - resource.s3BucketDetails.name

            • S3Object - resource.s3BucketDetails.name

          • ResourceType (string) --

            The type of resource.

          • TotalFindings (integer) --

            The total number of findings associated with this resource.

      • GroupedBySeverity (list) --

        Represents a list of map of total findings for each severity level.

        • (dict) --

          Information about severity level for each finding type.

          • LastGeneratedAt (datetime) --

            The timestamp at which a finding type for a specific severity was last generated.

          • Severity (float) --

            The severity level associated with each finding type.

          • TotalFindings (integer) --

            The total number of findings associated with this severity.

    • NextToken (string) --

      The pagination parameter to be used on the next list operation to retrieve more items.

      This parameter is currently not supported.