TrailTool

TrailTool aggregates CloudTrail logs to simplify analysis for AI agents. It combines:

• A Lambda function for ingesting, parsing, and correlating CloudTrail logs from an S3 bucket
• DynamoDB tables for persisting queryable entities: People, Sessions, Roles, Services, Resources
• trailtool CLI for accessing entity data to support common security and operational use cases

With TrailTool, you can:

• Investigate and summarize web/CLI sessions clarifying access patterns
• Generate least-privilege IAM policies from actual usage
• Detect ClickOps resources created or modified via console instead of IaC

For more details about how to use TrailTool, see https://engseclabs.com/blog/cloudtrail-for-ai-agents/.

A hosted version with more features (e.g. UI, API, MCP) is available - see trailtool.io.

Quick Start

Deploy the Ingestor

Requires AWS SAM CLI

New CloudTrail

Creates new CloudTrail trail/S3 bucket in addition to trailtool resources:

cd ingestor
sam deploy --template-file template-sandbox.yaml

Existing CloudTrail

Connects to your existing CloudTrail S3 bucket. A custom CloudFormation resource automatically enables EventBridge notifications on the bucket (required for triggering the ingestor on new log delivery):

cd ingestor
sam deploy --parameter-overrides \
  CloudTrailBucketName=your-bucket

Install the CLI

brew install engseclabs/tap/trailtool

Or with Go:

go install github.com/engseclabs/trailtool/cmd/trailtool@latest

Usage

# People
trailtool people list

# Sessions
trailtool sessions list --user alice@example.com --days 7
trailtool sessions detail --start-time "2025-01-15T10:30:00Z"
trailtool sessions summarize --start-time "2025-01-15T10:30:00Z"  # requires Bedrock

# Accounts
trailtool accounts list
trailtool accounts detail 123456789012

# Roles
trailtool roles list
trailtool roles detail MyRole
trailtool roles policy MyRole
trailtool roles policy MyRole --include-denied --explain

# Services
trailtool services list
trailtool services detail s3.amazonaws.com

# Resources
trailtool resources list --days 30
trailtool resources list --clickops                    # ClickOps: console-created resources
trailtool resources list --clickops --service iam      # ClickOps filtered by service
trailtool resources list --service s3 --days 7

All commands support --format json for machine-readable output.

Using TrailTool with AI Coding Agents

TrailTool is designed to work well with AI coding agents like Claude Code and Cursor. To teach your agent about TrailTool's capabilities, copy docs/agent-instructions.md into your project as CLAUDE.md (or your agent's equivalent configuration file).

This gives your agent full knowledge of the CLI and step-by-step workflows for common tasks like detecting ClickOps, generating least-privilege IAM policies, and validating break-glass access.