ListInvestigationsCommand

Suggest an Edit

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. ListInvestigations lists all active Detective investigations.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { DetectiveClient, ListInvestigationsCommand } from "@aws-sdk/client-detective"; // ES Modules import
// const { DetectiveClient, ListInvestigationsCommand } = require("@aws-sdk/client-detective"); // CommonJS import
const client = new DetectiveClient(config);
const input = { // ListInvestigationsRequest
  GraphArn: "STRING_VALUE", // required
  NextToken: "STRING_VALUE",
  MaxResults: Number("int"),
  FilterCriteria: { // FilterCriteria
    Severity: { // StringFilter
      Value: "STRING_VALUE", // required
    },
    Status: {
      Value: "STRING_VALUE", // required
    },
    State: {
      Value: "STRING_VALUE", // required
    },
    EntityArn: {
      Value: "STRING_VALUE", // required
    },
    CreatedTime: { // DateFilter
      StartInclusive: new Date("TIMESTAMP"), // required
      EndInclusive: new Date("TIMESTAMP"), // required
    },
  },
  SortCriteria: { // SortCriteria
    Field: "SEVERITY" || "STATUS" || "CREATED_TIME",
    SortOrder: "ASC" || "DESC",
  },
};
const command = new ListInvestigationsCommand(input);
const response = await client.send(command);
// { // ListInvestigationsResponse
//   InvestigationDetails: [ // InvestigationDetails
//     { // InvestigationDetail
//       InvestigationId: "STRING_VALUE",
//       Severity: "INFORMATIONAL" || "LOW" || "MEDIUM" || "HIGH" || "CRITICAL",
//       Status: "RUNNING" || "FAILED" || "SUCCESSFUL",
//       State: "ACTIVE" || "ARCHIVED",
//       CreatedTime: new Date("TIMESTAMP"),
//       EntityArn: "STRING_VALUE",
//       EntityType: "IAM_ROLE" || "IAM_USER",
//     },
//   ],
//   NextToken: "STRING_VALUE",
// };

ListInvestigationsCommand Input

See ListInvestigationsCommandInput for more details

Parameter
Type
Description
GraphArn
Required
string | undefined

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

FilterCriteria
FilterCriteria | undefined

Filters the investigation results based on a criteria.

MaxResults
number | undefined

Lists the maximum number of investigations in a page.

NextToken
string | undefined

Lists 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.

SortCriteria
SortCriteria | undefined

Sorts the investigation results based on a criteria.

ListInvestigationsCommand Output

See ListInvestigationsCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
InvestigationDetails
InvestigationDetail[] | undefined

Lists the summary of uncommon behavior or malicious activity which indicates a compromise.

NextToken
string | undefined

Lists 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.

Throws

Name
Fault
Details
AccessDeniedException
client

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

InternalServerException
server

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

ResourceNotFoundException
client

The request refers to a nonexistent resource.

TooManyRequestsException
client

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

ValidationException
client

The request parameters are invalid.

DetectiveServiceException
Base exception class for all service exceptions from Detective service.