Endpoint Event Schema

Beacon endpoint JSONL fields and normalization behavior

Endpoint Event Schema

Beacon endpoint events are JSONL records with a stable schema contract. The schema is designed for local inspection, Wazuh localfile ingestion, and customer-managed forwarding pipelines.

Normalization

Beacon normalizes different runtime signals into the same endpoint contract. The collector exporter looks for common OTLP attributes such as gen_ai.request.model, gen_ai.tool.name, mcp.tool.name, process.command_line, file.path, conversation.id, vcs.repository.url, and git.branch. Hook telemetry builds the same fields directly from hook payloads.

When a runtime does not provide an explicit Beacon action, Beacon infers one from the signal. Prompt-like events become prompt.submitted, shell or exec events become command.executed, MCP events become mcp.tool_invoked, file/write/edit events become file.modified, approval events become approval.requested, and other tool activity becomes tool.invoked.

When a runtime omits event.category, Beacon infers it from event.action. For example, prompt.* becomes prompt, command.* becomes command, file.* becomes file, mcp.* becomes mcp, approval.* and policy.* become approval, metric.* becomes metric, and tool.* becomes tool.

Required fields

Field	Meaning
timestamp	UTC event time
vendor	Always beacon
product	Always endpoint-agent
schema_version	Current public schema version, 1.0
event.kind	Event family, currently agent_runtime
event.action	Normalized action such as command.executed or tool.invoked
event.category	Event category, provided by the runtime or inferred from event.action when possible
severity	info, low, medium, high, or critical
endpoint	Host and operating system context
harness	Runtime that produced the signal

Entity model

Beacon models each endpoint event as an action plus a set of typed entities. The event object describes what happened, while the surrounding objects describe who or what participated in that action.

Entity	Purpose	Common fields
endpoint	Device and agent context for the machine where telemetry was collected	hostname, os, agent_version
user	Local operating system user context	name, uid
harness	AI runtime or integration that produced the signal	name, version, executable_path, config_path
session	Conversation or runtime session context	id, working_directory
tool	Tool invocation context, including shell-like tools	name, command, path
file	File activity context	path, operation, language, diff_hash, diff_bytes
command	Shell or process execution context	command, exit_code, duration_ms
mcp	MCP-like server and tool context	server, tool
approval	Approval or policy decision context	required, decision, reason
policy	Policy metadata when available from a runtime or integration	id, name, decision, enforcement, reason
prompt	Prompt text when content retention allows it	text
content	Content-retention state for the event	retention, included, redacted, truncated
destination	Output or validation destination state	type, mode, status
health	Endpoint or component health state	component, status, reason

Top-level model, repository, branch, message, raw, and field_truncated fields add shared context that can apply across multiple entities. For example, a command event can include both tool and command; a file edit can include file, session, repository, and branch; and a validation event can include destination.

Optional context

Optional context fields add detail when available:

• user: local user metadata
• session: conversation or runtime session metadata
• tool: tool name, command, or path metadata
• file: file path, operation, language, diff hash, or diff byte counts
• command: shell command, exit code, or duration metadata
• mcp: MCP-like server and tool metadata
• approval: approval requirement, decision, or reason
• policy: policy ID, name, decision, enforcement mode, or reason
• content: content retention mode and inclusion/redaction state
• destination: output destination state, such as Wazuh localfile validation
• health: component health status
• model, repository, branch, message, raw, and field_truncated: additional runtime context and truncation metadata

Example command event

{
  "timestamp": "2026-05-11T22:21:00Z",
  "vendor": "beacon",
  "product": "endpoint-agent",
  "schema_version": "1.0",
  "event": {
    "kind": "agent_runtime",
    "action": "command.executed",
    "category": "command"
  },
  "severity": "info",
  "endpoint": {
    "hostname": "example-mac",
    "os": "darwin",
    "agent_version": "0.0.4"
  },
  "user": {
    "name": "local-user"
  },
  "harness": {
    "name": "cursor"
  },
  "session": {
    "id": "conversation-1",
    "working_directory": "/Users/local-user/repo"
  },
  "tool": {
    "name": "Shell",
    "command": "go test ./..."
  },
  "command": {
    "command": "go test ./..."
  },
  "content": {
    "retention": "metadata",
    "included": false
  },
  "message": "Shell command executed"
}

Privacy and retention fields

Beacon records configured content fields by default. Content retention is configurable with --content-retention full, --content-retention redacted, or --content-retention metadata.

• full: default; includes configured content fields in local or customer-controlled logs, still subject to event size limits
• redacted: includes configured content fields after local redaction and size limits
• metadata: excludes prompt text, raw attributes, command output, and raw diffs

Beacon also caps event size, redacts common secret patterns, and marks events with field_truncated when fields must be shortened before writing.

For Codex CLI, Beacon also filters noisy internal transport spans before writing endpoint events. The schema remains the same; the filter reduces low-signal trace records rather than changing event fields.

Related

Beacon architecture

See how runtime telemetry becomes normalized JSONL.

Wazuh

Configure Wazuh ingestion for Beacon endpoint events.