cloudtrail_lookup_events
Search and retrieve CloudTrail events using specific filters such as EventName, Username, or ResourceType. Specify start and end times for precise event tracking, with default settings for the last 7 days if not provided.
Instructions
Lookup CloudTrail events using filters.
If the user request falls into one of these scenarios, use the Athena tools instead:
- EventName is a data event (e.g. GetObject, DeleteObject, PutObject);
- the user wants to filter by role name;
- the user wants to filter by principal ID;
- the user wants to filter by IP address;
- the user wants to filter by bucket name;
- the user wants to filter by file object in buckets;
- the user wants to filter using regex;
When filtering for EventName, note that the event name is case-sensitive and must match the exact name of the event.
If you want to use operators like 'equals', 'not equals', 'contains', etc., you must use the Athena tools instead.
<IMPORTANT>
Call datetime.datetime.now() to get the current date and time before providing the start and end times.
If the user asks for events happened in the last 7 days, run 'datetime.datetime.now() - datetime.timedelta(days=7)' to get the start date.
Print out the start and end times to the user.
</IMPORTANT>
Parameters:
aws_region (str): The AWS region - use 'us-east-1' if not specified.
attribute_key (str): The name of the event to search for.
Valid attributes keys: EventId | EventName | ReadOnly | Username | ResourceType | ResourceName | EventSource | AccessKeyId
attribute_value (str): The value of the event to search for.
If no key-value pair is provided, use 'ReadOnly'='false'.
start_time (str): start timestamp with format 'YYYY-MM-DD HH:MM:SS' (e.g. '2025-04-10 12:45:50').
If not provided, use 'datetime.datetime.now() - datetime.timedelta(days=7)' to get the start date.
end_time (str): end timestamp with format 'YYYY-MM-DD HH:MM:SS' (e.g. '2025-04-11 12:45:50').
If not provided, use 'datetime.datetime.now()' to get the end date.
max_results (int): Maximum number of events to return.
Returns:
list: A list of CloudTrail events matching the specified criteria.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| attribute_key | Yes | ||
| attribute_value | Yes | ||
| aws_region | Yes | ||
| end_time | Yes | ||
| max_results | No | ||
| start_time | Yes |
Input Schema (JSON Schema)
{
"properties": {
"attribute_key": {
"title": "Attribute Key",
"type": "string"
},
"attribute_value": {
"title": "Attribute Value",
"type": "string"
},
"aws_region": {
"title": "Aws Region",
"type": "string"
},
"end_time": {
"title": "End Time",
"type": "string"
},
"max_results": {
"default": 50,
"title": "Max Results",
"type": "integer"
},
"start_time": {
"title": "Start Time",
"type": "string"
}
},
"required": [
"aws_region",
"attribute_key",
"attribute_value",
"start_time",
"end_time"
],
"title": "cloudtrail_lookup_eventsArguments",
"type": "object"
}