# TrailDiscover

## Overview

You can use [TrailDiscover](https://github.com/adanalvarez/TrailDiscover) as an enrichment source in Panther. TrailDiscover is a continuously evolving repository of CloudTrail events containing detailed descriptions, MITRE ATT\&CK insights, real-world incident references, research links, and information about security implications.

Learn how to [view stored enrichment data here](https://docs.panther.com/enrichment/..#viewing-and-managing-enrichments), and how to [view log events with enrichment data here](https://docs.panther.com/enrichment/..#viewing-log-events-with-enrichment-data).

## How TrailDiscover works

TrailDiscover enriches CloudTrail events with relevant information from TrailDiscover, using the log's `eventName` key. If you use [Amazon Security Lake](https://docs.panther.com/data-onboarding/supported-logs/aws/security-lake), TrailDiscover enriches the `api.operation` field, which contains the CloudTrail event name.

## Setting up TrailDiscover enrichment

{% tabs %}
{% tab title="Console" %}
**How to set up TrailDiscover enrichment in the Panther Console**

1. In the left-hand navigation bar in your Panther Console, click **Detections**.
2. Click the **Packs** tab.
3. Search for "TrailDiscover," and on the **TrailDiscover Lookup Tables** tile, click the **Enabled** toggle `ON`.
4. In the pop-up confirmation modal, click **Continue**.
5. To verify the Enrichment is enabled, from the left sidebar menu, click **Configure** > **Enrichments.**
   * On this page, you can see all enrichment sources, whether each source is currently enabled or disabled, and when a source’s data was last refreshed.
     {% endtab %}

{% tab title="CLI" %}
**How to set up TrailDiscover enrichment in the CLI workflow**

* To set up TrailDiscover in the CLI workflow, follow the instructions for Panther-managed enrichments on [Managing Lookup Tables and Enrichment Providers with the Panther Analysis Tool](https://docs.panther.com/panther-developer-workflows/detections-repo/pat/managing-enrichment). Set up in the Panther Console is not currently available.

Please note the following considerations:

* CI/CD users do not need to use Detection Packs to get TrailDiscover enrichment tables. You can pull in the latest release of [`panther-analysis`](https://github.com/panther-labs/panther-analysis) and use the `panther_analysis_tool` (PAT) to upload the TrailDiscover enrichment tables
  * To enable the TrailDiscover tables using the [`panther-analysis`](https://github.com/panther-labs/panther-analysis) repo, make sure to open each corresponding YAML configuration file and set `enabled: true`.
* It is possible for CI/CD users to enable TrailDiscover enrichment via Detection Packs, as long as you do not customize the TrailDiscover tables using PAT.
  * If you choose to manage TrailDiscover through PAT after enabling it in the Panther Console, you must first disable the Detection Packs in the Panther Console. Simultaneous use of both the Panther Console and PAT to manage TrailDiscover is not supported.
* For more information on how to manage TrailDiscover enrichment, please see the [TrailDiscover files in Panther's GitHub repository](https://github.com/panther-labs/panther-analysis/tree/main/lookup_tables/traildiscover).
  {% endtab %}
  {% endtabs %}

## Example event enriched with TrailDiscover

Below is a CloudTrail log enriched with TrailDiscover data. The `TrailDiscover` object within `p_enrichment` contains additional information about the `AssumeRole` event, such as links to associated incidents, research, and MITRE ATT\&CK tactics and techniques.

```json
{
  "awsRegion": "us-east-1",
  "correlation_rule_matches": {},
  "database_name": "panther_logs",
  "eventCategory": "Management",
  "eventID": "5d0ee1aa-cac2-3876-9808-aecdc2b720ab",
  "eventName": "AssumeRole",
  "eventSource": "sts.amazonaws.com",
  "eventTime": "2024-04-24 19:23:36.000000000",
  "eventType": "AwsApiCall",
  "eventVersion": "1.08",
  "managementEvent": true,
  "p_enrichment": {
    "TrailDiscover": {
      "eventName": {
        "awsService": "STS",
        "description": "Returns a set of temporary security credentials that you can use to access AWS resources.",
        "eventName": "AssumeRole",
        "eventSource": "sts.amazonaws.com",
        "incidents": [
          {
            "description": "The curious case of DangerDev@protonmail.me",
            "link": "https://www.invictus-ir.com/news/the-curious-case-of-dangerdev-protonmail-me"
          },
          {
            "description": "Trouble in Paradise",
            "link": "https://blog.darklab.hk/2021/07/06/trouble-in-paradise/"
          }
        ],
        "mitreAttackTactics": [
          "TA0001 - Initial Access",
          "TA0003 - Persistence",
          "TA0004 - Privilege Escalation"
        ],
        "mitreAttackTechniques": [
          "T1199 - Trusted Relationship",
          "T1078 - Valid Accounts"
        ],
        "p_match": "AssumeRole",
        "permissions": "https://aws.permissions.cloud/iam/sts#sts-AssumeRole",
        "researchLinks": [
          {
            "description": "Role Chain Juggling",
            "link": "https://hackingthe.cloud/aws/post_exploitation/role-chain-juggling/"
          },
          {
            "description": "Detecting and removing risky actions out of your IAM security policies",
            "link": "https://www.solvo.cloud/blog/detecting-and-removing-risky-actions-out-of-your-iam-security-policies/"
          }
        ],
        "securityImplications": "Attackers might use AssumeRole to gain unauthorized access to an AWS role. This might allow them to gain initial access, escalate privileges or in specific scenarios gain persistence.",
        "simulation": [
          {
            "type": "commandLine",
            "value": "aws sts assume-role --role-arn arn:aws:iam::123456789012:role/TrailDiscover --role-session-name TrailDiscover"
          }
        ],
        "usedInWild": true
      }
    }
  },
  "readOnly": true,
  "recipientAccountId": "123456789012",
  "requestID": "ddcb3c89-b762-43a1-a2b7-33f6f1afac53",
  "requestParameters": {
    "roleArn": "arn:aws:iam::123456789012:role/some-role",
    "roleSessionName": "SOME_SESSION"
  },
  "resources": [
    {
      "accountId": "123456789012",
      "arn": "arn:aws:iam::123456789012:role/some-role",
      "type": "AWS::IAM::Role"
    }
  ],
  "responseElements": {
    "assumedRoleUser": {
      "arn": "arn:aws:sts::123456789012:assumed-role/some-role/SOME_SESSION",
      "assumedRoleId": "AROASXP6SDABCDEFGL:SOME_SESSION"
    },
    "credentials": {
      "accessKeyId": "ASIASXABCDEFGRGZ",
      "expiration": "Apr 24, 2024, 8:23:36 PM",
      "sessionToken": "token"
    }
  },
  "sharedEventID": "a077320f-2184-482c-8e6d-e1e9ddfde08f",
  "sourceIPAddress": "cloudtrail.amazonaws.com",
  "table_name": "aws_cloudtrail",
  "userAgent": "cloudtrail.amazonaws.com",
  "userIdentity": {
    "invokedBy": "cloudtrail.amazonaws.com",
    "type": "AWSService"
  }
}
```