Anthropic-Cybersecurity-Skills/skills/performing-cloud-native-threat-hunting-with-aws-detective/references/api-reference.md

AWS Detective API Reference

This reference covers the Amazon Detective API for cloud-native threat hunting, via the AWS SDK for Python (boto3) and the AWS CLI. Detective ingests CloudTrail, VPC Flow Logs, GuardDuty findings, and EKS audit logs into a behavior graph and exposes entity profiles, finding groups, and guided investigations.

Authentication

Detective uses standard AWS IAM authentication — no separate API key. Credentials resolve through the SDK credential provider chain (environment variables, ~/.aws/credentials profile, EC2/ECS/EKS/Lambda role, or SSO).

import boto3

detective = boto3.client("detective", region_name="us-east-1")

Required IAM permissions (managed policy AmazonDetectiveFullAccess, or least-privilege custom):

Action	Purpose
detective:ListGraphs	Discover behavior graphs
detective:ListInvestigations	List guided investigations
detective:GetInvestigation	Get an investigation's results
detective:ListIndicators	List indicators for an investigation
detective:StartInvestigation	Launch a new investigation on an entity
detective:ListMembers / detective:GetMembers	Multi-account graph membership
guardduty:ListFindings, guardduty:GetFindings	Correlate GuardDuty findings

Prerequisite: Amazon GuardDuty must be enabled and active for at least 48 hours before Detective can build a usable behavior graph.

Key Methods (boto3 detective client)

Method	Description	Key Parameters
list_graphs	List behavior graphs the account administers.	MaxResults, NextToken
start_investigation	Run an automated investigation on an entity over a scope window.	GraphArn (required), EntityArn (required), ScopeStartTime, ScopeEndTime
get_investigation	Retrieve an investigation's results (severity, status, scope, entity).	GraphArn (required), InvestigationId (required)
list_investigations	List investigations, filterable/sortable.	GraphArn (required), FilterCriteria, SortCriteria, MaxResults, NextToken
list_indicators	List indicators (TTPs, anomalies) tied to an investigation.	GraphArn (required), InvestigationId (required), IndicatorType, MaxResults, NextToken
list_members / get_members	Member accounts in the behavior graph.	GraphArn, AccountIds
create_members / delete_members	Invite/remove member accounts.	GraphArn, Accounts
list_datasource_packages	Optional data sources enabled (EKS audit, etc.).	GraphArn
update_investigation_state	Mark an investigation ARCHIVED / ACTIVE.	GraphArn, InvestigationId, State

list_indicators — verified parameters

GraphArn (string, required), InvestigationId (string, required), IndicatorType (string, optional filter), NextToken (string — pagination token; expires after 24 hours), MaxResults (integer). Valid IndicatorType values:

TTP_OBSERVED · IMPOSSIBLE_TRAVEL · FLAGGED_IP_ADDRESS · NEW_GEOLOCATION · NEW_ASO (new autonomous system org) · NEW_USER_AGENT · RELATED_FINDING · RELATED_FINDING_GROUP

get_investigation — verified

Request: GraphArn (the behavior graph ARN), InvestigationId. Response includes CreatedTime (UTC ISO8601, e.g. 2021-08-18T16:35:56.284Z), EntityArn, EntityType, GraphArn, InvestigationId, ScopeStartTime, ScopeEndTime, plus severity/status/state.

list_investigations filter / sort detail

FilterCriteria = {
    "Severity":     {"Value": "CRITICAL"},   # INFORMATIONAL|LOW|MEDIUM|HIGH|CRITICAL
    "Status":       {"Value": "RUNNING"},     # RUNNING|FAILED|SUCCESSFUL
    "State":        {"Value": "ACTIVE"},      # ACTIVE|ARCHIVED
    "EntityArn":    {"Value": "arn:aws:iam::123456789012:user/suspicious"},
    "CreatedTime":  {"StartInclusive": <datetime>, "EndInclusive": <datetime>},
}
SortCriteria = {"Field": "SEVERITY", "SortOrder": "DESC"}  # CREATED_TIME|SEVERITY|STATUS

Python SDK

# Installation
pip install boto3

import boto3

detective = boto3.client("detective", region_name="us-east-1")

