:doc:`Inspector <../../inspector>` / Client / describe_findings

*****************
describe_findings
*****************



.. py:method:: Inspector.Client.describe_findings(**kwargs)

  

  Describes the findings that are specified by the ARNs of the findings.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/inspector-2016-02-16/DescribeFindings>`_  


  **Request Syntax**
  ::

    response = client.describe_findings(
        findingArns=[
            'string',
        ],
        locale='EN_US'
    )
    
  :type findingArns: list
  :param findingArns: **[REQUIRED]** 

    The ARN that specifies the finding that you want to describe.

    

  
    - *(string) --* 

    

  :type locale: string
  :param locale: 

    The locale into which you want to translate a finding description, recommendation, and the short description that identifies the finding.

    

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

    
    ::

      {
          'findings': [
              {
                  'arn': 'string',
                  'schemaVersion': 123,
                  'service': 'string',
                  'serviceAttributes': {
                      'schemaVersion': 123,
                      'assessmentRunArn': 'string',
                      'rulesPackageArn': 'string'
                  },
                  'assetType': 'ec2-instance',
                  'assetAttributes': {
                      'schemaVersion': 123,
                      'agentId': 'string',
                      'autoScalingGroup': 'string',
                      'amiId': 'string',
                      'hostname': 'string',
                      'ipv4Addresses': [
                          'string',
                      ],
                      'tags': [
                          {
                              'key': 'string',
                              'value': 'string'
                          },
                      ],
                      'networkInterfaces': [
                          {
                              'networkInterfaceId': 'string',
                              'subnetId': 'string',
                              'vpcId': 'string',
                              'privateDnsName': 'string',
                              'privateIpAddress': 'string',
                              'privateIpAddresses': [
                                  {
                                      'privateDnsName': 'string',
                                      'privateIpAddress': 'string'
                                  },
                              ],
                              'publicDnsName': 'string',
                              'publicIp': 'string',
                              'ipv6Addresses': [
                                  'string',
                              ],
                              'securityGroups': [
                                  {
                                      'groupName': 'string',
                                      'groupId': 'string'
                                  },
                              ]
                          },
                      ]
                  },
                  'id': 'string',
                  'title': 'string',
                  'description': 'string',
                  'recommendation': 'string',
                  'severity': 'Low'|'Medium'|'High'|'Informational'|'Undefined',
                  'numericSeverity': 123.0,
                  'confidence': 123,
                  'indicatorOfCompromise': True|False,
                  'attributes': [
                      {
                          'key': 'string',
                          'value': 'string'
                      },
                  ],
                  'userAttributes': [
                      {
                          'key': 'string',
                          'value': 'string'
                      },
                  ],
                  'createdAt': datetime(2015, 1, 1),
                  'updatedAt': datetime(2015, 1, 1)
              },
          ],
          'failedItems': {
              'string': {
                  'failureCode': 'INVALID_ARN'|'DUPLICATE_ARN'|'ITEM_DOES_NOT_EXIST'|'ACCESS_DENIED'|'LIMIT_EXCEEDED'|'INTERNAL_ERROR',
                  'retryable': True|False
              }
          }
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **findings** *(list) --* 

        Information about the finding.

        
        

        - *(dict) --* 

          Contains information about an Amazon Inspector finding. This data type is used as the response element in the  DescribeFindings action.

          
          

          - **arn** *(string) --* 

            The ARN that specifies the finding.

            
          

          - **schemaVersion** *(integer) --* 

            The schema version of this data type.

            
          

          - **service** *(string) --* 

            The data element is set to "Inspector".

            
          

          - **serviceAttributes** *(dict) --* 

            This data type is used in the  Finding data type.

            
            

            - **schemaVersion** *(integer) --* 

              The schema version of this data type.

              
            

            - **assessmentRunArn** *(string) --* 

              The ARN of the assessment run during which the finding is generated.

              
            

            - **rulesPackageArn** *(string) --* 

              The ARN of the rules package that is used to generate the finding.

              
        
          

          - **assetType** *(string) --* 

            The type of the host from which the finding is generated.

            
          

          - **assetAttributes** *(dict) --* 

            A collection of attributes of the host from which the finding is generated.

            
            

            - **schemaVersion** *(integer) --* 

              The schema version of this data type.

              
            

            - **agentId** *(string) --* 

              The ID of the agent that is installed on the EC2 instance where the finding is generated.

              
            

            - **autoScalingGroup** *(string) --* 

              The Auto Scaling group of the EC2 instance where the finding is generated.

              
            

            - **amiId** *(string) --* 

              The ID of the Amazon Machine Image (AMI) that is installed on the EC2 instance where the finding is generated.

              
            

            - **hostname** *(string) --* 

              The hostname of the EC2 instance where the finding is generated.

              
            

            - **ipv4Addresses** *(list) --* 

              The list of IP v4 addresses of the EC2 instance where the finding is generated.

              
              

              - *(string) --* 
          
            

            - **tags** *(list) --* 

              The tags related to the EC2 instance where the finding is generated.

              
              

              - *(dict) --* 

                A key and value pair. This data type is used as a request parameter in the  SetTagsForResource action and a response element in the  ListTagsForResource action.

                
                

                - **key** *(string) --* 

                  A tag key.

                  
                

                - **value** *(string) --* 

                  A value assigned to a tag key.

                  
            
          
            

            - **networkInterfaces** *(list) --* 

              An array of the network interfaces interacting with the EC2 instance where the finding is generated.

              
              

              - *(dict) --* 

                Contains information about the network interfaces interacting with an EC2 instance. This data type is used as one of the elements of the  AssetAttributes data type.

                
                

                - **networkInterfaceId** *(string) --* 

                  The ID of the network interface.

                  
                

                - **subnetId** *(string) --* 

                  The ID of a subnet associated with the network interface.

                  
                

                - **vpcId** *(string) --* 

                  The ID of a VPC associated with the network interface.

                  
                

                - **privateDnsName** *(string) --* 

                  The name of a private DNS associated with the network interface.

                  
                

                - **privateIpAddress** *(string) --* 

                  The private IP address associated with the network interface.

                  
                

                - **privateIpAddresses** *(list) --* 

                  A list of the private IP addresses associated with the network interface. Includes the privateDnsName and privateIpAddress.

                  
                  

                  - *(dict) --* 

                    Contains information about a private IP address associated with a network interface. This data type is used as a response element in the  DescribeFindings action.

                    
                    

                    - **privateDnsName** *(string) --* 

                      The DNS name of the private IP address.

                      
                    

                    - **privateIpAddress** *(string) --* 

                      The full IP address of the network inteface.

                      
                
              
                

                - **publicDnsName** *(string) --* 

                  The name of a public DNS associated with the network interface.

                  
                

                - **publicIp** *(string) --* 

                  The public IP address from which the network interface is reachable.

                  
                

                - **ipv6Addresses** *(list) --* 

                  The IP addresses associated with the network interface.

                  
                  

                  - *(string) --* 
              
                

                - **securityGroups** *(list) --* 

                  A list of the security groups associated with the network interface. Includes the groupId and groupName.

                  
                  

                  - *(dict) --* 

                    Contains information about a security group associated with a network interface. This data type is used as one of the elements of the  NetworkInterface data type.

                    
                    

                    - **groupName** *(string) --* 

                      The name of the security group.

                      
                    

                    - **groupId** *(string) --* 

                      The ID of the security group.

                      
                
              
            
          
        
          

          - **id** *(string) --* 

            The ID of the finding.

            
          

          - **title** *(string) --* 

            The name of the finding.

            
          

          - **description** *(string) --* 

            The description of the finding.

            
          

          - **recommendation** *(string) --* 

            The recommendation for the finding.

            
          

          - **severity** *(string) --* 

            The finding severity. Values can be set to High, Medium, Low, and Informational.

            
          

          - **numericSeverity** *(float) --* 

            The numeric value of the finding severity.

            
          

          - **confidence** *(integer) --* 

            This data element is currently not used.

            
          

          - **indicatorOfCompromise** *(boolean) --* 

            This data element is currently not used.

            
          

          - **attributes** *(list) --* 

            The system-defined attributes for the finding.

            
            

            - *(dict) --* 

              This data type is used as a request parameter in the  AddAttributesToFindings and  CreateAssessmentTemplate actions.

              
              

              - **key** *(string) --* 

                The attribute key.

                
              

              - **value** *(string) --* 

                The value assigned to the attribute key.

                
          
        
          

          - **userAttributes** *(list) --* 

            The user-defined attributes that are assigned to the finding.

            
            

            - *(dict) --* 

              This data type is used as a request parameter in the  AddAttributesToFindings and  CreateAssessmentTemplate actions.

              
              

              - **key** *(string) --* 

                The attribute key.

                
              

              - **value** *(string) --* 

                The value assigned to the attribute key.

                
          
        
          

          - **createdAt** *(datetime) --* 

            The time when the finding was generated.

            
          

          - **updatedAt** *(datetime) --* 

            The time when  AddAttributesToFindings is called.

            
      
    
      

      - **failedItems** *(dict) --* 

        Finding details that cannot be described. An error code is provided for each failed item.

        
        

        - *(string) --* 
          

          - *(dict) --* 

            Includes details about the failed items.

            
            

            - **failureCode** *(string) --* 

              The status code of a failed item.

              
            

            - **retryable** *(boolean) --* 

              Indicates whether you can immediately retry a request for this item for a specified resource.

              
        
    
  
  
  **Exceptions**
  
  *   :py:class:`Inspector.Client.exceptions.InternalException`

  
  *   :py:class:`Inspector.Client.exceptions.InvalidInputException`

  

  **Examples**

  Describes the findings that are specified by the ARNs of the findings.
  ::

    response = client.describe_findings(
        findingArns=[
            'arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq/template/0-4r1V2mAw/run/0-MKkpXXPE/finding/0-HwPnsDm4',
        ],
    )
    
    print(response)

  
  Expected Output:
  ::

    {
        'failedItems': {
        },
        'findings': [
            {
                'arn': 'arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq/template/0-4r1V2mAw/run/0-MKkpXXPE/finding/0-HwPnsDm4',
                'assetAttributes': {
                    'ipv4Addresses': [
                    ],
                    'schemaVersion': 1,
                },
                'assetType': 'ec2-instance',
                'attributes': [
                ],
                'confidence': 10,
                'createdAt': datetime(2016, 3, 22, 20, 58, 21, 1, 82, 0),
                'description': 'Amazon Inspector did not find any potential security issues during this assessment.',
                'indicatorOfCompromise': False,
                'numericSeverity': 0,
                'recommendation': 'No remediation needed.',
                'schemaVersion': 1,
                'service': 'Inspector',
                'serviceAttributes': {
                    'assessmentRunArn': 'arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq/template/0-4r1V2mAw/run/0-MKkpXXPE',
                    'rulesPackageArn': 'arn:aws:inspector:us-west-2:758058086616:rulespackage/0-X1KXtawP',
                    'schemaVersion': 1,
                },
                'severity': 'Informational',
                'title': 'No potential security issues found',
                'updatedAt': datetime(2016, 3, 22, 20, 58, 21, 1, 82, 0),
                'userAttributes': [
                ],
            },
        ],
        'ResponseMetadata': {
            '...': '...',
        },
    }

  