:doc:`GuardDuty <../../guardduty>` / Client / list_findings

*************
list_findings
*************



.. py:method:: GuardDuty.Client.list_findings(**kwargs)

  

  Lists GuardDuty findings for the specified detector ID.

   

  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 <https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_regions.html>`__.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/guardduty-2017-11-28/ListFindings>`_  


  **Request Syntax**
  ::

    response = client.list_findings(
        DetectorId='string',
        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,
                    'Matches': [
                        'string',
                    ],
                    'NotMatches': [
                        'string',
                    ]
                }
            }
        },
        SortCriteria={
            'AttributeName': 'string',
            'OrderBy': 'ASC'|'DESC'
        },
        MaxResults=123,
        NextToken='string'
    )
    
  :type DetectorId: string
  :param DetectorId: **[REQUIRED]** 

    The ID of the detector that specifies the GuardDuty service whose findings you want to list.

     

    To find the ``detectorId`` in the current Region, see the Settings page in the GuardDuty console, or run the `ListDetectors <https://docs.aws.amazon.com/guardduty/latest/APIReference/API_ListDetectors.html>`__ API.

    

  
  :type FindingCriteria: dict
  :param FindingCriteria: 

    Represents the criteria used for querying findings. Valid values include:

     

    
    * JSON field name
     
    * accountId
     
    * region
     
    * confidence
     
    * id
     
    * resource.accessKeyDetails.accessKeyId
     
    * resource.accessKeyDetails.principalId
     
    * resource.accessKeyDetails.userName
     
    * resource.accessKeyDetails.userType
     
    * resource.instanceDetails.iamInstanceProfile.id
     
    * resource.instanceDetails.imageId
     
    * resource.instanceDetails.instanceId
     
    * resource.instanceDetails.networkInterfaces.ipv6Addresses
     
    * resource.instanceDetails.networkInterfaces.privateIpAddresses.privateIpAddress
     
    * resource.instanceDetails.networkInterfaces.publicDnsName
     
    * resource.instanceDetails.networkInterfaces.publicIp
     
    * resource.instanceDetails.networkInterfaces.securityGroups.groupId
     
    * resource.instanceDetails.networkInterfaces.securityGroups.groupName
     
    * resource.instanceDetails.networkInterfaces.subnetId
     
    * resource.instanceDetails.networkInterfaces.vpcId
     
    * resource.instanceDetails.tags.key
     
    * resource.instanceDetails.tags.value
     
    * resource.resourceType
     
    * service.action.actionType
     
    * service.action.awsApiCallAction.api
     
    * service.action.awsApiCallAction.callerType
     
    * service.action.awsApiCallAction.remoteIpDetails.city.cityName
     
    * service.action.awsApiCallAction.remoteIpDetails.country.countryName
     
    * service.action.awsApiCallAction.remoteIpDetails.ipAddressV4
     
    * service.action.awsApiCallAction.remoteIpDetails.organization.asn
     
    * service.action.awsApiCallAction.remoteIpDetails.organization.asnOrg
     
    * service.action.awsApiCallAction.serviceName
     
    * service.action.dnsRequestAction.domain
     
    * service.action.dnsRequestAction.domainWithSuffix
     
    * service.action.networkConnectionAction.blocked
     
    * service.action.networkConnectionAction.connectionDirection
     
    * service.action.networkConnectionAction.localPortDetails.port
     
    * service.action.networkConnectionAction.protocol
     
    * service.action.networkConnectionAction.remoteIpDetails.country.countryName
     
    * service.action.networkConnectionAction.remoteIpDetails.ipAddressV4
     
    * service.action.networkConnectionAction.remoteIpDetails.organization.asn
     
    * service.action.networkConnectionAction.remoteIpDetails.organization.asnOrg
     
    * service.action.networkConnectionAction.remotePortDetails.port
     
    * service.additionalInfo.threatListName
     
    * service.archived When this attribute is set to 'true', only archived findings are listed. When it's set to 'false', only unarchived findings are listed. When this attribute is not set, all existing findings are listed.
     
    * service.ebsVolumeScanDetails.scanId
     
    * service.resourceRole
     
    * severity
     
    * type
     
    * updatedAt Type: Timestamp in Unix Epoch millisecond format: 1486685375000
    

    

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

            

          
          - **Matches** *(list) --* 

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

             

            .. note::

              

              The *matches* condition is available only for create-filter and update-filter APIs.

              

            

          
            - *(string) --* 

            
        
          - **NotMatches** *(list) --* 

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

             

            .. note::

              

              The *not-matches* condition is available only for create-filter and update-filter APIs.

              

            

          
            - *(string) --* 

            
        
        
  

  
  :type SortCriteria: dict
  :param SortCriteria: 

    Represents the criteria used for sorting findings.

    

  
    - **AttributeName** *(string) --* 

      Represents the finding attribute, such as ``accountId``, that sorts the findings.

      

    
    - **OrderBy** *(string) --* 

      The order by which the sorted findings are to be displayed.

      

    
  
  :type MaxResults: integer
  :param MaxResults: 

    You can use this parameter to indicate the maximum number of items you want in the response. The default value is 50. The maximum value is 50.

    

  
  :type NextToken: string
  :param NextToken: 

    You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the list action. For subsequent calls to the action, fill nextToken in the request with the value of NextToken from the previous response to continue listing data.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'FindingIds': [
              'string',
          ],
          'NextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **FindingIds** *(list) --* 

        The IDs of the findings that you're listing.

        
        

        - *(string) --* 
    
      

      - **NextToken** *(string) --* 

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

        
  
  **Exceptions**
  
  *   :py:class:`GuardDuty.Client.exceptions.BadRequestException`

  
  *   :py:class:`GuardDuty.Client.exceptions.InternalServerErrorException`

  