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:| Hop Type | Description | Decorator |
|---|---|---|
agent | An AI agent performing inference or work | @sec0.agent() |
orchestrator | A coordinator that plans and delegates to agents/tools | @sec0.orchestrator() |
gateway | A network-boundary router that forwards to upstream servers | @sec0.gateway() |
server | A tool server (MCP or otherwise) | @sec0.server() |
middleware | An enforcement layer wrapping tool execution | @sec0.middleware() |
tool | A specific tool invocation on a server | @sec0.tool() |
skill | A versioned agent skill/package invocation | @sec0.skill() |
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:| Control | Package | What It Does |
|---|---|---|
| Hop decorators | sec0-sdk/instrumentation | Audit trails, state propagation, trace linking for every hop |
| Agent state | sec0-sdk/agent-state | Canonical encoding/decoding of agent state across hops |
| Middleware enforcement | sec0-sdk/middleware | Wraps tool execution with policy, audit, and runtime decision hooks |
| Guard API | sec0-sdk/guard | App-level allow, redact, block, and escalate checks for outbound messages, tool calls, and APIs |
| Agent Guard | sec0-sdk/middleware | Inline scanning for prompt injection, PII, secrets, toxic content, malicious code |
| Registry freeze | sec0-sdk/middleware | Prevents handler swaps and registry mutation after initialization |
| Source hashing | sec0-sdk/middleware | Detects code changes in tool handlers and server code |
| SAST | sec0-sdk/middleware | Static analysis triggered on handler code/version change; blocks until scan passes |
| DAST | sec0-sdk/middleware | Dynamic analysis triggered on code/version change; generates runtime block rules with TTL |
Network Boundary Security
These controls enforce policy when execution crosses process or network boundaries:| Control | Package | What It Does |
|---|---|---|
| Policy enforcement | sec0-sdk/middleware | Tool allowlists, version pinning, deny rules on every invocation |
| Bridge client | sec0-sdk/middleware | Preserves custody, trace, idempotency, and agent-state continuity across gateway calls |
| Gateway auth | sec0-sdk/gateway | OIDC JWT validation at the network edge |
| Entitlements | sec0-sdk/gateway | Per-tenant/per-user tool allowlists and limits |
| Quotas | sec0-sdk/gateway | Rate limits and daily call limits per tenant/tool |
| Vendor token brokering | sec0-sdk/gateway | Inject upstream API keys without exposing them to agents |
| Idempotency/dedupe | sec0-sdk/gateway | Replay or reject duplicate side-effect calls |
| Boundary guardrails | sec0-sdk/gateway | Egress allowlists, filesystem allowlists, payload limits |
| AP2 mandates | sec0-sdk/mandate-ap2 | Multi-hop intent/cart verification for authorized actions |
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:| Decorator | What it instruments |
|---|---|
@sec0.orchestrator() | Coordinates agents, tracks plan vs. execution |
@sec0.agent() | Performs reasoning, sets objectives and state |
@sec0.tool() | Individual tool invocations |
sec0SecurityMiddleware() | Wraps the tool server with policy enforcement, Agent Guard, and registry freeze |
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.