def hunt_critical(graph_arn):
    """List critical, currently-running investigations and their indicators."""
    inv = detective.list_investigations(
        GraphArn=graph_arn,
        FilterCriteria={
            "Severity": {"Value": "CRITICAL"},
            "Status":   {"Value": "RUNNING"},
        },
        SortCriteria={"Field": "SEVERITY", "SortOrder": "DESC"},
        MaxResults=20,
    )
    for d in inv.get("InvestigationDetails", []):
        print(d["InvestigationId"], d["EntityArn"], d["Severity"])
        ind = detective.list_indicators(
            GraphArn=graph_arn,
            InvestigationId=d["InvestigationId"],
            MaxResults=50,
        )
        for i in ind.get("Indicators", []):
            print("  ", i["IndicatorType"], i.get("IndicatorDetail"))

# Launch a fresh investigation on a suspect IAM principal
def investigate_entity(graph_arn, entity_arn, start, end):
    resp = detective.start_investigation(
        GraphArn=graph_arn,
        EntityArn=entity_arn,
        ScopeStartTime=start,   # datetime
        ScopeEndTime=end,       # datetime
    )
    return resp["InvestigationId"]

for g in detective.list_graphs().get("GraphList", []):
    hunt_critical(g["Arn"])

CLI equivalents:

aws detective list-graphs --output table

aws detective list-investigations \
  --graph-arn arn:aws:detective:us-east-1:123456789012:graph:abc \
  --filter-criteria '{"Severity":{"Value":"HIGH"}}' \
  --max-results 10

aws detective list-indicators \
  --graph-arn arn:aws:detective:us-east-1:123456789012:graph:abc \
  --investigation-id 000000000000000000001 --max-results 50

Common Response Fields

list_investigations → InvestigationDetails[]:

Field	Meaning
InvestigationId	Unique investigation ID
Severity	INFORMATIONAL | LOW | MEDIUM | HIGH | CRITICAL
Status	RUNNING | FAILED | SUCCESSFUL
State	ACTIVE | ARCHIVED
EntityArn	The entity under investigation
EntityType	IAM_USER | IAM_ROLE (etc.)
CreatedTime	Investigation creation timestamp (UTC ISO8601)

list_indicators → Indicators[]: each has IndicatorType plus an IndicatorDetail union populated for the matching type (e.g. FlaggedIpAddressDetail, ImpossibleTravelDetail, NewGeolocationDetail, TTPsObservedDetail carrying MITRE ATT&CK tactic/technique).

Rate Limits / Service Quotas

Detective enforces account-level, per-Region quotas (most adjustable via Service Quotas):

Quota	Default
Member accounts per behavior graph	1,200
Behavior graphs (administrator) per Region	1
Data retention in behavior graph	1 year of rolling history
Investigation scope window	up to 1 year
Pagination token (list_indicators NextToken) lifetime	24 hours
API request rate	Throttled per standard AWS API limits

Throttling returns TooManyRequestsException; boto3 retries with exponential backoff. There is no per-request monetary charge for the API itself — Detective is billed by volume of log data ingested into the behavior graph (GB/month, tiered).

Error Codes

Error	Meaning
AccessDeniedException	Caller lacks the required detective:* permission
ValidationException	Invalid parameter (bad ARN, malformed filter)
ResourceNotFoundException	Graph, investigation, or entity not found
TooManyRequestsException	API rate quota exceeded; back off and retry
ConflictException	Concurrent modification of graph membership
InternalServerException	Transient service-side error; retry
ServiceQuotaExceededException	Member/graph quota exceeded

Resources

• Detective API Reference: https://docs.aws.amazon.com/detective/latest/APIReference/Welcome.html
• ListInvestigations: https://docs.aws.amazon.com/detective/latest/APIReference/API_ListInvestigations.html
• GetInvestigation: https://docs.aws.amazon.com/detective/latest/APIReference/API_GetInvestigation.html
• StartInvestigation: https://docs.aws.amazon.com/detective/latest/APIReference/API_StartInvestigation.html
• boto3 list_indicators: https://docs.aws.amazon.com/boto3/latest/reference/services/detective/client/list_indicators.html
• boto3 Detective client: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/detective.html
• Detective + GuardDuty integration: https://docs.aws.amazon.com/detective/latest/userguide/detective-integration-guardduty.html