GuardDuty Findings API for MCP Servers — Querying, Filtering, Archiving

ListFindings with filter criteria

ListFindings returns finding IDs (not finding details) matching the specified criteria. You must call GetFindings with the returned IDs to get the actual finding content. The maximum page size is 50 IDs per ListFindings call and 50 findings per GetFindings call.

# List all unarchived High-severity findings, newest first
aws guardduty list-findings \
  --detector-id abc1234567890abcdef1234567890 \
  --finding-criteria '{
    "Criterion": {
      "severity": {"Gte": 7},
      "service.archived": {"Eq": ["false"]}
    }
  }' \
  --sort-criteria '{"AttributeName": "updatedAt", "OrderBy": "DESC"}' \
  --max-results 50

# List findings of a specific type (EC2 credential exfiltration)
aws guardduty list-findings \
  --detector-id abc1234567890abcdef1234567890 \
  --finding-criteria '{
    "Criterion": {
      "type": {
        "Equals": [
          "InstanceCredentialExfiltration:EC2/NoInstanceProfile",
          "InstanceCredentialExfiltration:EC2/ScheduledEvent"
        ]
      }
    }
  }'

# List findings affecting a specific ECS cluster (by tag)
aws guardduty list-findings \
  --detector-id abc1234567890abcdef1234567890 \
  --finding-criteria '{
    "Criterion": {
      "resource.instanceDetails.tags.key": {"Equals": ["aws:ecs:clusterName"]},
      "resource.instanceDetails.tags.value": {"Equals": ["mcp-production-cluster"]}
    }
  }'

# Paginate through all findings (NextToken pattern)
TOKEN=""
while true; do
  RESULT=$(aws guardduty list-findings \
    --detector-id abc1234567890abcdef1234567890 \
    --max-results 50 \
    ${TOKEN:+--next-token "$TOKEN"} \
    --output json)
  echo "$RESULT" | jq -r '.FindingIds[]'
  TOKEN=$(echo "$RESULT" | jq -r '.NextToken // empty')
  [ -z "$TOKEN" ] && break
done

GetFindings response structure

The GetFindings response includes the full finding JSON for each requested ID. The key fields for MCP server incident response:

# Fetch details for specific finding IDs (max 50 per call)
aws guardduty get-findings \
  --detector-id abc1234567890abcdef1234567890 \
  --finding-ids "abc123" "def456" \
  --query 'Findings[*].{
    Id:Id,
    Type:Type,
    Severity:Severity,
    Count:Service.Count,
    FirstSeen:Service.EventFirstSeen,
    LastSeen:Service.EventLastSeen,
    Resource:Resource
  }'

# Full finding structure (key fields):
# {
#   "Id": "abc123def456...",           ← deterministic hash: same threat = same ID
#   "Type": "UnauthorizedAccess:EC2/SSHBruteForce",
#   "Severity": 5.0,                   ← float 0.1-8.9
#   "CreatedAt": "2026-10-08T10:00:00Z",
#   "UpdatedAt": "2026-10-08T14:00:00Z", ← updated when count increments
#   "Title": "EC2 instance is being probed on port 22.",
#   "Description": "EC2 instance i-1234567890abcdef0 is being probed...",
#
#   "Service": {
#     "Count": 847,                    ← 847 individual SSH attempts, one finding
#     "EventFirstSeen": "2026-10-07T08:00:00Z",
#     "EventLastSeen": "2026-10-08T14:00:00Z",
#     "Archived": false,
#     "UserFeedback": null,            ← "USEFUL" or "NOT_USEFUL" after UpdateFindingsFeedback
#     "Action": {                      ← what threat actor did
#       "ActionType": "PORT_PROBE",
#       "PortProbeAction": {
#         "PortProbeDetails": [{
#           "LocalPortDetails": {"Port": 22, "PortName": "SSH"},
#           "RemoteIpDetails": {
#             "IpAddressV4": "198.51.100.5",
#             "Country": {"CountryName": "China"},
#             "Organization": {"Asn": "4134", "AsnOrg": "CHINANET-BACKBONE"}
#           }
#         }]
#       }
#     }
#   },
#
#   "Resource": {
#     "ResourceType": "Instance",
#     "InstanceDetails": {
#       "InstanceId": "i-1234567890abcdef0",
#       "InstanceType": "t3.medium",
#       "InstanceState": "running",
#       "Tags": [{"Key": "Service", "Value": "mcp-monitoring"}],
#       "NetworkInterfaces": [{
#         "PublicIp": "54.1.2.3",
#         "SubnetId": "subnet-abc123",
#         "VpcId": "vpc-def456"
#       }]
#     }
#   }
# }

