GuardDuty Detectors & Finding Types

Enabling data sources and interpreting finding severity via SDK.

A GuardDuty detector is the single object that turns threat detection on for a region, and its DataSources configuration decides how wide a net it casts. Everything downstream - which findings show up, how quickly, and how serious they are - flows from what the detector is configured to look at. This page covers configuring data sources and reading the finding types and severities that come back.

Recipe

Quick-reference recipe card - copy-paste ready.

{
  "detectorId": "<detector-id>",
  "dataSources": {
    "s3Logs": { "enable": true },
    "kubernetes": { "auditLogs": { "enable": true } },
    "malwareProtection": { "scanEc2InstanceWithFindings": { "ebsVolumes": { "enable": true } } }
  }
}

When to reach for this:

• Widening GuardDuty coverage beyond the default VPC Flow Logs/DNS/CloudTrail signals.
• Triaging a batch of findings and needing to sort by severity programmatically.
• Building a dashboard or alert pipeline that needs to interpret Type strings, not just display them raw.
• Auditing which data sources are actually enabled on a detector you inherited.

Working Example

Enable additional data sources on an existing detector, then list and interpret findings by severity.

# --- Python (boto3) ---
import boto3
 
guardduty = boto3.client("guardduty", region_name="us-east-1")
detector_id = "<detector-id>"
 
# Widen coverage: S3 data events and EKS audit logs.
guardduty.update_detector(
    DetectorId=detector_id,
    DataSources={
        "S3Logs": {"Enable": True},
        "Kubernetes": {"AuditLogs": {"Enable": True}},
    },
)
 
# List findings sorted by severity, highest first.
resp = guardduty.list_findings(
    DetectorId=detector_id,
    SortCriteria={"AttributeName": "severity", "OrderBy": "DESC"},
    MaxResults=25,
)
details = guardduty.get_findings(DetectorId=detector_id, FindingIds=resp["FindingIds"])
 
for f in details["Findings"]:
    sev = f["Severity"]
    label = "high" if sev >= 7 else "medium" if sev >= 4 else "low"
    print(f["Type"], sev, label)

// --- TypeScript (AWS SDK v3) ---
import {
  GuardDutyClient, UpdateDetectorCommand, ListFindingsCommand, GetFindingsCommand,
} from "@aws-sdk/client-guardduty";
 
const guardduty = new GuardDutyClient({ region: "us-east-1" });
const detectorId = "<detector-id>";
 
// Widen coverage: S3 data events and EKS audit logs.
await guardduty.send(new UpdateDetectorCommand({
  DetectorId: detectorId,
  DataSources: {
    S3Logs: { Enable: true },
    Kubernetes: { AuditLogs: { Enable: true } },
  },
}));
 
// List findings sorted by severity, highest first.
const resp = await guardduty.send(new ListFindingsCommand({
  DetectorId: detectorId,
  SortCriteria: { AttributeName: "severity", OrderBy: "DESC" },
  MaxResults: 25,
}));
const details = await guardduty.send(new GetFindingsCommand({
  DetectorId: detectorId, FindingIds: resp.FindingIds,
}));
 
for (const f of details.Findings ?? []) {
  const sev = f.Severity ?? 0;
  const label = sev >= 7 ? "high" : sev >= 4 ? "medium" : "low";
  console.log(f.Type, sev, label);
}

What this demonstrates:

• UpdateDetector adds data sources to a detector that already exists - you do not need to recreate it to widen coverage.
• SortCriteria on ListFindings orders by severity (or updatedAt), so triage-by-severity does not need client-side sorting.
• The ListFindings -> GetFindings two-call pattern is required - IDs and full detail are separate calls.
• Severity buckets (low/medium/high) are a convention, not an API field - GuardDuty returns the raw float and leaves labeling to you.

Deep Dive

Data Sources, What Each Covers

• Foundational sources (always on, no extra config) - VPC Flow Logs, DNS query logs, and CloudTrail management events. These start analyzing the moment CreateDetector runs.
• S3 protection (S3Logs) - adds S3 data-event analysis, surfacing findings like unusual API calls against a bucket or requests from a Tor exit node.
• EKS protection (Kubernetes.AuditLogs) - analyzes Kubernetes audit logs for control-plane threats like anonymous access attempts or privilege escalation inside a cluster.
• Malware Protection (MalwareProtection) - triggered by certain EC2/EBS-related findings, it snapshots and scans the volume for malware without needing an agent on the instance.
• Each optional source is billed by volume analyzed - enabling all of them by default on every account is a cost decision, not just a coverage one.

Reading Finding Type Strings

• A Type string has the shape Threat:ResourceType/ThreatDetail, e.g. UnauthorizedAccess:EC2/SSHBruteForce or Backdoor:EC2/C&CActivity.B.
• The prefix before the colon groups the category (UnauthorizedAccess, Backdoor, CryptoCurrency, Trojan, Recon, Policy, and others) - useful for routing rules that act on a whole category.
• The resource segment (EC2, S3, IAMUser, Kubernetes) tells you what was affected, which usually maps directly to the remediation target.
• New finding types are added over time as threat patterns evolve - do not hardcode an exhaustive list; match on prefix/category where possible instead of an enumerated set.

Severity in Practice

• These bands are a common convention, not an AWS-enforced threshold - some teams tune the cutoffs to their own risk tolerance.
• Severity can shift on an existing finding as GuardDuty gathers more signal (UpdatedAt changes) - do not treat the first severity you saw as final.

Python & TypeScript Notes

# boto3 paginator for large finding sets instead of manual NextToken handling.
paginator = guardduty.get_paginator("list_findings")
for page in paginator.paginate(DetectorId=detector_id):
    print(len(page["FindingIds"]))

// SDK v3 loops on NextToken directly - there is no paginator helper for GuardDuty.
let nextToken: string | undefined;
do {
  const page = await guardduty.send(new ListFindingsCommand({ DetectorId: detectorId, NextToken: nextToken }));
  console.log(page.FindingIds?.length);
  nextToken = page.NextToken;
} while (nextToken);

Gotchas

• Assuming a new detector has findings immediately - GuardDuty needs live traffic/logs to analyze; a freshly created detector in a quiet account can show zero findings for a while. Fix: do not treat an empty result as a broken integration - generate or wait for real activity.
• Treating the severity float as a fixed enum - some tooling expects Low/Medium/High strings, but the API returns a raw number. Fix: bucket the float yourself at the boundaries your team agrees on.
• Forgetting optional data sources cost extra - enabling S3 protection, EKS audit logs, or Malware Protection across a large estate can meaningfully increase the bill. Fix: enable per-account based on actual risk, not uniformly by default.
• Parsing Type with a hardcoded switch statement - new finding types ship regularly, and an exhaustive switch silently drops unknown ones into a default branch. Fix: match on the category prefix and log/handle unrecognized types visibly instead of swallowing them.
• Not batching GetFindings calls - passing more than 50 FindingIds in one call fails. Fix: chunk IDs into batches of 50 before calling GetFindings.
• Confusing UpdateDetector's data source shape with CreateDetector's - both accept a DataSources object, but forgetting nested keys (Kubernetes.AuditLogs.Enable, not Kubernetes.Enable) silently no-ops. Fix: check GetDetector after updating to confirm the source actually enabled.

Alternatives

FAQs

Related

• Threat Detection Basics - the end-to-end enable-and-list flow this page builds on.
• GuardDuty & Security Hub Together - where these findings go once Security Hub is enabled.
• Automated Response to GuardDuty Findings - acting on the findings read here.
• Threat Detection via SDK Best Practices - triage workflow and suppression hygiene.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).