2023/11/27 - Amazon Detective - 5 new api methods
Changes Added new APIs in Detective to support resource investigations
List all Investigations.
See also: AWS API Documentation
Request Syntax
client.list_investigations(
GraphArn='string',
NextToken='string',
MaxResults=123,
FilterCriteria={
'Severity': {
'Value': 'string'
},
'Status': {
'Value': 'string'
},
'State': {
'Value': 'string'
},
'EntityArn': {
'Value': 'string'
},
'CreatedTime': {
'StartInclusive': datetime(2015, 1, 1),
'EndInclusive': datetime(2015, 1, 1)
}
},
SortCriteria={
'Field': 'SEVERITY'|'STATUS'|'CREATED_TIME',
'SortOrder': 'ASC'|'DESC'
}
)
string
[REQUIRED]
The ARN of the behavior graph.
string
List 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. Using an expired pagination token will return a Validation Exception error.
integer
List the maximum number of investigations in a page.
dict
Filter the investigation results based on a criteria.
Severity (dict) --
Filter the investigation results based on the severity.
Value (string) -- [REQUIRED]
The string filter value.
Status (dict) --
Filter the investigation results based on the status.
Value (string) -- [REQUIRED]
The string filter value.
State (dict) --
Filter the investigation results based on the state.
Value (string) -- [REQUIRED]
The string filter value.
EntityArn (dict) --
Filter the investigation results based on the Amazon Resource Name (ARN) of the entity.
Value (string) -- [REQUIRED]
The string filter value.
CreatedTime (dict) --
Filter the investigation results based on when the investigation was created.
StartInclusive (datetime) -- [REQUIRED]
A timestamp representing the start of the time period from when data is filtered, including the start date.
EndInclusive (datetime) -- [REQUIRED]
A timestamp representing the end date of the time period until when data is filtered , including the end date.
dict
Sorts the investigation results based on a criteria.
Field (string) --
Represents the Field attribute to sort investigations.
SortOrder (string) --
The order by which the sorted findings are displayed.
dict
Response Syntax
{
'InvestigationDetails': [
{
'InvestigationId': 'string',
'Severity': 'INFORMATIONAL'|'LOW'|'MEDIUM'|'HIGH'|'CRITICAL',
'Status': 'RUNNING'|'FAILED'|'SUCCESSFUL',
'State': 'ACTIVE'|'ARCHIVED',
'CreatedTime': datetime(2015, 1, 1),
'EntityArn': 'string',
'EntityType': 'IAM_ROLE'|'IAM_USER'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
InvestigationDetails (list) --
Investigations details lists the summary of uncommon behavior or malicious activity which indicates a compromise.
(dict) --
Details about the investigation related to a potential security event identified by Detective
InvestigationId (string) --
The investigation ID of the investigation report.
Severity (string) --
Severity based on the likelihood and impact of the indicators of compromise discovered in the investigation.
Status (string) --
Status based on the completion status of the investigation.
State (string) --
The current state of the investigation. An archived investigation indicates you have completed reviewing the investigation.
CreatedTime (datetime) --
The UTC time stamp of the creation time of the investigation report.
EntityArn (string) --
The unique Amazon Resource Name (ARN) of the IAM user and IAM role.
EntityType (string) --
Type of entity. For example, Amazon Web Services accounts, such as IAM user and role.
NextToken (string) --
List 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. Using an expired pagination token will return an HTTP 400 InvalidToken error.
Returns the investigation results of an investigation for a behavior graph.
See also: AWS API Documentation
Request Syntax
client.get_investigation(
GraphArn='string',
InvestigationId='string'
)
string
[REQUIRED]
The ARN of the behavior graph.
string
[REQUIRED]
The investigation ID of the investigation report.
dict
Response Syntax
{
'GraphArn': 'string',
'InvestigationId': 'string',
'EntityArn': 'string',
'EntityType': 'IAM_ROLE'|'IAM_USER',
'CreatedTime': datetime(2015, 1, 1),
'ScopeStartTime': datetime(2015, 1, 1),
'ScopeEndTime': datetime(2015, 1, 1),
'Status': 'RUNNING'|'FAILED'|'SUCCESSFUL',
'Severity': 'INFORMATIONAL'|'LOW'|'MEDIUM'|'HIGH'|'CRITICAL',
'State': 'ACTIVE'|'ARCHIVED'
}
Response Structure
(dict) --
GraphArn (string) --
The ARN of the behavior graph.
InvestigationId (string) --
The investigation ID of the investigation report.
EntityArn (string) --
The unique Amazon Resource Name (ARN) of the IAM user and IAM role.
EntityType (string) --
Type of entity. For example, Amazon Web Services accounts, such as IAM user and role.
CreatedTime (datetime) --
The UTC time stamp of the creation time of the investigation report.
ScopeStartTime (datetime) --
The start date and time for the scope time set to generate the investigation report.
ScopeEndTime (datetime) --
The data and time when the investigation began. The value is an UTC ISO8601 formatted string. For example, 2021-08-18T16:35:56.284Z.
Status (string) --
Status based on the completion status of the investigation.
Severity (string) --
Severity based on the likelihood and impact of the indicators of compromise discovered in the investigation.
State (string) --
The current state of the investigation. An archived investigation indicates you have completed reviewing the investigation.
initiate an investigation on an entity in a graph
See also: AWS API Documentation
Request Syntax
client.start_investigation(
GraphArn='string',
EntityArn='string',
ScopeStartTime=datetime(2015, 1, 1),
ScopeEndTime=datetime(2015, 1, 1)
)
string
[REQUIRED]
The ARN of the behavior graph.
string
[REQUIRED]
The unique Amazon Resource Name (ARN) of the IAM user and IAM role.
datetime
[REQUIRED]
The data and time when the investigation began. The value is an UTC ISO8601 formatted string. For example, 2021-08-18T16:35:56.284Z .
datetime
[REQUIRED]
The data and time when the investigation began. The value is an UTC ISO8601 formatted string. For example, 2021-08-18T16:35:56.284Z .
dict
Response Syntax
{
'InvestigationId': 'string'
}
Response Structure
(dict) --
InvestigationId (string) --
The investigation ID of the investigation report.
Update the state of an investigation.
See also: AWS API Documentation
Request Syntax
client.update_investigation_state(
GraphArn='string',
InvestigationId='string',
State='ACTIVE'|'ARCHIVED'
)
string
[REQUIRED]
The ARN of the behavior graph.
string
[REQUIRED]
The investigation ID of the investigation report.
string
[REQUIRED]
The current state of the investigation. An archived investigation indicates you have completed reviewing the investigation.
None
Get the indicators from an investigation
See also: AWS API Documentation
Request Syntax
client.list_indicators(
GraphArn='string',
InvestigationId='string',
IndicatorType='TTP_OBSERVED'|'IMPOSSIBLE_TRAVEL'|'FLAGGED_IP_ADDRESS'|'NEW_GEOLOCATION'|'NEW_ASO'|'NEW_USER_AGENT'|'RELATED_FINDING'|'RELATED_FINDING_GROUP',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The ARN of the behavior graph.
string
[REQUIRED]
The investigation ID of the investigation report.
string
string
List 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. Using an expired pagination token will return a Validation Exception error.
integer
List the maximum number of indicators in a page.
dict
Response Syntax
{
'GraphArn': 'string',
'InvestigationId': 'string',
'NextToken': 'string',
'Indicators': [
{
'IndicatorType': 'TTP_OBSERVED'|'IMPOSSIBLE_TRAVEL'|'FLAGGED_IP_ADDRESS'|'NEW_GEOLOCATION'|'NEW_ASO'|'NEW_USER_AGENT'|'RELATED_FINDING'|'RELATED_FINDING_GROUP',
'IndicatorDetail': {
'TTPsObservedDetail': {
'Tactic': 'string',
'Technique': 'string',
'Procedure': 'string',
'IpAddress': 'string',
'APIName': 'string',
'APISuccessCount': 123,
'APIFailureCount': 123
},
'ImpossibleTravelDetail': {
'StartingIpAddress': 'string',
'EndingIpAddress': 'string',
'StartingLocation': 'string',
'EndingLocation': 'string',
'HourlyTimeDelta': 123
},
'FlaggedIpAddressDetail': {
'IpAddress': 'string',
'Reason': 'AWS_THREAT_INTELLIGENCE'
},
'NewGeolocationDetail': {
'Location': 'string',
'IpAddress': 'string',
'IsNewForEntireAccount': True|False
},
'NewAsoDetail': {
'Aso': 'string',
'IsNewForEntireAccount': True|False
},
'NewUserAgentDetail': {
'UserAgent': 'string',
'IsNewForEntireAccount': True|False
},
'RelatedFindingDetail': {
'Arn': 'string',
'Type': 'string',
'IpAddress': 'string'
},
'RelatedFindingGroupDetail': {
'Id': 'string'
}
}
},
]
}
Response Structure
(dict) --
GraphArn (string) --
The ARN of the behavior graph.
InvestigationId (string) --
The investigation ID of the investigation report.
NextToken (string) --
List 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. Using an expired pagination token will return a Validation Exception error.
Indicators (list) --
Indicators of compromise listed based on severity.
(dict) --
Investigations triages indicators of compromises such as a finding and surfaces only the most critical and suspicious issues, so you can focus on high-level investigations.
IndicatorType (string) --
The type of indicator.
IndicatorDetail (dict) --
Details about the indicator of compromise.
TTPsObservedDetail (dict) --
Details about the indicator of compromise.
Tactic (string) --
The tactic used, identified by the investigation.
Technique (string) --
The technique used, identified by the investigation.
Procedure (string) --
The procedure used, identified by the investigation.
IpAddress (string) --
The IP address where the TTP was observed.
APIName (string) --
The name of the API where the TTP was observed.
APISuccessCount (integer) --
The total number of successful API requests.
APIFailureCount (integer) --
The total number of failed API requests.
ImpossibleTravelDetail (dict) --
Identifies unusual and impossible user activity for an account.
StartingIpAddress (string) --
IP address where the resource was first used in the impossible travel
EndingIpAddress (string) --
IP address where the resource was last used in the impossible travel.
StartingLocation (string) --
Location where the resource was first used in the impossible travel
EndingLocation (string) --
Location where the resource was last used in the impossible travel.
HourlyTimeDelta (integer) --
Returns the time difference between the first and last timestamp the resource was used.
FlaggedIpAddressDetail (dict) --
Suspicious IP addresses that are flagged, which indicates critical or severe threats based on threat intelligence by Detective. This indicator is derived from AWS threat intelligence.
IpAddress (string) --
IP address of the suspicious entity.
Reason (string) --
Details the reason the IP address was flagged as suspicious.
NewGeolocationDetail (dict) --
Contains details about the new geographic location.
Location (string) --
Location where the resource was accessed.
IpAddress (string) --
IP address using which the resource was accessed.
IsNewForEntireAccount (boolean) --
Checks if the gelocation is new for the entire account.
NewAsoDetail (dict) --
Contains details about the new Autonomous System Organization (ASO).
Aso (string) --
Details about the new Autonomous System Organization (ASO).
IsNewForEntireAccount (boolean) --
Checks if the ASO is for new for the entire account.
NewUserAgentDetail (dict) --
Contains details about the new user agent.
UserAgent (string) --
New user agent which accessed the resource.
IsNewForEntireAccount (boolean) --
Checks if the user agent is new for the entire account.
RelatedFindingDetail (dict) --
Contains details about related findings.
Arn (string) --
The ARN of the related finding.
Type (string) --
The type of finding.
IpAddress (string) --
The IP address of the finding.
RelatedFindingGroupDetail (dict) --
Contains details about related finding groups.
Id (string) --
The unique identifier for the finding group.