# Open Threat Exchange (OTX) (Beta)
## Overview
{% hint style="info" %}
OTX enrichment is in open beta starting with Panther version 1.116, and is available to all customers. Please share any bug reports and feature requests with your Panther support team.
{% endhint %}
[Open Threat Exchange (OTX)](https://otx.alienvault.com/) is AlienVault's community-driven threat intelligence platform, where contributors collaborate to identify emerging threats.
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).
{% hint style="warning" %}
OTX enrichment in Panther requires an OTX API key.
{% endhint %}
## How OTX enrichment works in Panther
By default, OTX is configured to run against every log source in your Panther environment ([yet is possible to disable for a log type, if desired](#enabling-disabling-or-modifying-otx-enrichment-for-a-log-type)). Panther will attempt to match each incoming log event, across all log types, against the OTX Panther-managed enrichment before it passes through the detection engine.
If Panther [identifies a match](#how-a-match-between-a-log-event-and-otx-is-made) between an incoming event and OTX entry, OTX data is appended to the matching log event under a top-level `p_enrichment` key. It can then be referenced in detection logic and searches.
For more information on detection writing using an enrichment source, see [Writing a detection using custom enrichment data](https://docs.panther.com/custom#writing-a-detection-using-custom-enrichment-data).
### How a match between a log event and OTX is made
A log event is enriched with OTX Panther-managed enrichment data (under `p_enrichment`) if a match is found between:
* Any of the values of the Selector field(s) configured for each associated log type.
* For each log type, the default Selectors are the [Indicator Fields](https://docs.panther.com/search/panther-fields#indicator-fields) (represented by `p_any_*`) associated with the enrichment table's primary key's indicator field designations (though the Selectors are configurable). [Learn more about this auto-mapping here](https://docs.panther.com/custom#option-2-let-log-types-and-selectors-be-automatically-mapped-by-indicator-fields).
* The value of the `indicator` key in an OTX table entry in Panther.
* `indicator` is the primary key of the OTX table and contains the indicator value (IP address, domain, file hash, etc.).
* See an example of `indicator` in the [Example OTX table entry](#example-otx-enrichment-table-entry) below.
## Setting up OTX enrichment
### Step 1: Retrieve an OTX API key
1. Log in to your [OTX](https://otx.alienvault.com/) account.
2. In the upper-right corner, click your username, then **Settings**.\
3. From the **OTX Key** section, copy the API key you'd like to use to fetch data in Panther.
* If you rotate or regenerate the API key in the future, you must update the configuration in Panther.
### Step 2: Create the OTX enrichment in Panther
To configure OTX enrichment in Panther:
1. In the left-hand navigation bar of your Panther Console, click **Configure** > **Enrichments**.
2. In the upper-right corner, click **Create New**.
3. Click **Open Threat Exchange**.\
4. In the **OTX Enrichment Settings** form, provide values for the following fields:
* **Name**: enter a descriptive name for your integration.
* **API Token**: enter the API token you retrieved in Step 1.
* **Refresh period (minutes)**: configure how often Panther will refresh OTX data. The default refresh period is 360 minutes.
* **Max age (days)**: configure the maximum age in days for pulses to include in the lookup table. Default is 365 days.
5. Click **Setup**.
* Your new OTX configuration will be visible in the **Configure** > **Enrichments** page.
{% hint style="info" %}
Your new OTX enrichment will show as being in a healthy state, with zero entries, for \~10 minutes. During this time, the first data pull is being performed.
.png?alt=media)
{% endhint %}
## Enabling, disabling, or modifying OTX enrichment for a log type
OTX enrichment is enabled by default for each log type in your Panther instance.
If you'd like to disable (or later enable) OTX enrichment for a certain log type, or alter a log type's selectors:
1. In the left-hand navigation bar in your Panther Console, click **Configure** > **Enrichments**.
2. In the list of Enrichments, locate the OTX source you'd like to modify, and click its name.
3. On the provider's details page, to the right of the **Enriched Log Types** header, click **Edit**.
* If you'd like to enable this enrichment for a new log type, click **Add Log Type**.
* In the new row that populates, select a **Log Type** and, in the **Selectors** field, at least one event field.
* If you'd like to disable this enrichment for a log type, locate that log type's row, and click the trash icon.
* If you'd like to alter the selectors for a log type, click into the **Selectors** field and add or remove selections for event fields.
4. In the upper-right corner of the **Enriched Log Types** tile, click **Save**.
## Example OTX enrichment table entry
The below is an example of an OTX pulse response normalized by Panther. Each `indicator` from the pulse creates its own row.
```json
{
"id": "507f1f77bcf86cd799439011",
"name": "Malicious Domain Activity",
"description": "Indicators related to malicious domain activity",
"created": "2023-08-15T10:30:00Z",
"modified": "2023-08-15T10:30:00Z",
"tags": ["malware", "domain", "c2"],
"industries": ["financial"],
"malware_families": ["trojan", "backdoor"],
"references": ["https://example.com/threat-report"],
"attack_ids": ["T1016", "T1059", "T1071"],
"indicator": "malicious-domain.com",
"indicator_type": "domain",
"indicator_created": "2023-08-15T10:30:00Z",
"indicator_expiration": "2024-08-15T10:30:00Z",
"tlp": "white",
"adversary": "APT29",
"target_countries": ["US", "UK"],
"p_event_time": "2023-08-15T10:30:00Z",
"p_log_type": "OTX.Pulses",
"p_parse_time": "2023-08-15T11:00:00Z",
"p_row_id": "abc123def456ghi789",
"p_schema_version": 0
}
```
## OTX data structure
Pulses
An OTX pulse represents threat intelligence indicators related to a specific threat or campaign. In Panther, each indicator from a pulse becomes its own row in the enrichment, combined with the pulse metadata. Each row contains the following attributes:
**Pulse Metadata (shared across all indicators from the same pulse)**:
* `id`: a unique identifier for the pulse
* `name`: the name/title of the pulse
* `description`: a description of the threat intelligence contained in the pulse
* `created`: a timestamp of when the pulse was originally created
* `modified`: an optional timestamp indicating when the pulse was last modified
* `tags`: categorization tags applied to the pulse
* `industries`: target industries affected by the threats in this pulse
* `malware_families`: malware families associated with the threats
* `references`: external references, URLs, or citations related to the threat intelligence
* `attack_ids`: MITRE ATT\&CK technique IDs mapped to the threat
* `tlp`: Traffic Light Protocol (TLP) classification for information sharing
* `adversary`: the threat actor or adversary group associated with the pulse
* `target_countries`: countries targeted by the threats in this pulse
**Indicator-Specific Fields (unique per row)**:
* `indicator`: the indicator value (IP address, domain name, file hash, URL, etc.), this is the primary key
* `indicator_type`: the type of indicator (e.g., 'IPv4', 'domain', 'hostname', 'email', 'URL', 'FileHash-MD5', 'FileHash-SHA256')
* `indicator_created`: the timestamp when the indicator was created
* `indicator_expiration`: the timestamp when the indicator expires or becomes invalid (optional)
See the complete [OTX.Pulses](#otx.pulses-schema) schema below.
### `OTX.Pulses` schema
The following is the Panther-managed `OTX.Pulses` schema, representing how Pulses are stored in Panther. Each indicator from a pulse becomes its own row with embedded pulse metadata.
```yaml
schema: OTX.Pulses
description: Open Threat Exchange (OTX) pulses containing threat intelligence indicators and metadata
referenceURL: https://otx.alienvault.com
fields:
- name: id
required: true
description: The unique identifier for the pulse.
type: string
- name: name
required: true
description: The title or name of the pulse describing the threat.
type: string
- name: description
description: The detailed description of the threat, campaign, or security event.
type: string
- name: created
required: true
description: The timestamp when the pulse was created.
type: timestamp
timeFormats:
- '%Y-%m-%dT%H:%M:%S.%N'
- '%Y-%m-%dT%H:%M:%S'
isEventTime: true
- name: modified
description: The timestamp when the pulse was last modified.
type: timestamp
timeFormats:
- '%Y-%m-%dT%H:%M:%S.%N'
- '%Y-%m-%dT%H:%M:%S'
- name: tags
description: Keywords or labels associated with the pulse for categorization and filtering.
type: array
element:
type: string
- name: industries
description: Industry sectors targeted by the threat described in the pulse.
type: array
element:
type: string
- name: malware_families
description: Malware families associated with the threat described in the pulse.
type: array
element:
type: string
- name: references
description: URLs to external sources, reports, or articles related to the pulse.
type: array
element:
type: string
- name: tlp
description: Traffic Light Protocol classification indicating information sharing restrictions.
type: string
- name: adversary
description: Name or identifier of the threat actor, group, or adversary associated with the pulse.
type: string
- name: target_countries
description: Countries or regions targeted by the threat described in the pulse.
type: array
element:
type: string
- name: attack_ids
description: MITRE ATT&CK technique IDs (e.g., T1016, T1059) mapped to the threat.
type: array
element:
type: string
indicators:
- mitre_attack_technique
- name: indicator
required: true
description: The actual indicator value (e.g., IP address, domain name, file hash, URL).
type: string
indicators:
- ip
- domain
- md5
- sha1
- sha256
- email
- cve
- name: indicator_type
description: The type of indicator (e.g., 'IPv4', 'domain', 'hostname', 'email', 'URL', 'FileHash-MD5', 'FileHash-SHA256').
type: string
- name: indicator_created
description: The timestamp when the indicator was created.
type: timestamp
timeFormats:
- '%Y-%m-%dT%H:%M:%S'
- name: indicator_expiration
description: The timestamp when the indicator expires or becomes invalid.
type: timestamp
timeFormats:
- '%Y-%m-%dT%H:%M:%S'
```