GuardDuty / Client / get_investigation

get_investigation¶

GuardDuty.Client.get_investigation(**kwargs)¶

This API is currently available as a preview. This feature is available in the following Amazon Web Services Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Canada (Central), Europe (Frankfurt), Europe (Ireland), Europe (London), Europe (Paris), Europe (Stockholm), and Asia Pacific (Tokyo).

Retrieves the results and status of a specific GuardDuty investigation.

An administrator account can retrieve any investigation within the organization. Member accounts can only retrieve investigations that belong to them.

Request Syntax

response = client.get_investigation(
    DetectorId='string',
    InvestigationId='string'
)

Parameters:

DetectorId (string) –
[REQUIRED]

The unique ID of the GuardDuty detector associated with the investigation.

To find the detectorId in the current Region, see the Settings page in the GuardDuty console, or run the ListDetectors API.
InvestigationId (string) –
[REQUIRED]

The unique identifier of the investigation to retrieve.

Return type:

dict

Returns:

Response Syntax

{
    'Investigation': {
        'InvestigationId': 'string',
        'Status': 'RUNNING'|'COMPLETED'|'FAILED',
        'TriggerPrompt': 'string',
        'TriggeredBy': 'string',
        'Metadata': {
            'Version': 'string',
            'Product': {
                'Name': 'string',
                'Feature': 'string'
            }
        },
        'Cloud': {
            'Provider': 'AWS',
            'Region': 'string',
            'Account': 'string'
        },
        'RiskLevel': 'Info'|'Low'|'Medium'|'High'|'Critical',
        'Risk': 'string',
        'Confidence': 'Unknown'|'Low'|'Medium'|'High',
        'Summary': 'string',
        'StartTime': datetime(2015, 1, 1),
        'EndTime': datetime(2015, 1, 1),
        'Error': 'string'
    }
}

Response Structure

(dict) –
- Investigation (dict) –
  
  The details and results of the requested investigation.
  - InvestigationId (string) –
    
    The unique identifier of the investigation.
  - Status (string) –
    
    The current status of the investigation. Possible values are RUNNING, COMPLETED, and FAILED.
  - TriggerPrompt (string) –
    
    The natural-language prompt that initiated this investigation.
  - TriggeredBy (string) –
    
    The account that initiated the investigation.
  - Metadata (dict) –
    
    Metadata about the product and version that produced the investigation.
    - Version (string) –
      
      The version of the investigation engine that produced the results.
    - Product (dict) –
      
      Information about the product that produced the investigation.
      - Name (string) –
        
        The name of the product.
      - Feature (string) –
        
        The specific feature within the product that produced the investigation.
  - Cloud (dict) –
    
    Details about the cloud environment in which the investigation was performed, including the provider, region, and account.
    - Provider (string) –
      
      The cloud provider. Currently, only AWS is supported.
    - Region (string) –
      
      The Amazon Web Services Region in which the investigated resource resides.
    - Account (string) –
      
      The Amazon Web Services account ID of the investigated resource.
  - RiskLevel (string) –
    
    The assessed risk level of the investigated threat. Possible values are Info, Low, Medium, High, and Critical.
  - Risk (string) –
    
    A human-readable description of the assessed risk.
  - Confidence (string) –
    
    The confidence level of the investigation’s assessment. Possible values are Unknown, Low, Medium, and High.
  - Summary (string) –
    
    A structured summary of the investigation findings, including affected resources, threat assessment, and recommended remediation steps.
  - StartTime (datetime) –
    
    The timestamp at which the investigation started.
  - EndTime (datetime) –
    
    The timestamp at which the investigation completed.
  - Error (string) –
    
    Details about the error if the investigation status is FAILED.

Exceptions

GuardDuty.Client.exceptions.BadRequestException
GuardDuty.Client.exceptions.InternalServerErrorException
GuardDuty.Client.exceptions.AccessDeniedException
GuardDuty.Client.exceptions.ResourceNotFoundException