Overview
The schema reference below is generated from JSON Schema files under schemas/. These files cover audit events, scan events, scan findings, activity events, gateway event envelopes, network egress events, scan results, and OpenTelemetry-facing event contracts.
Runtime shapes
The gateway handlers in internal/gateway/api.go and internal/gateway/proxy.go also return small JSON responses that are defined in Go rather than JSON Schema files.
| Shape | Source | Where it appears |
|---|---|---|
| Sidecar status map | internal/gateway/api.go::handleStatus | GET /status |
| Guardrail runtime config map | internal/gateway/api.go::handleGuardrailConfig | GET and PATCH /v1/guardrail/config |
| Provider list response | internal/gateway/providers_endpoint.go::providersListResponse | GET /v1/config/providers on the proxy |
| Egress ingestion payload | schemas/network-egress-event.json plus internal/gateway/egress.go validation | POST /v1/events/egress on the proxy |
Autogenerated reference
The tables below are rebuilt by make docs-gen from the JSON Schemas under schemas/. Do not edit between the BEGIN AUTOGEN / END AUTOGEN sentinels.
Audit event
DefenseClaw Audit Event
Row persisted in audit_events (SQLite) and forwarded to Splunk/HTTP sinks. v7 adds provenance (SchemaVersion=7) + three-tier agent identity. Consumers MUST treat every field marked optional as nullable — not every action emits every field.
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | |
timestamp | string (date-time) | yes | |
action | enum (init, stop, ready, scan, scan-start, rescan, rescan-start, block, allow, warn, quarantine, restore, disable, enable, deploy, drift, network-egress-blocked, network-egress-allowed, guardrail-block, guardrail-warn, guardrail-allow, approval-request, approval-granted, approval-denied, tool-call, tool-result, config-update, policy-update, policy-reload, action, acknowledge-alerts, dismiss-alerts, webhook-delivered, webhook-failed, sink-failure, sink-restored, alert) | yes | Curated action — see internal/audit/actions.go (Go) and cli/defenseclaw/audit_actions.py (Python). Extending this enum is a minor schema bump. |
target | string \| null | no | Target of the action (skill id, mcp server id, policy id, etc). Nullable — lifecycle events like 'init' and 'ready' have no target. |
actor | string | yes | Who caused the action. Format: '<subsystem>:<principal>' (e.g. 'cli:alice', 'scanner:skill', 'system'). |
details | string \| null | no | Redacted free-form detail blob. JSON-encoded payload after sanitizer. Treat as opaque. |
severity | enum (CRITICAL, HIGH, MEDIUM, LOW, INFO, WARN) | no | |
run_id | string \| null | no | |
session_id | string \| null | no | |
trace_id | string \| null | no | |
span_id | string \| null | no | |
agent_id | string \| null | no | Stable agent identity across process restarts. |
agent_name | string \| null | no | Human-readable agent name. |
agent_instance_id | string \| null | no | Per-session agent identity — rotates on new session. |
sidecar_instance_id | string \| null | no | Per-process sidecar identity — rotates on every defenseclaw gateway start. |
destination_app | string \| null | no | Tool provider / downstream app. Optional. |
tool_name | string \| null | no | |
tool_id | string \| null | no | |
policy_id | string \| null | no | |
schema_version | integer | yes | Audit row format version. v7 = provenance + three-tier agent identity. Downstream MUST reject unrecognized versions. |
content_hash | string \| null | no | SHA-256 hex of the canonical JSON serialization of the emitting config / policy at emit time. Optional; present when the event describes a configurable surface. |
generation | integer \| null | no | Monotonic counter incremented on every Save of the governing config/policy. Optional. |
binary_version | string \| null | no | Semver of the DefenseClaw binary that produced the event. |
Scan event
DefenseClaw Scan Event Payload (v7)
Populates the scan sub-object on a gateway-event-envelope when event_type="scan". Summarises one scanner invocation — findings are fanned out as sibling EventScanFinding events sharing the same scan_id.
Definitions
ScanPayload
| Field | Type | Required | Description |
|---|---|---|---|
scan_id | string | yes | Correlation id shared by the roll-up EventScan and all child EventScanFinding events. |
scanner | enum (skill, mcp, plugin, aibom, codeguard) | yes | |
target | string | yes | File path | skill name | server URL. Redacted when scanner contract requires. |
target_type | enum (file, skill, mcp, plugin, aibom, None) | no | |
verdict | enum (clean, warn, block, None) | no | |
duration_ms | integer \| null | no | |
severity_max | enum (CRITICAL, HIGH, MEDIUM, LOW, INFO, None) | no | |
counts | object \| null | no | Severity -> count. Keys are a subset of severity_max enum. |
total_count | integer \| null | no | |
exit_code | integer \| null | no | |
error | string \| null | no | Scanner execution error. Present only when the wrapper failed (timeout, non-zero exit). |
Scan finding event
DefenseClaw Scan Finding Event Payload (v7)
Populates the scan_finding sub-object on a gateway-event-envelope when event_type="scan_finding". One emission per scanner finding; downstream SIEM can alert on a single critical finding without joining against the parent EventScan summary.
Definitions
ScanFindingPayload
| Field | Type | Required | Description |
|---|---|---|---|
scan_id | string | yes | |
scanner | enum (skill, mcp, plugin, aibom, codeguard) | yes | |
target | string | yes | |
finding_id | string \| null | no | |
rule_id | string \| null | no | Stable detection rule identifier. Preferred group-by for SIEM; never display-string. |
category | string \| null | no | |
title | string \| null | no | |
description | string \| null | no | Always redacted. |
severity | enum (CRITICAL, HIGH, MEDIUM, LOW, INFO, None) | no | |
location | string \| null | no | Redacted path + line. |
line_number | integer \| null | no | |
remediation | string \| null | no | |
tags | array \| null | no |
Activity event
DefenseClaw Activity Event Payload (v7)
Populates the activity sub-object on a gateway-event-envelope when event_type="activity". Records operator-facing mutations: config save, policy reload, block/allow list update, skill approval, sink reconfiguration. Carries before/after snapshots plus a structured diff so compliance auditors can reconstruct every change without scraping CLI output.
Definitions
ActivityPayload
| Field | Type | Required | Description |
|---|---|---|---|
actor | string | yes | Principal who made the change. Format: '<subsystem>:<principal>'. |
action | enum (config-update, policy-update, policy-reload, block, allow, quarantine, restore, disable, enable, action, acknowledge-alerts, dismiss-alerts, deploy, stop) | yes | Mirrors audit.Action. Subset applicable to operator mutations. |
target_type | enum (policy, skill, mcp, config, action, sink, alert, plugin) | yes | |
target_id | string | yes | |
reason | string \| null | no | Operator-supplied free text. |
before | object \| null | no | Compact snapshot of resource before change. null on create. |
after | object \| null | no | Compact snapshot of resource after change. null on delete. |
diff | array \| null | no | |
version_from | string \| null | no | Content hash / semver of resource before change. |
version_to | string \| null | no | Content hash / semver of resource after change. |
DiffEntry
| Field | Type | Required | Description |
|---|---|---|---|
path | string | yes | JSON pointer / dotted path. Array indices rendered as 'field[n]'. |
op | enum (add, remove, replace) | yes | |
before | no | Present for replace + remove. Redacted if sensitive. | |
after | no | Present for add + replace. Redacted if sensitive. |
Gateway event envelope
DefenseClaw Gateway Event Envelope (v7)
One JSONL line emitted by the DefenseClaw gateway sidecar to gateway.jsonl / stderr / HTTP sinks. The envelope carries correlation + provenance; exactly one of the type-specific payload sub-objects (verdict, judge, lifecycle, error, diagnostic, scan, scan_finding, activity) is populated and selected by event_type.
| Field | Type | Required | Description |
|---|---|---|---|
ts | string (date-time) | yes | |
event_type | enum (verdict, judge, lifecycle, error, diagnostic, scan, scan_finding, activity, egress) | yes | |
severity | enum (INFO, LOW, MEDIUM, HIGH, CRITICAL, WARN) | yes | |
schema_version | integer | yes | |
content_hash | string \| null | no | |
generation | integer \| null | no | |
binary_version | string \| null | no | |
run_id | string \| null | no | |
request_id | string \| null | no | |
session_id | string \| null | no | |
trace_id | string \| null | no | |
provider | string \| null | no | |
model | string \| null | no | |
direction | enum (prompt, completion, tool_call, None) | no | |
agent_id | string \| null | no | |
agent_name | string \| null | no | |
agent_instance_id | string \| null | no | |
sidecar_instance_id | string \| null | no | |
policy_id | string \| null | no | |
destination_app | string \| null | no | |
tool_name | string \| null | no | |
tool_id | string \| null | no | |
tenant_id | string \| null | no | RESERVED (v7): logical tenancy boundary for hosted/SaaS deployments. Unpopulated until a matching producer ships. |
workspace_id | string \| null | no | RESERVED (v7): sub-tenant workspace/organization/team scope. Unpopulated until a matching producer ships. |
environment | string \| null | no | RESERVED (v7): deployment environment (dev|staging|prod|sandbox). Unpopulated until a matching producer ships. |
deployment_mode | string \| null | no | RESERVED (v7): sidecar deployment mode (standalone|managed|edge|ci). Unpopulated until a matching producer ships. |
discovery_source | string \| null | no | RESERVED (v7): how the monitored agent/tool was discovered (registry|manual|scan|import). Unpopulated until a matching producer ships. |
verdict | #/$defs/VerdictPayload | no | |
judge | #/$defs/JudgePayload | no | |
lifecycle | #/$defs/LifecyclePayload | no | |
error | #/$defs/ErrorPayload | no | |
diagnostic | #/$defs/DiagnosticPayload | no | |
scan | https://defenseclaw.io/schemas/scan-event.json#/$defs/ScanPayload | no | |
scan_finding | https://defenseclaw.io/schemas/scan-finding-event.json#/$defs/ScanFindingPayload | no | |
activity | https://defenseclaw.io/schemas/activity-event.json#/$defs/ActivityPayload | no | |
egress | #/$defs/EgressPayload | no |
Variants (oneOf)
- Variant 1:
- Variant 2:
- Variant 3:
- Variant 4:
- Variant 5:
- Variant 6:
- Variant 7:
- Variant 8:
- Variant 9:
Definitions
VerdictPayload
| Field | Type | Required | Description |
|---|---|---|---|
stage | enum (regex, judge, cisco_ai_defense, opa, final, session_message, multi_turn, block_list, approval) | yes | |
action | enum (allow, warn, block) | yes | |
reason | string \| null | no | |
categories | array \| null | no | |
latency_ms | integer \| null | no |
JudgePayload
| Field | Type | Required | Description |
|---|---|---|---|
kind | string | yes | |
model | string | yes | |
input_bytes | integer | yes | |
latency_ms | integer | yes | |
action | string \| null | no | |
severity | string \| null | no | |
findings | array \| null | no | |
raw_response | string \| null | no | |
parse_error | string \| null | no |
LifecyclePayload
| Field | Type | Required | Description |
|---|---|---|---|
subsystem | string | yes | |
transition | enum (start, stop, ready, degraded, restored, alert, completed) | yes | |
details | object \| null | no |
ErrorPayload
| Field | Type | Required | Description |
|---|---|---|---|
subsystem | string | yes | |
code | string \| null | no | |
message | string | yes | |
cause | string \| null | no |
DiagnosticPayload
| Field | Type | Required | Description |
|---|---|---|---|
component | string | yes | |
message | string | yes | |
fields | object \| null | no |
EgressPayload
| Field | Type | Required | Description |
|---|---|---|---|
target_host | string \| null | no | |
target_path | string \| null | no | |
body_shape | enum (``, none, messages, prompt, input, contents, unknown, None) | no | |
looks_like_llm | boolean \| null | no | |
branch | enum (known, shape, passthrough) | yes | |
decision | enum (allow, block) | yes | |
reason | string \| null | no | |
source | enum (go, ts) | yes |
Network egress event
NetworkEgressEvent
A single outbound network call observed by the agent runtime, with policy decision fields stored as first-class structured data.
| Field | Type | Required | Description |
|---|---|---|---|
timestamp | string (date-time) | no | When the call was observed (RFC3339). Defaults to the ingestion time when omitted. |
session_id | string | no | Agent session identifier. Correlates this event with tool_call/tool_result rows for the same session. |
hostname | string | yes | Destination hostname without port (e.g. 'api.example.com'). |
url | string | no | Full destination URL. Stored at most 512 characters. |
http_method | enum (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) | no | HTTP verb (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS). |
protocol | enum (http, https) | no | Transport protocol. |
policy_outcome | string | yes | Human-readable summary of the policy decision. |
decision_code | string | no | Machine-readable outcome token for programmatic filtering. |
blocked | boolean | no | true when the call was actively prevented by policy. |
severity | enum (INFO, LOW, MEDIUM, HIGH, CRITICAL) | no | Event severity. Defaults to HIGH for blocked calls and INFO for allowed calls. |
details | string | no | Additional context such as the matched policy pattern. |
Scan result
DefenseClaw Scan Result
Canonical scanner output — what skill-scanner / mcp-scanner / plugin-scanner / aibom / codeguard serialize as the CLI --output json payload and what gets persisted to audit.scan_results.raw_output. v7 extends the Finding shape with rule_id + line_number for SIEM-safe grouping, and extends the envelope with the provenance quartet.
| Field | Type | Required | Description |
|---|---|---|---|
scanner | enum (skill, mcp, plugin, aibom, codeguard, skill-scanner, mcp-scanner, plugin-scanner) | yes | |
target | string | yes | |
timestamp | string (date-time) | yes | |
duration | string \| null | no | |
scan_id | string \| null | no | v7 correlation id shared with gateway-event-envelope EventScan + child EventScanFinding events. |
schema_version | integer \| null | no | |
content_hash | string \| null | no | |
generation | integer \| null | no | |
binary_version | string \| null | no | |
agent_id | string \| null | no | |
agent_instance_id | string \| null | no | |
sidecar_instance_id | string \| null | no | |
findings | array | yes |