I tried to verify whether Amazon GuardDuty Investigation can be used in an event-driven manner, but it turned out it cannot.
This page has been translated by machine translation. View original
Hello, this is Usuda.
Is everyone doing incident investigations on AWS? (Greeting)
The other day, an Investigation feature was added to Amazon GuardDuty in preview.
Since starting an investigation requires explicitly triggering it from our side, I wondered if it would be possible to automatically trigger it or automatically capture events, so I tested the behavior.
As the title suggests, I was unable to automatically capture events, so I'll summarize what happened along with how to handle it.
Overview
Amazon GuardDuty Investigation is a feature that allows additional investigation of detected threats and more.
Traditionally, Amazon GuardDuty detects threats from various activities on AWS, but it was often necessary to collect additional information to assess the impact and respond — such as what operations were performed before and after the threat, and retrieving related information about the target resource.
Although it's still in preview, Amazon GuardDuty Investigation can investigate across a single Finding, a single AWS account, or an entire AWS Organizations, conducting various additional investigations with the help of AI, and summarizing what is happening and how to respond — it's a great feature!
It may become even more convenient when officially released, but since it's still in preview, I'll summarize the results of various tests. (I'll also send feedback to AWS)
What I Want to Do
As mentioned above, investigations using the current Amazon GuardDuty Investigation must be started manually.
For example, you'd want to automatically trigger an investigation whenever a Finding is detected, or receive a Slack notification when the investigation results are ready.
So first, I investigated whether events are emitted from Amazon EventBridge.
No Events Are Emitted
When Amazon GuardDuty detects a threat, a "detail-type": "GuardDuty Finding" event is published from Amazon EventBridge. For details, see this user guide.
I first checked whether there are any additional events published by Amazon GuardDuty, such as those related to Amazon GuardDuty Investigation.
Normally, detections are notified by configuring an event rule like the one below.
This time, I changed it so that all Amazon GuardDuty events are notified. Regardless of investigations, various actions will be notified, so this is a double-edged sword setting only suitable for brief testing.
As a result, I was able to capture the execution of CreateInvestigation itself as an AwsApiCall, as shown below.
{
"version": "0",
"id": "00000000-0000-0000-0000-000000000000",
"detail-type": "AWS API Call via CloudTrail",
"source": "aws.guardduty",
"account": "123456789012",
"time": "2026-07-07T01:58:24Z",
"region": "ap-northeast-1",
"resources": [],
"detail": {
"eventVersion": "1.09",
"userIdentity": {
"…omitted…"
},
"eventTime": "2026-07-07T01:58:24Z",
"eventSource": "guardduty.amazonaws.com",
"eventName": "CreateInvestigation",
"awsRegion": "ap-northeast-1",
"sourceIPAddress": "203.0.113.10",
"userAgent": "Boto3/1.43.41 md/Botocore#1.43.41 ua/2.1 os/linux lang/python#3.13.13 exec-env/CloudShell Botocore/1.43.41",
"requestParameters": {
"triggerPrompt": "Investigate account 123456789012",
"detectorId": "1111111111111111111111111111111",
"clientToken": "00000000-0000-0000-0000-000000000000"
},
"responseElements": {
"investigationId": "22222222-2222-2222-2222-222222222222"
},
"requestID": "33333333-3333-3333-3333-333333333333",
"eventID": "44444444-4444-4444-4444-444444444444",
"readOnly": false,
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "123456789012",
"eventCategory": "Management",
"sessionCredentialFromConsole": "true"
}
}
However, no other events were published. In other words, the following is true:
- There are no event types related to Amazon GuardDuty Investigation
- Even when an Amazon GuardDuty Investigation completes, it cannot be detected passively
So, since no events are emitted, you need to explicitly go and fetch the results.
Running the Investigation with a Script and Fetching the Results
Since you also need to explicitly trigger an investigation after a Findings event is emitted, it seems best for now to make the entire process from triggering to retrieving the results a single sequence of operations.
The article below describes how to run investigations using the AWS CLI, so in this article I'll try doing it with Python.
For the code, please refer to boto3's create_investigation and related documentation.
Roughly speaking, the following script did the job.
import time
import boto3
ACCOUNT_ID = "902096752875"
client = boto3.client("guardduty")
detector_id = client.list_detectors()["DetectorIds"][0]
investigation_id = client.create_investigation(
DetectorId=detector_id,
TriggerPrompt=f"Investigate account {ACCOUNT_ID}",
)["InvestigationId"]
while True:
resp = client.get_investigation(
DetectorId=detector_id,
InvestigationId=investigation_id,
)
investigation = resp["Investigation"]
status = investigation["Status"]
print(status)
if status in ("COMPLETED", "FAILED"):
break
time.sleep(15)
print(investigation.get("RiskLevel"))
print(investigation.get("Confidence"))
print(investigation.get("Summary"))
Let me highlight a few points.
As also mentioned in the AWS CLI article above, unlike the console, when running an investigation via the API you don't simply specify Findings or an AWS account directly — instead, you put the instructions including those elements in natural language into the TriggerPrompt parameter.
It really feels like generative AI.
So I've assembled this in a simplified way. On the flip side, since it's not an explicit parameter, it's also a point to be careful about as it can be a bit cumbersome to handle.
Also, the investigation status is found in response["Investigation"]["Status"] via get_investigation, and it seems you just need to wait until it becomes either "COMPLETED" or "FAILED".
By the way, true to the nature of generative AI, the investigation results vary quite a bit even with the same prompt — the titles alone differed like this.
The content also changes quite a bit, so I'm curious how consistently good output will be produced in actual investigations.
Summary
I checked whether the Amazon GuardDuty Investigation feature can be handled in an event-driven manner, but at least in its current preview state, it cannot.
It seems best to create notifications based on Findings detections and the results of the corresponding investigations.
