{"id":50713099,"url":"https://github.com/engseclabs/trailtool","last_synced_at":"2026-06-26T17:00:44.733Z","repository":{"id":343815898,"uuid":"1178272049","full_name":"engseclabs/trailtool","owner":"engseclabs","description":"Simplified CloudTrail analysis for AI agents","archived":false,"fork":false,"pushed_at":"2026-05-24T20:10:21.000Z","size":9803,"stargazers_count":28,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T22:12:18.293Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/engseclabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-10T21:36:49.000Z","updated_at":"2026-05-24T20:09:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/engseclabs/trailtool","commit_stats":null,"previous_names":["engseclabs/trailtool"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/engseclabs/trailtool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engseclabs%2Ftrailtool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engseclabs%2Ftrailtool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engseclabs%2Ftrailtool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engseclabs%2Ftrailtool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/engseclabs","download_url":"https://codeload.github.com/engseclabs/trailtool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engseclabs%2Ftrailtool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34825611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T17:00:26.107Z","updated_at":"2026-06-26T17:00:44.728Z","avatar_url":"https://github.com/engseclabs.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# TrailTool\n\nTrailTool aggregates CloudTrail logs to simplify analysis for AI agents. It combines:\n\n- A Lambda function for ingesting, parsing, and correlating CloudTrail logs from an S3 bucket\n- DynamoDB tables for persisting queryable entities: People, Sessions, Roles, Services, Resources\n- `trailtool` CLI for accessing entity data to support common security and operational use cases\n\nWith TrailTool, you can:\n\n- Investigate and summarize web/CLI sessions clarifying access patterns\n- Track activity across role assumptions — see which human session assumed which roles and what they did\n- Generate least-privilege IAM policies from actual usage\n- Detect ClickOps resources created or modified via console instead of IaC\n\nFor more details about how to use TrailTool, see https://engseclabs.com/blog/cloudtrail-for-ai-agents/.\n\nA hosted version with more features (e.g. UI, API, MCP) is available - see [trailtool.io](https://trailtool.io).\n\n## Quick Start\n\n### Deploy the Ingestor\n\n*Requires [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)*\n\n### New CloudTrail\n\nCreates new CloudTrail trail/S3 bucket in addition to trailtool resources:\n\n```bash\ncd ingestor\nsam deploy --template-file template-sandbox.yaml\n```\n\n### Existing CloudTrail\n\nConnects 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):\n\n```bash\ncd ingestor\nsam deploy --parameter-overrides \\\n  CloudTrailBucketName=your-bucket\n```\n\n## Install the CLI\n\n```bash\nbrew install engseclabs/tap/trailtool\n```\n\nOr with Go:\n\n```bash\ngo install github.com/engseclabs/trailtool/cmd/trailtool@latest\n```\n\n### Usage\n\n```bash\n# People\ntrailtool people list\n\n# Sessions\ntrailtool sessions list --user alice@example.com --days 7\ntrailtool sessions list --user alice@example.com --days 7 --long  # show full role names\ntrailtool sessions detail --at 2025-01-15T10:30\ntrailtool sessions detail --index 1 --user alice@example.com --days 7  # by list position\ntrailtool sessions detail --at 2025-01-15T10:30 --user alice@example.com\ntrailtool sessions detail --at latest\ntrailtool sessions summarize --at 2025-01-15T10:30  # requires Bedrock\n\n# Accounts\ntrailtool accounts list\ntrailtool accounts detail 123456789012\ntrailtool accounts detail --index 1      # by list position\n\n# Roles\ntrailtool roles list\ntrailtool roles detail MyRole\ntrailtool roles detail --index 2         # by list position\ntrailtool roles policy MyRole\ntrailtool roles policy MyRole --include-denied --explain\n\n# Session-scoped policy (tighter: only what this session actually did)\ntrailtool sessions policy --at latest\ntrailtool sessions policy --at 2025-01-15T10:35 --user alice@example.com --explain\n\n# Services\ntrailtool services list\ntrailtool services detail s3.amazonaws.com\ntrailtool services detail --index 3      # by list position\n\n# Resources\ntrailtool resources list --days 30\ntrailtool resources list --clickops                    # ClickOps: console-created resources\ntrailtool resources list --clickops --service iam      # ClickOps filtered by service\ntrailtool resources list --service s3 --days 7\n```\n\n### Role Chaining\n\nTrailTool automatically correlates `AssumeRole` calls back to the originating human session, for both console switch-role and programmatic (`aws sts assume-role`) flows. This lets you answer \"who actually did this?\" even when the CloudTrail actor is an assumed role with no obvious human attribution.\n\n```\n$ trailtool sessions list --days 1\n\n#  WHEN        USER                  ROLE         ACCOUNT        EVENTS  TYPE     DURATION  CHAINED\n1  5 mins ago  alice@example.com     AdminAccess  123456789012   84      API      12m       → 2 role(s)\n2  5 mins ago  alice@example.com     DeployRole   123456789012   31      API      8m        ↑ child\n3  5 mins ago  alice@example.com     AuditRole    123456789012   12      API      3m        ↑ child\n```\n\n`→ N role(s)` means this human session assumed N roles. `↑ child` means this session was created via `AssumeRole` and is attributed back to its parent.\n\n```bash\n# See which roles a session assumed and how many events each generated\ntrailtool sessions detail --at 2025-01-15T10:30 --user alice@example.com\n\n# The detail view shows the full chain:\n# Assumed by: alice@example.com at 2025-01-15T10:30:00Z            (on child sessions)\n#   → trailtool sessions detail --at 2025-01-15T10:30 --user alice@example.com\n#\n# Assumed Roles (2, 43 events):                                    (on parent sessions)\n#   2025-01-15T10:35:00Z  DeployRole  31 events  8m\n#     → trailtool sessions detail --at 2025-01-15T10:35 --user alice@example.com\n#   2025-01-15T10:36:00Z  AuditRole   12 events  3m\n#     → trailtool sessions detail --at 2025-01-15T10:36 --user alice@example.com\n```\n\n### `aws login` Session Detection\n\nWhen a developer runs `aws login` to vend credentials to an AI agent (Claude Code, VS Code Copilot, etc.), TrailTool detects the `CreateOAuth2Token` event on `signin.amazonaws.com` and correlates it back to the agent session that received those credentials. The agent session is tagged as `LOGIN` type and includes attribution back to the authorizing human session.\n\n```\n$ trailtool sessions list --days 1\n\nWHEN        USER                  ROLE         ACCOUNT        EVENTS  TYPE     DURATION  CHAINED\n5 mins ago  alice@example.com     AdminAccess  123456789012   3       LOGIN    8m        ← login\n8 mins ago  alice@example.com     AdminAccess  123456789012   84      API      12m\n```\n\n`← login` means the session's credentials were vended via `aws login` by a human in another session. The detail view shows the attribution:\n\n```\nCredentials granted via aws login by: alice@example.com at 2025-01-15T10:30:00Z (8 minutes ago)\n  → trailtool sessions detail --at 2025-01-15T10:30 --user alice@example.com\n```\n\nThis distinguishes agent-driven activity (credentials vended by a human developer via `aws login`) from background automation or long-running CLI sessions.\n\nAll commands support `--format json` for machine-readable output.\n\n## Using TrailTool with AI Coding Agents\n\nTrailTool 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`](docs/agent-instructions.md) into your project as `CLAUDE.md` (or your agent's equivalent configuration file).\n\nThis 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.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fengseclabs%2Ftrailtool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fengseclabs%2Ftrailtool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fengseclabs%2Ftrailtool/lists"}