# Event Schema Reference

This page provides a complete reference for the JSON events sent by TrapEye connectors (HTTP JSON, TCP JSON, Syslog).

TrapEye sends two distinct types of events that work together to provide complete attack visibility. Events are forwarded in **real-time** as attacks occur. Each threat can have multiple associated interactions, allowing you to build a complete attack timeline.

---

## Event Types

The `event_type` field allows you to differentiate between the two event types:

| Event Value | Type | Description |
|-------------|------|-------------|
| `new_threat` | Threat Event | High-level threat actor identification based on source IP and behavioral patterns. Represents the detection of a new malicious actor. |
| `new_interaction` | Interaction Event | Detailed, granular log of an individual action taken by a threat actor. Captures specific attack techniques, targeted services, and behavioral details. Multiple interactions can be linked to a single threat via `threat_uuid`. |

---

## Threat Events

Threat events are triggered when TrapEye identifies a new malicious actor based on their source IP and behavior patterns.

### Example Threat Event

```json
{
  "@meta": {
    "product": "TrapEye",
    "schema_version": "1.0",
    "vendor": "ANANTIS"
  },
  "entity_uuid": "0e28f730-18c1-429a-821e-5282cf641dd4",
  "event_type": "new_threat",
  "first_interaction": "2026-01-23T19:23:22.149338689Z",
  "last_interaction": "2026-01-23T19:23:22.149339478Z",
  "reverse_lookup": "test-webhook-connection.local",
  "source_asn": "Private",
  "source_country": "Internal Network",
  "source_ip": "10.0.0.1",
  "threat_uuid": "00000000-0000-0000-0000-000000000000"
}
```

<DownloadJsonButton filename="trapeye-threat-schema.json" />

### Threat Event Fields

| Field | Type | Description |
|-------|------|-------------|
| `@meta` | Object (JSON) | Metadata object containing `vendor` ("ANANTIS"), `product` ("TrapEye"), and `schema_version` for event format versioning. |
| `entity_uuid` | String (UUID) | UUID of the tenant where the device is installed. |
| `event_type` | String | Event type identifier. Always `"new_threat"` for threat events. |
| `first_interaction` | String (RFC 3339) | Timestamp of the first interaction from this threat actor. |
| `last_interaction` | String (RFC 3339) | Timestamp of the most recent interaction from this threat actor. |
| `reverse_lookup` | String | Reverse DNS lookup result for the source IP. |
| `source_asn` | String | Autonomous System Number (ASN) of the source IP. Shows `"Private"` for internal networks. |
| `source_country` | String | Geographic country associated with the source IP. May show `"Internal Network"` for private IPs. |
| `source_ip` | String | IP address of the malicious actor. |
| `threat_uuid` | String (UUID) | Unique identifier for this specific threat. Used to correlate related interactions. |

### Threat Lifecycle

The `threat_uuid` is tied to both the source IP and the threat status in the TrapEye console:

- When a new source IP is detected, a new threat is created with a unique `threat_uuid`
- All subsequent interactions from this IP are linked to the same `threat_uuid`
- **If analysts close the threat in the console** and the same source IP later resumes activity, a **new threat** will be created with a **different `threat_uuid`**

This behavior allows security teams to track distinct attack campaigns from the same source IP over time.

---

## Interaction Events

Interaction events provide detailed information about each individual action taken by a threat actor against your traps.

### Example Interaction Event

```json
{
  "@meta": {
    "product": "TrapEye",
    "schema_version": "1.0",
    "vendor": "ANANTIS"
  },
  "additional_data": {
    "message": "Test webhook connection",
    "test": true
  },
  "description": "Port scanning activity detected on SSH service",
  "destination_ports": [22],
  "entity_uuid": "0e28f730-18c1-429a-821e-5282cf641dd4",
  "event_type": "new_interaction",
  "impacted_service": "ssh",
  "interaction_type": "port_scan",
  "mitre_id": "T1046",
  "reverse_lookup": "test-webhook-connection.local",
  "severity": 3,
  "source_asn": "Private",
  "source_country": "Internal Network",
  "source_ip": "10.0.0.1",
  "threat_uuid": "00000000-0000-0000-0000-000000000000",
  "timestamp": "2026-01-23T19:23:22.438164520Z",
  "trapeye_hostname": "",
  "trapeye_name": "My TrapEye",
  "trapeye_uuid": "00000000-0000-0000-0000-000000000000"
}
```

<DownloadJsonButton filename="trapeye-interaction-schema.json" />

### Interaction Event Fields

| Field | Type | Description |
|-------|------|-------------|
| `@meta` | Object (JSON) | Metadata object containing `vendor` ("ANANTIS"), `product` ("TrapEye"), and `schema_version` for event format versioning. |
| `additional_data` | Object (JSON) | Free-form JSON object containing rich attack context: device/browser fingerprints, authentication attempts, executed commands. **Note:** Sensitive data such as passwords are never included. |
| `description` | String | Human-readable description of the interaction activity. |
| `destination_ports` | Array of Integers | List of destination ports targeted during the interaction. |
| `entity_uuid` | String (UUID) | UUID of the tenant where the device is installed. |
| `event_type` | String | Event type identifier. Always `"new_interaction"` for interaction events. |
| `impacted_service` | String | The service or protocol targeted by the attacker (e.g., `ssh`, `http`, `rdp`). |
| `interaction_type` | String | Type of interaction detected (e.g., `port_scan`, `brute_force`). |
| `mitre_id` | String | MITRE ATT&CK technique identifier associated with this interaction (e.g., `T1046` for Network Service Discovery). |
| `reverse_lookup` | String | Reverse DNS lookup result for the source IP. |
| `severity` | Integer | Severity level of the interaction on a scale from 1 (low) to 10 (critical). |
| `source_asn` | String | Autonomous System Number (ASN) of the source IP. Shows `"Private"` for internal networks. |
| `source_country` | String | Geographic country associated with the source IP. May show `"Internal Network"` for private IPs. |
| `source_ip` | String | IP address of the attacker performing the interaction. |
| `threat_uuid` | String (UUID) | Unique identifier for the threat actor. Used to correlate this interaction with its parent threat event. |
| `timestamp` | String (RFC 3339) | Exact timestamp when the interaction occurred. |
| `trapeye_hostname` | String | Hostname of the TrapEye decoy. |
| `trapeye_name` | String | Name of the TrapEye decoy configured in the interface. |
| `trapeye_uuid` | String (UUID) | UUID of the TrapEye device that detected this interaction. |

---

## Correlation

Use the `threat_uuid` field to correlate interaction events with their parent threat:

- Each **threat** has a unique `threat_uuid`
- All **interactions** from the same threat actor share the same `threat_uuid`
- This allows you to group interactions by threat actor for analysis

---

## Testing Events

When you use the **Test Connection** button in TrapEye, a test event is sent with default values.

**Tip:** Test events use the **exact same JSON structure** as production events, making them ideal for:

- Validating connector connectivity
- Testing parsing rules and field extraction
- Developing correlation logic
- Configuring SOAR playbooks

---

## Best Practices

1. **Use the `event_type` field** as the primary discriminator to route threats and interactions to appropriate handlers
2. **Correlate by `threat_uuid`** to build complete attack timelines
3. **Enrich with `source_ip`** lookups for additional threat intelligence context
4. **Map `mitre_id`** to your threat matrix for standardized attack classification

---

## Support

If you need additional fields or have questions about TrapEye event structures, you can contact us: support@anantis.io.