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 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

{
  "entity_uuid": "0e28f730-18c1-429a-821e-5282cf641dd4",
  "event": "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"
}

Threat Event Fields

Field	Type	Description
`entity_uuid`	String (UUID)	UUID of the tenant where the device is installed.
`event`	String	Event type identifier. Always `"new_threat"` for threat events.
`first_interaction`	String (ISO 8601)	Timestamp of the first interaction from this threat actor.
`last_interaction`	String (ISO 8601)	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

{
  "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": "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_uuid": "00000000-0000-0000-0000-000000000000"
}

Interaction Event Fields

Field	Type	Description
`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`	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 (ISO 8601)	Exact timestamp when the interaction occurred.
`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.

Best Practices

Use the event field as the primary discriminator to route threats and interactions to appropriate handlers
Correlate by threat_uuid to build complete attack timelines
Enrich with source_ip lookups for additional threat intelligence context
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.