TrailDiscover

Why This Project Exists

I started TrailDiscover because I often wondered if certain AWS commands had been used in past cyber attacks and what information was available about them. Since most API actions create a CloudTrail event with the same name, I decided to focus on CloudTrail events, also because aproaching it this way might help using this information with SIEMs. This project is about making it easier to understand which AWS actions have been misused before, how others might be misused and the event they generate. I hope this helps people decide what to watch out for, speed up figuring out what happened in an attack, and inspire new security research.

Website

The easiest way to consume this information is via the website: https://traildiscover.cloud/

• Events: search and filter every event, and open one to see its details, sources and example log.
• Insights: the public incident sources behind the evidence, the MITRE ATT&CK techniques the events map to (also as an ATT&CK Navigator layer), and the AWS services involved.

What's in the Project

Here's what you'll find in TrailDiscover:

• Events Folder: This is the main folder, here each AWS service has its own folder and inside you will find a JSON file for each event, like CloudTrail/DeleteTrail.json or Cognito/GetCredentialsForIdentity.json.
• Docs Folder: This folder contains a website where you can search through the events easily. You can access the website via: https://traildiscover.cloud/
• Tools Folder: Contains build.py, a single pipeline that formats events, redacts CloudTrail logs, copies log examples to docs, and generates the files the website uses (events.json, events.csv, datadog_dashboard.json, and the ATT&CK files for the Insights page). updateAttackLookup.py refreshes the pinned MITRE ATT&CK data in tools/attack/; it is only needed when moving to a new ATT&CK version. Additional helper scripts are included for Grimoire log retrieval, Sigma rule matching, and security implication generation.

How Events Are Structured

Each event in the json files contains:

• The name of the event (like "CreateKeyPair").
• The event source that will appear in CloudTrail (such as "ec2.amazonaws.com").
• The AWS service it's part of (for example, "EC2").
• A description of what the API call related to the event does (Almost all descriptions come from AWS official documentation).
• MITRE ATT&CK tactics and techniques that might relate to the event.
• Whether we have evidence (and there is a link to it) that the call related to the event has been used in real attacks before.
• Links to incidents and research about the call related to the event.
• A note on what security implications might come with the event (Some of them are generated with OpenAI, but I've tried to review them).

Heads Up

This is just the start, and there's a lot of manual work behind it, so there might be mistakes. The way I've mapped events to MITRE ATT&CK tactics and techniques is my best guess, based on how these commands work and what's been seen in attacks, but there are many ways to look at it.

How to Contribute

PRs are welcome. Here’s how you can contribute:

Adding New Events: You can contribute by adding new event files to the events folder within the respective service directory. Make sure to include all the relevant details as described in the event structure section.

Update Event Details: Add any new findings or details that can provide a better understanding of the event's implications, use in real-world attacks, or links to researchs where the event is mentioned. When the same incident report applies to several events, use the same URL and title in each, so the Insights page counts it as one source.

Updating The Web: After adding or updating events, run python3 build.py from the tools folder to format, redact, and generate all output files. This ensures that the website stays up-to-date with the latest event information.

MCP Server

TrailDiscover is available as an MCP (Model Context Protocol) server, allowing AI assistants to query the CloudTrail security events database directly.

Endpoint: https://mcp.traildiscover.cloud/mcp

VS Code / GitHub Copilot

Add to your .vscode/mcp.json:

{
  "servers": {
    "traildiscover": {
      "type": "http",
      "url": "https://mcp.traildiscover.cloud/mcp"
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "traildiscover": {
      "type": "streamable-http",
      "url": "https://mcp.traildiscover.cloud/mcp"
    }
  }
}

Available Tools

Datadog Dashboard

Run python3 build.py from the tools folder to generate all output files including datadog_dashboard.json in the docs folder. This JSON can be imported into Datadog as a dashboard.

The dashboard has an overview section with a 'Top 10 CloudTrail Events exploited in the wild' showcasing the top 10 events happening in the account/s that are known to be used in the wild by attackers. Additionally, it includes a 'MITRE ATT&CK Tactics Events Timeline' that groups events from TrailDiscover into MITRE ATT&CK Tactics and shows when they are happening in our account/s.

Then, events are organized according to MITRE ATT&CK tactics. Each event is presented with two widgets: one provides a description, a direct link to traildiscover.cloud, and references to related incidents and research; the other features a counter displaying the frequency of these events in your AWS environment.

⚠️ Warning

This dashboard is resource-intensive. If you want to generate a dashboard with fewer data it is possible to use the options --on-the-wild-only to only add events that have been seen in the wild, or the --tactics option to only add specific tactics. Example usage: python3 build.py --on-the-wild-only --tactics "TA0005 - Defense Evasion" "TA0008 - Lateral Movement"

Plans for the Future

• Adding More Events: I'll keep adding new events and updating the info for existing ones.
• Adding New Alerts: Map the current events with third-party alerts.