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
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
