Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

StartInvestigation

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.

Request Syntax


POST /investigations/startInvestigation HTTP/1.1
Content-type: application/json

{
   "EntityArn": "string",
   "GraphArn": "string",
   "ScopeEndTime": "string",
   "ScopeStartTime": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

EntityArn

The unique Amazon Resource Name (ARN) of the IAM user and IAM role.

Type: String

Pattern: ^arn:.*

Required: Yes

GraphArn

The Amazon Resource Name (ARN) of the behavior graph.

Type: String

Pattern: ^arn:aws[-\w]{0,10}?:detective:[-\w]{2,20}?:\d{12}?:graph:[abcdef\d]{32}?$

Required: Yes

ScopeEndTime

The data and time when the investigation ended. The value is an UTC ISO8601 formatted string. For example, 2021-08-18T16:35:56.284Z.

Type: Timestamp

Required: Yes

ScopeStartTime

The data and time when the investigation began. The value is an UTC ISO8601 formatted string. For example, 2021-08-18T16:35:56.284Z.

Type: Timestamp

Required: Yes

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "InvestigationId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

InvestigationId

The investigation ID of the investigation report.

Type: String

Length Constraints: Fixed length of 21.

Pattern: ^[0-9]+$

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The request issuer does not have permission to access this resource or perform this operation.

HTTP Status Code: 403

InternalServerException

The request was valid but failed because of a problem with the service.

HTTP Status Code: 500

ResourceNotFoundException

The request refers to a nonexistent resource.

HTTP Status Code: 404

TooManyRequestsException

The request cannot be completed because too many other requests are occurring at the same time.

HTTP Status Code: 429

ValidationException

The request parameters are invalid.

HTTP Status Code: 400