Hops
A hop is any unit of work in an agentic runtime that Sec0 instruments. Every hop gets a consistent identity, audit trail, and state propagation envelope. Sec0 supports seven hop types:
Each hop is registered in
sec0.config.yaml under app.hops with its type, nodeId, and type-specific metadata. Decorators resolve their configuration from this registry automatically.
For package installation and import paths, see Installation (and use the Quickstart for an end-to-end setup).
Custody Chain
Sec0 maintains a custody chain, an unbroken, signed audit trail across every hop in a request graph. This is achieved through:- Trace propagation: W3C-compatible
traceIdandspanIdflow through every hop - Agent state headers: Canonical state (
x-node-id,x-agent-ref,x-agent-state) propagated via HTTP headers - Signed audit envelopes: Each hop emits an Ed25519-signed NDJSON record with input/output integrity hashes
- Cause linking: Parent
traceId/spanIdare recorded ascause_trace_id/cause_span_idfor graph reconstruction
Architecture
Sec0 enforces security at two distinct boundaries:In-Device Security
These controls run within your application process:Network Boundary Security
These controls enforce policy when execution crosses process or network boundaries:How It Works
In-Device Security
Decorators instrument each hop in your application process. The middleware wraps your tool server to enforce policy and emit signed audit logs. Each layer is decorated independently:
On every tool invocation the middleware computes a source hash of the handler. When the hash changes (code update or version change), Security Hook scans (Claude Security/SAST/DAST) are triggered automatically. Execution can be blocked until the scan passes, based on configured severity thresholds.
Every decorated hop emits a signed audit envelope to the append-only audit log.
Network Boundary Security
When tool calls cross a network boundary, the gateway enforces auth, quotas, and custody at the edge.Tool call via gateway
The agent callscallToolViaGateway() with the server name, tool@version, arguments, auth header, trace context, and agent state. The gateway validates auth, checks entitlements and quotas, injects vendor tokens, enforces idempotency, then forwards to the remote tool server.
See Gateway Bridge for client usage and Network Gateway for gateway setup, endpoints, and enforcement options.
Agent-to-agent via gateway
callToolViaGatewayWithAgent() is a convenience wrapper that attaches the calling agent’s nodeId, runId, variables, and metadata so the receiving agent has full context about who is calling and why.
The gateway also exposes POST /a2a/invoke for agent-to-agent routing where the target server and tool are specified in the request body.
For a complete gateway capability breakdown and configuration examples, see Network Gateway and the Gateway Config Reference.
Agent State
Agent state is the canonical runtime context that flows through every hop. It carries the executingnodeId, a runId reference for correlation, and scoped variables/metadata that downstream hops can use for contextual policy enforcement.
When crossing process/network boundaries, agent state is transported via three canonical headers:
x-node-idx-agent-refx-agent-state
Policy
Sec0 policies are YAML documents that define runtime governance controls: tool allowlists, scanning, privacy/retention, side-effects, and enforcement behavior. Policies can be loaded locally or fetched dynamically, and can be scoped per agent (nodeId).
Start in observe mode (enforcement.deny_on: []) and progressively enable enforcement by adding deny_on reasons and optional escalate_on reasons for escalation workflows.
See the Policy Guide and the Policy Schema Reference.