The Service.Action field structure varies by finding type: NetworkConnectionAction for connection-based findings, PortProbeAction for port scans, AwsApiCallAction for API-based threats (unauthorized API calls, unusual CloudTrail activity), and DnsRequestAction for DNS-based findings (C2 communication, crypto mining). Always check ActionType first to know which subfield to parse.

Deduplication behavior and implications for automation

GuardDuty generates one finding per unique combination of: finding type + affected resource + source details. Subsequent occurrences of the same threat increment the existing finding's service.count and update service.eventLastSeen rather than creating new findings. The finding ID is deterministic — you can predict it will be the same for repeated events from the same source to the same target.

# Check if a finding is new vs. updated
aws guardduty get-findings \
  --detector-id abc1234567890abcdef1234567890 \
  --finding-ids "abc123" \
  --query 'Findings[0].{
    Created:CreatedAt,
    Updated:UpdatedAt,
    Count:Service.Count,
    IsNew:Service.IsNew
  }'

# Service.IsNew = true → first time this finding appeared in current publishing cycle
# Service.IsNew = false → this is an update to an existing finding
# Count > 1 and CreatedAt != UpdatedAt → repeated threat, not a first occurrence

# For EventBridge-triggered automation: check DynamoDB to see if you already responded
# Using finding ID as the deduplication key in DynamoDB

# Node.js Lambda example (idempotent remediation check):
# const { DynamoDBClient, PutItemCommand } = require('@aws-sdk/client-dynamodb');
# const dynamo = new DynamoDBClient({});
#
# async function handleFinding(findingId, findingType) {
#   // Conditional put: only insert if findingId doesn't exist
#   // Returns ConditionalCheckFailedException if already handled
#   try {
#     await dynamo.send(new PutItemCommand({
#       TableName: 'guardduty-responses',
#       Item: {
#         findingId: { S: findingId },
#         respondedAt: { S: new Date().toISOString() },
#         type: { S: findingType }
#       },
#       ConditionExpression: 'attribute_not_exists(findingId)'
#     }));
#     return true; // First time responding to this finding
#   } catch (e) {
#     if (e.name === 'ConditionalCheckFailedException') return false; // Already handled
#     throw e;
#   }
# }

The deduplication window is 90 days — after 90 days, GuardDuty expires the finding and a subsequent occurrence creates a new finding with a new ID. For ongoing threats (like an EC2 instance under sustained brute-force), you may need to check service.eventLastSeen to determine if the threat is still active, not just whether the finding exists.

Archiving and feedback

Archiving a finding removes it from the active finding list but retains it in the detector for 90 days. Archived findings still appear in ListFindings when you include service.archived: Eq ["true"] in the filter criteria. Use archiving when you have confirmed the finding is either a false positive or has been fully remediated.

# Archive specific findings (mark as reviewed/resolved)
aws guardduty archive-findings \
  --detector-id abc1234567890abcdef1234567890 \
  --finding-ids "finding-id-1" "finding-id-2" "finding-id-3"

# Unarchive if you need to re-open a finding
aws guardduty unarchive-findings \
  --detector-id abc1234567890abcdef1234567890 \
  --finding-ids "finding-id-1"

# Provide feedback to improve GuardDuty's ML model
# USEFUL = this was a real threat, correct detection
# NOT_USEFUL = this was a false positive
aws guardduty update-findings-feedback \
  --detector-id abc1234567890abcdef1234567890 \
  --finding-ids "finding-id-1" \
  --feedback USEFUL \
  --comments "Confirmed credential exfiltration from compromised MCP worker"

aws guardduty update-findings-feedback \
  --detector-id abc1234567890abcdef1234567890 \
  --finding-ids "finding-id-2" \
  --feedback NOT_USEFUL \
  --comments "Expected port scan from internal monitoring tool"

# Bulk archive all Low findings older than 30 days (cleanup script pattern)
# 1. List findings with severity < 4 updated before 30 days ago
# 2. Archive in batches of 50 (API limit per call)
CUTOFF=$(date -u -d '30 days ago' +%s)000  # epoch milliseconds
aws guardduty list-findings \
  --detector-id abc1234567890abcdef1234567890 \
  --finding-criteria "{
    \"Criterion\": {
      \"severity\": {\"Lt\": 4},
      \"updatedAt\": {\"Lte\": $CUTOFF},
      \"service.archived\": {\"Eq\": [\"false\"]}
    }
  }" \
  --query 'FindingIds' --output json | \
  jq -r '.[]' | \
  xargs -n 50 aws guardduty archive-findings \
    --detector-id abc1234567890abcdef1234567890 \
    --finding-ids

Common finding patterns for MCP server infrastructure

Failure modes reference