graphs

Creates, updates, deletes, gets or lists a graphs resource.

Overview

Name	graphs
Type	Resource
Id	aws.detective.graphs

Fields

The following fields are returned by SELECT queries:

list_graphs

Name	Datatype	Description
graph_list	array	A list of behavior graphs that the account is an administrator account for.
next_token	string	If there are more behavior graphs remaining in the results, then this is the pagination token to use to request the next page of behavior graphs.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_graphs	select	region		Returns the list of behavior graphs that the calling account is an administrator account of. This operation can only be called by an administrator account. Because an account can currently only be the administrator of one behavior graph within a Region, the results always contain a single behavior graph.
create_graph	insert	region		Creates a new behavior graph for the calling account, and sets that account as the administrator account. This operation is called by the account that is enabling Detective. The operation also enables Detective for the calling account in the currently selected Region. It returns the ARN of the new behavior graph. CreateGraph triggers a process to create the corresponding data tables for the new behavior graph. An account can only be the administrator account for one behavior graph within a Region. If the same account calls CreateGraph with the same administrator account, it always returns the same behavior graph ARN. It does not create a new behavior graph.
disassociate_membership	update	region, GraphArn		Removes the member account from the specified behavior graph. This operation can only be called by an invited member account that has the ENABLED status. DisassociateMembership cannot be called by an organization account in the organization behavior graph. For the organization behavior graph, the Detective administrator account determines which organization accounts to enable or disable as member accounts.
delete_graph	delete	region		Disables the specified behavior graph and queues it to be deleted. This operation removes the behavior graph from each member account's list of behavior graphs. DeleteGraph can only be called by the administrator account for a behavior graph.
accept_invitation	exec	region, GraphArn		Accepts an invitation for the member account to contribute data to a behavior graph. This operation can only be called by an invited member account. The request provides the ARN of behavior graph. The member account status in the graph must be INVITED.
reject_invitation	exec	region, GraphArn		Rejects an invitation to contribute the account data to a behavior graph. This operation must be called by an invited member account that has the INVITED status. RejectInvitation cannot be called by an organization account in the organization behavior graph. In the organization behavior graph, organization accounts do not receive an invitation.
start_investigation	exec	region, GraphArn, EntityArn, ScopeStartTime, ScopeEndTime		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. StartInvestigation initiates an investigation on an entity in a behavior graph.
start_monitoring_member	exec	region, GraphArn, AccountId		Sends a request to enable data ingest for a member account that has a status of ACCEPTED_BUT_DISABLED. For valid member accounts, the status is updated as follows. If Detective enabled the member account, then the new status is ENABLED. If Detective cannot enable the member account, the status remains ACCEPTED_BUT_DISABLED.

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

list_graphs

Returns the list of behavior graphs that the calling account is an administrator account of. This operation can only be called by an administrator account. Because an account can currently only be the administrator of one behavior graph within a Region, the results always contain a single behavior graph.

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

INSERT examples

create_graph

Creates a new behavior graph for the calling account, and sets that account as the administrator account. This operation is called by the account that is enabling Detective. The operation also enables Detective for the calling account in the currently selected Region. It returns the ARN of the new behavior graph. CreateGraph triggers a process to create the corresponding data tables for the new behavior graph. An account can only be the administrator account for one behavior graph within a Region. If the same account calls CreateGraph with the same administrator account, it always returns the same behavior graph ARN. It does not create a new behavior graph.

INSERT INTO aws.detective.graphs (
Tags,
region
)
SELECT 
'{{ Tags }}',
'{{ region }}'
RETURNING
graph_arn
;

Manifest

# Description fields are for documentation purposes
- name: graphs
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the graphs resource.
  - name: Tags
    value: "{{ Tags }}"

UPDATE examples

disassociate_membership

Removes the member account from the specified behavior graph. This operation can only be called by an invited member account that has the ENABLED status. DisassociateMembership cannot be called by an organization account in the organization behavior graph. For the organization behavior graph, the Detective administrator account determines which organization accounts to enable or disable as member accounts.

UPDATE aws.detective.graphs
SET 
GraphArn = '{{ GraphArn }}'
WHERE 
region = '{{ region }}' --required
AND GraphArn = '{{ GraphArn }}' --required;

DELETE examples

delete_graph

Disables the specified behavior graph and queues it to be deleted. This operation removes the behavior graph from each member account's list of behavior graphs. DeleteGraph can only be called by the administrator account for a behavior graph.

DELETE FROM aws.detective.graphs
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

accept_invitation

Accepts an invitation for the member account to contribute data to a behavior graph. This operation can only be called by an invited member account. The request provides the ARN of behavior graph. The member account status in the graph must be INVITED.

EXEC aws.detective.graphs.accept_invitation 
@region='{{ region }}' --required 
@@json=
'{
"GraphArn": "{{ GraphArn }}"
}'
;

reject_invitation

Rejects an invitation to contribute the account data to a behavior graph. This operation must be called by an invited member account that has the INVITED status. RejectInvitation cannot be called by an organization account in the organization behavior graph. In the organization behavior graph, organization accounts do not receive an invitation.

EXEC aws.detective.graphs.reject_invitation 
@region='{{ region }}' --required 
@@json=
'{
"GraphArn": "{{ GraphArn }}"
}'
;

start_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. StartInvestigation initiates an investigation on an entity in a behavior graph.

EXEC aws.detective.graphs.start_investigation 
@region='{{ region }}' --required 
@@json=
'{
"GraphArn": "{{ GraphArn }}", 
"EntityArn": "{{ EntityArn }}", 
"ScopeStartTime": "{{ ScopeStartTime }}", 
"ScopeEndTime": "{{ ScopeEndTime }}"
}'
;

start_monitoring_member

Sends a request to enable data ingest for a member account that has a status of ACCEPTED_BUT_DISABLED. For valid member accounts, the status is updated as follows. If Detective enabled the member account, then the new status is ENABLED. If Detective cannot enable the member account, the status remains ACCEPTED_BUT_DISABLED.

EXEC aws.detective.graphs.start_monitoring_member 
@region='{{ region }}' --required 
@@json=
'{
"GraphArn": "{{ GraphArn }}", 
"AccountId": "{{ AccountId }}"
}'
;