GetInvestigation
This API is currently available as a preview. This feature is available in the following Amazon Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Canada (Central), Europe (Frankfurt), Europe (Ireland), Europe (London), Europe (Paris), Europe (Stockholm), and Asia Pacific (Tokyo).
Retrieves the results and status of a specific GuardDuty investigation.
GuardDuty returns the results, including the summary and the scope of the investigation,
only when the investigation status is COMPLETED. By default, GuardDuty returns the
summary as text in Summary. To return a typed summary in
SummaryData instead, set SummaryFormat to
STRUCTURED.
An administrator account can retrieve any investigation within the organization. Member accounts can only retrieve investigations that belong to them.
Request Syntax
GET /detector/DetectorId/investigation/InvestigationId?summaryFormat=SummaryFormat HTTP/1.1
URI Request Parameters
The request uses the following URI parameters.
- DetectorId
-
The unique ID of the GuardDuty detector associated with the investigation.
To find the
detectorIdin the current Region, see the Settings page in the GuardDuty console, or run the ListDetectors API.Length Constraints: Minimum length of 1. Maximum length of 300.
Required: Yes
- InvestigationId
-
The unique identifier of the investigation to retrieve.
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern:
[a-fA-F0-9\-]+Required: Yes
- SummaryFormat
-
The format in which to return the investigation summary. Possible values:
-
STRING– (Default) Returns the summary as text inSummary. -
STRUCTURED– Returns a typed summary inSummaryData.
GuardDuty returns a summary only when the investigation status is
COMPLETED.Valid Values:
STRING | STRUCTURED -
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
Content-type: application/json
{
"investigation": {
"cloud": {
"account": "string",
"provider": "string",
"region": "string"
},
"confidence": "string",
"endTime": number,
"error": "string",
"investigationId": "string",
"metadata": {
"product": {
"feature": "string",
"name": "string"
},
"version": "string"
},
"risk": "string",
"riskLevel": "string",
"scope": {
"accountId": "string",
"adminAccountId": "string",
"findingId": "string",
"investigationType": "string",
"queryTimeWindow": {
"endTime": number,
"startTime": number
}
},
"startTime": number,
"status": "string",
"summary": "string",
"summaryData": {
"accountAnalysis": {
"affectedResources": [
{
"findingCount": number,
"identifier": "string",
"type": "string"
}
],
"findingsSummary": {
"byTimeWindow": [
{
"endTime": number,
"findingCount": number,
"startTime": number
}
],
"severityBreakdown": {
"critical": number,
"high": number,
"info": number,
"low": number,
"medium": number
},
"topFindingTypes": [
{
"count": number,
"findingType": "string"
}
],
"totalFindings": number
},
"tacticCoverage": [
{
"findingCount": number,
"findingTypes": [ "string" ],
"phase": "string",
"techniques": [
{
"findingCount": number,
"findingTypes": [ "string" ],
"technique": {
"name": "string",
"uid": "string"
}
}
]
}
]
},
"countermeasures": [
{
"actions": [
{
"affectedResources": [
{
"arn": "string",
"identifier": "string",
"type": "string"
}
],
"cliCommands": [ "string" ],
"defenseTechnique": "string",
"description": "string",
"disposition": "string",
"dispositionId": number,
"mitigates": [ "string" ],
"priority": "string",
"title": "string"
}
],
"defenseTactic": "string",
"description": "string"
}
],
"findingType": "string",
"keyObservations": {
"narrative": "string",
"observations": [ "string" ],
"title": "string"
},
"organizationAnalysis": {
"accountBreakdown": [
{
"accountId": "string",
"findingCount": number
}
],
"findingsSummary": {
"affectedAccountCount": number,
"byTimeWindow": [
{
"endTime": number,
"findingCount": number,
"startTime": number
}
],
"severityBreakdown": {
"critical": number,
"high": number,
"info": number,
"low": number,
"medium": number
},
"topFindingTypes": [
{
"count": number,
"findingType": "string"
}
],
"totalAccountCount": number,
"totalFindings": number
}
},
"recommendations": [
{
"category": "string",
"cliCommands": [ "string" ],
"priority": "string",
"rationale": "string",
"title": "string"
}
],
"threatAssessment": {
"attackProgression": [
{
"attacks": [
{
"findings": [
{
"findingType": "string",
"uid": "string"
}
],
"tactic": {
"name": "string",
"uid": "string"
},
"technique": {
"name": "string",
"uid": "string"
},
"version": "string"
}
],
"description": "string",
"phase": "string"
}
],
"threatActorProfile": "string"
}
},
"triggeredBy": "string",
"triggerPrompt": "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.
- investigation
-
The details and results of the requested investigation.
Type: Investigation object
Errors
For information about the errors that are common to all actions, see Common Error Types.
- AccessDeniedException
-
An access denied exception object.
- Message
-
The error message.
- Type
-
The error type.
HTTP Status Code: 403
- BadRequestException
-
A bad request exception object.
- Message
-
The error message.
- Type
-
The error type.
HTTP Status Code: 400
- InternalServerErrorException
-
An internal server error exception object.
- Message
-
The error message.
- Type
-
The error type.
HTTP Status Code: 500
- ResourceNotFoundException
-
The requested resource can't be found.
- Message
-
The error message.
- Type
-
The error type.
HTTP Status Code: 404
See Also
For more information about using this API in one of the language-specific Amazon SDKs, see the following: