investigations

Creates, updates, deletes, gets or lists an investigations resource.

Overview

Name	investigations
Type	Resource
Id	aws.detective.investigations

Fields

The following fields are returned by SELECT queries:

get_investigation

Name	Datatype	Description
created_time	string (date-time)	The creation time of the investigation report in UTC time stamp format.
entity_arn	string	The unique Amazon Resource Name (ARN). Detective supports IAM user ARNs and IAM role ARNs. (pattern: <code>^arn:.*</code>)
entity_type	string	Type of entity. For example, Amazon Web Services accounts, such as an IAM user and/or IAM role. (IAM_ROLE, IAM_USER)
graph_arn	string	The Amazon Resource Name (ARN) of the behavior graph. (pattern: <code>^arn:aws[-\w]{0,10}?:detective:[-\w]{2,20}?:\d{12}?:graph:[abcdef\d]{32}?$</code>)
investigation_id	string	The investigation ID of the investigation report. (pattern: <code>^[0-9]+$</code>)
scope_end_time	string (date-time)	The data and time when the investigation began. The value is an UTC ISO8601 formatted string. For example, 2021-08-18T16:35:56.284Z.
scope_start_time	string (date-time)	The start date and time used to set the scope time within which you want to generate the investigation report. The value is an UTC ISO8601 formatted string. For example, 2021-08-18T16:35:56.284Z.
severity	string	The severity assigned is based on the likelihood and impact of the indicators of compromise discovered in the investigation. (INFORMATIONAL, LOW, MEDIUM, HIGH, CRITICAL)
state	string	The current state of the investigation. An archived investigation indicates that you have completed reviewing the investigation. (ACTIVE, ARCHIVED)
status	string	The status based on the completion status of the investigation. (RUNNING, FAILED, SUCCESSFUL)

list_investigations

Name	Datatype	Description
investigation_details	array	Lists the summary of uncommon behavior or malicious activity which indicates a compromise.
next_token	string	Lists if there are more results available. The value of nextToken is a unique pagination token for each page. Repeat the call using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_investigation	select	region		Detective investigations lets you investigate IAM users and IAM roles using indicators of compromise. An indicator of compromise (IOC) is an artifact observed in or on a network, system, or environment that can (with a high level of confidence) identify malicious activity or a security incident. GetInvestigation returns the investigation results of an investigation for a behavior graph.
list_investigations	select	region		Detective investigations lets you investigate IAM users and IAM roles using indicators of compromise. An indicator of compromise (IOC) is an artifact observed in or on a network, system, or environment that can (with a high level of confidence) identify malicious activity or a security incident. ListInvestigations lists all active Detective investigations.
update_investigation_state	update	region, GraphArn, InvestigationId		Updates the state of an investigation.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

get_investigation

Detective investigations lets you investigate IAM users and IAM roles using indicators of compromise. An indicator of compromise (IOC) is an artifact observed in or on a network, system, or environment that can (with a high level of confidence) identify malicious activity or a security incident. GetInvestigation returns the investigation results of an investigation for a behavior graph.

SELECT
created_time,
entity_arn,
entity_type,
graph_arn,
investigation_id,
scope_end_time,
scope_start_time,
severity,
state,
status
FROM aws.detective.investigations
WHERE region = '{{ region }}' -- required
;

list_investigations

Detective investigations lets you investigate IAM users and IAM roles using indicators of compromise. An indicator of compromise (IOC) is an artifact observed in or on a network, system, or environment that can (with a high level of confidence) identify malicious activity or a security incident. ListInvestigations lists all active Detective investigations.

SELECT
investigation_details,
next_token
FROM aws.detective.investigations
WHERE region = '{{ region }}' -- required
;

UPDATE examples

update_investigation_state

Updates the state of an investigation.

UPDATE aws.detective.investigations
SET 
GraphArn = '{{ GraphArn }}',
InvestigationId = '{{ InvestigationId }}',
State = '{{ State }}'
WHERE 
region = '{{ region }}' --required
AND GraphArn = '{{ GraphArn }}' --required
AND InvestigationId = '{{ InvestigationId }}' --required;