RFC: AWS CloudTrail Plugin

[shabbirabdul]

Is this related to an existing feature request or issue?

No response

Summary

This RFC proposes a new aws-cloudtrail plugin that provides deep CloudTrail-specific workflows for security incident investigation, compliance auditing, IAM activity analysis, and change tracking. The plugin integrates the awslabs.cloudtrail-mcp-server and awslabs.aws-knowledge-mcp-server, with one skill and four reference files covering the core security and compliance use cases.

Use case

Security engineers, DevOps teams, and compliance auditors need to investigate incidents, audit changes, and track IAM activity across AWS accounts. Today, this requires manually querying CloudTrail via the console or CLI, correlating events across time windows, and building investigation reports by hand.

Key use cases:

• Security incident investigation: Trace compromised credentials, identify affected resources, build forensic timelines from CloudTrail events
• Compliance auditing: Audit IAM changes, encryption compliance, network security modifications, and root account usage against frameworks like CIS, SOC 2, PCI-DSS
• IAM analysis: Detect privilege escalation patterns, track permission changes, audit access key rotation, and monitor cross-account role assumptions
• Change tracking: Build chronological change logs for any AWS resource, identify who changed what and when

Before / After:

Before (without the plugin):

User: "Who deleted the production S3 bucket?"

Agent: You can check CloudTrail in the AWS Console. Go to Event History, filter by event name DeleteBucket, and look for the resource name. You might also want to check the time range...

After (with aws-cloudtrail):

User: "Who deleted the production S3 bucket?"

Agent: Investigating S3 bucket deletion...

Time (UTC)	Principal	Action	Resource	Source IP	Verdict
2026-04-07T14:23:11Z	arn:aws:iam::123456789012:user/jdoe	DeleteBucket	my-prod-bucket	198.51.100.42	🔴

User jdoe deleted bucket my-prod-bucket from IP 198.51.100.42 at 2:23 PM UTC. This IP is outside your known corporate range. Checking for other activity by this user...

[Additional actions by jdoe in the same time window...]

Recommendation: Disable jdoe's access key immediately and investigate the source IP.

Proposal

Plugin structure

plugins/aws-cloudtrail/
├── .claude-plugin/
│   └── plugin.json            # Plugin manifest
├── .mcp.json                  # 2 MCP server definitions
├── README.md
└── skills/
    └── aws-cloudtrail/
        ├── SKILL.md           # Main skill (~117 lines, auto-triggers)
        └── references/
            ├── security-investigation.md   # Incident response patterns
            ├── compliance-auditing.md      # Audit workflows and frameworks
            ├── iam-analysis.md             # IAM event tracking and escalation detection
            └── lake-queries.md             # CloudTrail Lake SQL patterns

MCP servers

Server	Type	Purpose	Required?
awslabs.cloudtrail-mcp-server	stdio	CloudTrail event lookup, Lake SQL analytics, event data store management	Required
awslabs.aws-knowledge-mcp-server	http	AWS security best practices and service documentation	Required

awslabs.cloudtrail-mcp-server is the primary server — it provides all CloudTrail query capabilities (lookup_events, lake_query, list_event_data_stores, get_query_status, get_query_results). The knowledge server is invoked when the agent needs AWS security best practices or service-specific event documentation.

Skill design

The SKILL.md follows progressive disclosure:

• Initial load (~117 lines): Workflow, data source selection guide, MCP server usage, investigation type routing, defaults, and error handling
• On-demand references (4 files, all under 100 lines): Loaded only when the agent needs deep domain knowledge for a specific workflow

Workflow

1. Scope — Identify the investigation type (security incident, compliance audit, IAM analysis, change tracking) and time window
2. Investigate — Query CloudTrail events using the appropriate tool (lookup_events for recent events, lake_query for complex analytics)
3. Analyze — Correlate findings, identify patterns and anomalies
4. Report — Present structured findings with timestamps, principals, affected resources, and recommendations

Defaults

Setting	Default	How to Override
Time window	Last 24 hours	State: "check the last 7 days" or "since March 1st"
Event scope	Management events (default CloudTrail)	State: "include data events" or "check S3 object access"
Data source	lookup_events first; escalate to lake_query for aggregation or >90 days	State: "use CloudTrail Lake" or "run a SQL query"
Output format	Markdown findings table: Time / Principal / Action / Resource / Source IP / Verdict	—
Verdict markers	🔴 Malicious, ⚠️ Suspicious, ✅ Expected	—
Compliance framework	None (general audit)	State: "audit against CIS" or "check SOC 2 controls"
Lake query behavior	Check list_event_data_stores before querying; use LIMIT and eventTime filters	—

Out of scope

• Real-time alerting: This plugin queries historical events; it does not set up CloudTrail alarms or EventBridge rules
• CloudTrail configuration: The plugin does not create trails, enable logging, or modify CloudTrail settings
• Remediation: The plugin identifies issues and recommends actions but does not automatically remediate (e.g., does not disable access keys)
• Non-CloudTrail data sources: CloudWatch Logs, VPC Flow Logs, GuardDuty findings are not in scope

Potential challenges

• CloudTrail Lake availability: Not all accounts have CloudTrail Lake enabled. Mitigation: SKILL.md instructs the agent to fall back to lookup_events and suggest enabling Lake for advanced analytics.
• Event History limitations: lookup_events only covers the last 90 days of management events. Mitigation: SKILL.md documents this limitation and routes to Lake queries when longer time ranges are needed.
• Data event logging: S3 object-level and DynamoDB item-level events require explicit data event logging configuration. Mitigation: Reference files note when data events are required and suggest enabling them.
• Reference file size: Security investigation and Lake query reference files cover many patterns. Mitigation: Files load only when the relevant investigation type is detected; SKILL.md stays well under 300 lines.

Dependencies and Integrations

Dependencies (all from AWS Labs):

• awslabs.cloudtrail-mcp-server — CloudTrail event lookup and Lake analytics
• awslabs.aws-knowledge-mcp-server — AWS documentation and best practices

Integration with existing plugins:

• Complements deploy-on-aws: After deploying infrastructure, use aws-cloudtrail to audit the changes made and verify security posture

Alternative solutions

1. Service-centric model (per RFC: Plugin Granularity and Organization for awslabs/agent-plugins #56): A pure "CloudTrail tools" plugin wrapping the MCP server without workflow guidance. This would be too thin — the value is in the structured investigation playbooks, not just API access.

2. Manual MCP server setup: Users could configure awslabs.cloudtrail-mcp-server directly and write their own prompts. The plugin adds value through curated skill descriptions, progressive-disclosure reference files, and pre-built investigation workflows that guide the agent through complex security analysis tasks.