Security teams lose hours every week doing the same tedious work: pulling a GuardDuty finding, then manually stitching together CloudTrail events, network logs, and resource metadata to figure out whether it’s real. AWS’s new GuardDuty investigation agent, now in public preview, is built to close that gap turning a finding into a structured risk assessment in minutes instead of hours.
What It Actually Returns
Unlike a raw GuardDuty alert, an investigation produces a defined output: a risk level (Info, Low, Medium, High, or Critical), a confidence rating (Unknown, Low, Medium, or High), a plain-language summary of what happened, additional investigation detail, a MITRE ATT&CK technique mapping, and a set of recommended actions, including specific AWS CLI commands you can run to remediate. You can scope an investigation to a single finding, a single account, or your entire organization, and the CLI/API path also accepts a free-form trigger prompt of up to 2,048 characters, so you can point the agent at a specific concern in plain English.
What a Completed Investigation Looks Like
Say GuardDuty flags anomalous API activity from an IAM role that normally only touches S3. Run an investigation against that finding, and a few minutes later you get back something like this: risk level Critical, confidence High, a short narrative explaining that the role assumed a second role outside its usual pattern and then made a burst of unusual read calls, a MITRE ATT&CK mapping pointing to credential access and discovery techniques, and a recommended-actions list that includes the specific CLI commands to revoke the session and rotate the credential. That correlation and write-up is the actual value here. A standard GuardDuty finding would tell you the anomaly happened; the investigation agent tells you what it means and what to do about it.
Setting It Up
You’ll need three new IAM permissions: guardduty:CreateInvestigation, guardduty:GetInvestigation, and guardduty:ListInvestigations. Administrator accounts can create and view investigations for themselves and their member accounts; member accounts can only view their own. From the console, enabling investigations is a one-time toggle under GuardDuty settings, after which you can start an investigation from the Investigations page by finding ID, account ID, or organization-wide scope.
Via the Console
If you’d rather click than type, the console path is straightforward. Open GuardDuty and select Investigations from the navigation pane; the first time through, you’ll see a prompt to enable the feature under Settings. Once enabled, choose Initiate Investigation and pick a scope: a specific finding ID for a deep dive on one alert, an account ID to assess a single account’s overall posture, or All accounts for an organization-wide sweep, which is useful if you suspect lateral movement. During public preview, account-level investigations typically finish in 2 to 5 minutes, while a single-finding investigation takes closer to 10 to 12 minutes. When it’s done, opening the investigation shows five sections: general information (ID, status, timestamps), a plain-language summary, a MITRE ATT&CK mapping of affected resources and techniques, a threat assessment with the risk and confidence scores, and the recommended actions.
Automating It With the CLI
For automation, the same actions are available through the CLI. Before you can call any of it, you need your detector ID, which is unique per account and Region:
aws guardduty list-detectors --region us-east-1That returns a DetectorIds array. Grab the value and reuse it for every subsequent call in that Region, or export it as an environment variable if you’re scripting this. To kick off an investigation against a specific finding:
aws guardduty create-investigation --region us-east-1 \
--detector-id <your-detector-id> \
--trigger-prompt "Investigate this finding ID <finding-id>"The response includes an InvestigationId. Investigations run asynchronously, so you poll for status until it flips from RUNNING to COMPLETED:
aws guardduty get-investigation --region us-east-1 \
--detector-id <your-detector-id> \
--investigation-id <investigation-id> \
--query 'Investigation.Status'Checking roughly every 30 seconds is enough for most cases. If the status comes back FAILED, that almost always traces back to a permissions gap, so that’s the first thing to check. Once you’ve run a few, list-investigations gives you a filterable view of everything you’ve kicked off against a given detector:
aws guardduty list-investigations --region us-east-1 \
--detector-id <your-detector-id> \
--max-results 10Where It Fits In Your Pipeline
The agent isn’t meant to replace your SIEM. It’s a step you insert before findings reach one. A common pattern: findings already flow through EventBridge to your SIEM, so you add a Lambda function to that pipeline that calls CreateInvestigation, waits for completion, and forwards the enriched result (risk level, confidence, MITRE mapping, recommendations) alongside the raw finding. Critical, high-confidence results can route straight to your incident queue; low-risk, high-confidence ones can auto-close or batch for weekly review. That shifts analyst time from correlation work to validating an assessment that’s already been done.
It’s also worth distinguishing this from AWS Security Incident Response (AWS SIR), announced at re:Invent 2024. The investigation agent gives you an on-demand assessment of a finding or account; AWS SIR is the escalation path for active incidents where you want AWS’s human responders involved alongside AI-assisted triage. Use the investigation agent to size up what you’re looking at, and open a SIR case when you need help containing it.
Talking to It Through the AWS MCP Server
The investigation agent is also exposed through the AWS MCP server, part of AWS’s broader push to make its services callable from AI assistants using the Model Context Protocol. If your team already works inside an MCP-compatible client, you can skip the console and CLI entirely and just describe what you want investigated. Asking your assistant to look into the most recent high-severity finding in a specific account, or to pull up every investigation from the last day and flag which ones need a human to look at them, gets routed to the same CreateInvestigation and ListInvestigations calls under the hood. Responses coming back through an AI assistant can vary run to run, so treat them as a starting point for review rather than a final answer, especially for anything you’re about to act on.
Practical Constraints To Plan Around
During public preview, the agent runs in 10 regions, including US East (N. Virginia and Ohio), US West (Oregon), Canada (Central), four EU regions, and Asia Pacific (Tokyo). It’s free to use during preview, capped at 10 investigations per account per day and 100 total per account, and failed investigations don’t count against that quota. Data stays stored in the region where you started the investigation, though AWS notes that processing may route through other regions in the same geography via its Cross-Region Inference Service. If that data-residency detail matters for your compliance posture, check the routing table in the GuardDuty user guide before rolling this out broadly.
Getting Started
Enable investigations in your GuardDuty console, run one against a recent finding, and read the structured output before deciding how deep to integrate it into your pipeline. If your team already works inside an AI assistant connected to the AWS MCP server, you can skip the console entirely and just ask it to investigate a finding in plain language.
About
With over 25 years in the technology sector, Keith has spent the last decade providing consultancy, support, and strategic direction to customers across multiple cloud platforms.
Disclaimer: The information shared on this blog is for informational purposes only and should not be considered as professional advice. The opinions presented here are personal and independent of any affiliations with tech companies or organizations.