What it does. Investigate AWS security incidents using Amazon Detective's behavior graphs, Part of mukul975/Anthropic-Cybersecurity-Skills (817 security skills) (mukul975/Anthropic-Cybersecurity-Skills).

Upstream	mukul975/Anthropic-Cybersecurity-Skills
Skill file	skills/performing-cloud-native-threat-hunting-with-aws-detective/SKILL.md
License	Apache-2.0
Author	mukul975
Fetched	2026-09-10

Install

• npx skills add mukul975/Anthropic-Cybersecurity-Skills --skill performing-cloud-native-threat-hunting-with-aws-detective, or copy the skill folder into ~/.claude/skills/performing-cloud-native-threat-hunting-with-aws-detective/.
• Raw file: curl -sL https://raw.githubusercontent.com/mukul975/Anthropic-Cybersecurity-Skills/HEAD/skills/performing-cloud-native-threat-hunting-with-aws-detective/SKILL.md

SKILL.md (verbatim)

name: performing-cloud-native-threat-hunting-with-aws-detective
description: Investigate AWS security incidents using Amazon Detective's behavior graphs,
  built from CloudTrail, VPC Flow Logs, GuardDuty, and EKS audit logs, to trace entity
  timelines and profile IAM users, roles, EC2 instances, and IP addresses for lateral
  movement. Use when triaging GuardDuty findings, investigating a suspected AWS compromise,
  or reconstructing an attacker's activity timeline across AWS accounts.
domain: cybersecurity
subdomain: cloud-security
tags:
- aws-detective
- threat-hunting
- cloud-security
- guardduty
- behavior-graph
- aws
- iam
- ec2
- incident-investigation
version: '1.0'
author: juliosuas
license: Apache-2.0
nist_csf:
- PR.IR-01
- ID.AM-08
- GV.SC-06
- DE.CM-01
mitre_attack:
- T1078.004
- T1530
- T1537
- T1580
- T1071

Performing Cloud-Native Threat Hunting with AWS Detective

Overview

AWS Detective automatically collects and analyzes log data from AWS CloudTrail, VPC Flow Logs, GuardDuty findings, and EKS audit logs to build interactive behavior graphs. These graphs enable security analysts to investigate entities (IAM users, roles, IP addresses, EC2 instances) across time, identify anomalous API calls, detect lateral movement between accounts, and correlate GuardDuty findings into coherent attack narratives — all without manual log parsing.

Prerequisites

• AWS account with Detective enabled (requires GuardDuty active for 48+ hours)
• AWS CLI v2 configured with appropriate IAM permissions (detective:*, guardduty:List*)
• Python 3.9+ with boto3
• IAM policy: AmazonDetectiveFullAccess or custom policy with detective:SearchGraph, detective:GetInvestigation, detective:ListIndicators

Key Concepts

Concept	Description
Behavior Graph	Data structure linking CloudTrail, VPC Flow, GuardDuty, and EKS logs for an account/region
Entity	Investigable object: IAM user, IAM role, EC2 instance, IP address, S3 bucket, EKS cluster
Finding Group	Correlated set of GuardDuty findings linked to the same attack campaign
Entity Profile	Timeline of API calls, network connections, and resource access for a specific entity
Scope Time	Investigation window (default 24h, max 1 year) for behavioral analysis

Steps

Step 1: List Available Behavior Graphs

aws detective list-graphs --output table

Step 2: Investigate a Suspicious IAM User

# Get entity profile for an IAM user
aws detective get-investigation \
  --graph-arn arn:aws:detective:us-east-1:123456789012:graph:a1b2c3d4 \
  --investigation-id 000000000000000000001

Step 3: Search Entities Programmatically

#!/usr/bin/env python3
"""Search AWS Detective for suspicious entities."""
import boto3
import json
from datetime import datetime, timedelta

detective = boto3.client('detective')

def list_behavior_graphs():
    """List all Detective behavior graphs."""
    response = detective.list_graphs()
    return response.get('GraphList', [])

def get_investigation_indicators(graph_arn, investigation_id, max_results=50):
    """Get indicators for a specific investigation."""
    response = detective.list_indicators(
        GraphArn=graph_arn,
        InvestigationId=investigation_id,
        MaxResults=max_results
    )
    return response.get('Indicators', [])

def investigate_guardduty_findings(graph_arn):
    """List high-severity investigations correlated by Detective."""
    response = detective.list_investigations(
        GraphArn=graph_arn,
        FilterCriteria={
            'Severity': {'Value': 'CRITICAL'},
            'Status': {'Value': 'RUNNING'}
        },
        MaxResults=20
    )

    for investigation in response.get('InvestigationDetails', []):
        print(f"Investigation: {investigation['InvestigationId']}")
        print(f"  Entity: {investigation['EntityArn']}")
        print(f"  Status: {investigation['Status']}")
        print(f"  Severity: {investigation['Severity']}")
        print(f"  Created: {investigation['CreatedTime']}")
        print()

if __name__ == "__main__":
    graphs = list_behavior_graphs()
    for graph in graphs:
        print(f"Graph: {graph['Arn']}")
        investigate_guardduty_findings(graph['Arn'])

Step 4: Analyze Finding Groups for Attack Campaigns

# List investigations with high severity
aws detective list-investigations \
  --graph-arn arn:aws:detective:us-east-1:123456789012:graph:a1b2c3d4 \
  --filter-criteria '{"Severity":{"Value":"HIGH"}}' \
  --max-results 10

Step 5: Check Entity Indicators

# Get indicators for a specific investigation
aws detective list-indicators \
  --graph-arn arn:aws:detective:us-east-1:123456789012:graph:a1b2c3d4 \
  --investigation-id 000000000000000000001 \
  --max-results 50

Expected Output

The list-investigations command returns investigation metadata:

{
  "InvestigationDetails": [
    {
      "InvestigationId": "000000000000000000001",
      "Severity": "CRITICAL",
      "Status": "RUNNING",
      "State": "ACTIVE",
      "EntityArn": "arn:aws:iam::123456789012:user/suspicious-user",
      "EntityType": "IAM_USER",
      "CreatedTime": "2026-03-15T14:30:00Z"
    }
  ]
}

Indicators are retrieved separately via list-indicators and include types such as TTP_OBSERVED, IMPOSSIBLE_TRAVEL, FLAGGED_IP_ADDRESS, NEW_GEOLOCATION, NEW_ASO, NEW_USER_AGENT, RELATED_FINDING, and RELATED_FINDING_GROUP.

Verification

1. Confirm behavior graph has data: aws detective list-graphs returns non-empty list
2. Validate investigation results contain entity timelines with API call sequences
3. Cross-reference Detective findings with raw CloudTrail logs for accuracy
4. Verify finding group correlations match manual investigation conclusions
5. Confirm automated alerts trigger for HIGH/CRITICAL severity investigations

Other files in this skill

• assets/template.md
• references/api-reference.md
• references/standards.md
• references/workflows.md
• scripts/process.py

assets/template.md (verbatim)

AWS Detective Investigation Checklist

Pre-Investigation

• Confirm Detective is enabled and receiving data
• Identify trigger (GuardDuty finding, alert, manual hunt)
• Define scope time window
• Document initial IOCs

Entity Investigation

• IAM User/Role profile reviewed
• API call timeline analyzed
• Geographic anomalies checked (impossible travel)
• New API calls identified (never seen before)
• Privilege escalation attempts documented
• AssumeRole chain traced

Network Analysis

• VPC Flow Logs reviewed for entity
• Outbound connections to suspicious IPs identified
• Data transfer volumes assessed
• DNS query patterns checked

Finding Correlation

• All related GuardDuty findings grouped
• MITRE ATT&CK techniques mapped
• Attack timeline constructed
• Initial access vector identified

Response Actions

• Evidence preserved (or capture rationale if immediate containment required)
• Compromised credentials disabled
• Active sessions revoked
• Affected resources isolated
• Stakeholders notified

references/api-reference.md (verbatim)

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

references/standards.md (verbatim)

Standards & References

MITRE ATT&CK Cloud Matrix

• TA0001 Initial Access: T1078 (Valid Accounts), T1190 (Exploit Public-Facing Application)
• TA0003 Persistence: T1098 (Account Manipulation), T1136 (Create Account)
• TA0004 Privilege Escalation: T1078, T1484 (Domain Policy Modification)
• TA0005 Defense Evasion: T1562 (Impair Defenses), T1070 (Indicator Removal)
• TA0006 Credential Access: T1528 (Steal Application Access Token)
• TA0007 Discovery: T1580 (Cloud Infrastructure Discovery), T1526 (Cloud Service Discovery)
• TA0009 Collection: T1530 (Data from Cloud Storage)
• TA0010 Exfiltration: T1537 (Transfer Data to Cloud Account)

AWS Documentation

• AWS Detective User Guide
• AWS Detective API Reference
• GuardDuty Finding Types

CIS AWS Foundations Benchmark

• Section 4: Monitoring (relevant to Detective integration)

references/workflows.md (verbatim)

AWS Detective Investigation Workflow

Phase 1: Triage

1. Review GuardDuty HIGH/CRITICAL findings
2. Open Detective console → Finding Groups
3. Identify clustered findings pointing to same entity

Phase 2: Entity Investigation

1. Select entity (IAM user/role, EC2, IP)
2. Review 24h behavior timeline
3. Identify unusual API calls, new geolocations, impossible travel
4. Check for privilege escalation patterns (CreateAccessKey, AttachPolicy)

Phase 3: Scope Assessment

1. Trace lateral movement via AssumeRole chains
2. Check S3 data access patterns
3. Review VPC Flow Logs for unusual outbound connections
4. Identify all compromised credentials

Phase 4: Correlation

1. Map findings to MITRE ATT&CK techniques
2. Build attack timeline from entity profiles
3. Identify initial access vector
4. Document indicators of compromise (IOCs)

Phase 5: Response

1. Preserve evidence (CloudTrail logs, flow logs, snapshots) when safe
2. Disable compromised credentials
3. Revoke active sessions
4. Isolate affected resources
5. If active impact is ongoing, contain first and document evidence trade-offs

Back to mukul975/Anthropic-Cybersecurity-Skills (817 security skills) or Agent skills.