GuardDuty / Client / get_findings_statistics

get_findings_statistics#

GuardDuty.Client.get_findings_statistics(**kwargs)#

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.

Request Syntax

response = 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
)

Parameters:

DetectorId (string) –
[REQUIRED]

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

To find the detectorId in the current Region, see the Settings page in the GuardDuty console, or run the ListDetectors API.
FindingStatisticTypes (list) –
The types of finding statistics to retrieve.
- (string) –
FindingCriteria (dict) –
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.
GroupBy (string) – Displays the findings statistics grouped by one of the listed valid values.
OrderBy (string) –
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.
MaxResults (integer) –
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.

Return type:

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.

Exceptions

GuardDuty.Client.exceptions.BadRequestException
GuardDuty.Client.exceptions.InternalServerErrorException