Crate agent_bridle

Expand description

agent-bridle — the facade.

Re-exports the agent_bridle_core leash and assembles the default tool Registry a host consumes. Tools are registered through the explicit builder (DESIGN §5) — the DCE-proof path under strip+lto release profiles — and each tool’s symbol is anchored here by a pub use, so the linker can never silently drop one from tools/list.

use agent_bridle::registry;
use agent_bridle::{Caveats, CountBound, Scope};

let reg = registry();
let granted = Caveats {
    exec: Scope::only(["echo".to_string()]),
    max_calls: CountBound::AtMost(2),
    ..Caveats::top()
};
let out = reg
    .dispatch("shell", serde_json::json!({ "program": "echo", "args": ["hi"] }), &granted)
    .await?;
assert_eq!(out["exit_code"], 0);

Modules§

net_proxy: Loopback egress proxy for the macOS net host allow-list (#124, ADR 0016).
operator: Operator-authz contract — the shared types that bind an authenticated human operator to a permission decision (newt-agent #1354, the “web-authz triangle”, from the PR #1353 security audit).
policy: OCAP durable-policy schema — the shared contract for per-verdict permission policy (agent-bridle #220; newt-agent #1126 track O).

Structs§

AttestRequirement: What step-up an action demands before the gate will mint a context for it.
Attestation: A content-addressed, non-repudiable record that a human authorized a specific action — Provenance that becomes a Scar in the causal log. It carries its own proof: the credential id + signature prove which authenticator, the challenge proves which action, the generation proves which flight.
BackendToggles: Backend availability toggles (subsumes BRIDLE_REQUIRE_*).
BridleConfig: The complete, layered bridle configuration (mechanism). Every field defaults to today’s behavior; see the module docs for the authority-vs-mechanism split.
BrushShellTool: The carried brush engine (agent-bridle#20 / Track 2): a bash-in-Rust shell run in a dedicated sandboxed worker. Its CommandInterceptor provides the worker-local L2 leash; when an effective native backend engages, the worker and descendants inherit that L3 boundary. Opt-in via the brush feature; a construction-time alternative to ShellTool behind the ADR 0005 D2 seam, using the temporary brush-ocap-* fork (reubeno/brush#1184). The carried brush engine — a Tool that runs a free-form command string through a worker-hosted bash-in-Rust shell with a worker-local CommandInterceptor leash and any L3 boundary engaged by the effective caveats. Registered under "shell" (the ADR 0005 D2 seam), a peer of ShellTool / HostShellTool.
CallRequest: The action a leash decision is about: a tool name, its arguments, and the resolved resource the policy keys on.
Caveats: The capability set an agent holds — one element of the authority meet-semilattice. See the module docs.
Challenge: A what-you-see-is-what-you-sign challenge: the content address of DOMAIN ‖ action_id ‖ generation ‖ nonce. The authenticator signs this, so a verified signature proves the human authorized that exact action, in that causal generation, for that single-use nonce.
ConfinedChild: A spawned child together with the OS sandbox actually in force around it.
ConfinedCommand: Builder for a subprocess confined by a ToolContext.
ContentId: The content address (BLAKE3) of a canonicalized CallRequest — a stable, collision-resistant identity for “this exact action.”
Denial: One structured leash denial recorded by the in-process interceptor.
DescendantExec: Parse and inspect Brush shell source without expansion or execution.
Discharge: A human-presence proof presented to the gate. Crypto-format-agnostic: the signature and credential_id are opaque bytes a DischargeVerifier interprets (e.g. the Ed25519Verifier reads them as a raw ed25519 verifying key + assertion, under the verifier-ed25519 feature).
DischargeAttempt: A presented step-up proof, bundled: the single-use nonce the challenge was bound with, the Discharge itself, and the DischargeVerifier that checks it. Grouping the “proof” inputs keeps Gate::authorize_with_discharge to a small argument list and distinct from the “what” (tool, grant, request, policy).
Disclosure: Operator-facing disclosure — what an operator should know about how this run was shaped, kept strictly separate from the EnforcementReport (ADR 0016 precedent / ADR 0017 D6). Disclosure is informational: it records over-delivery, disabled normalizations, a forced backend, and the loud unbridled opt-in. It never participates in crate::fence_strength or the enforcement claim — a run can never raise its confinement claim by disclosing something, and disclosing something can never lower it either.
EnforcementReport: Per-axis confinement report for the four OS-confinement Caveat axes (fs_read, fs_write, exec, net).
Gate: The leash enforcer. One gate backs a session (or a sub-delegation); it tracks the remaining call budget and the generation it is valid for.
GatePolicy: Gate defaults (gate.rs constants) — and the human-gesture axis of the ADR 0018 mode lattice.
InspectedCommand: Parse and inspect Brush shell source without expansion or execution.
InspectedConstruct: Parse and inspect Brush shell source without expansion or execution.
InspectedRedirect: Parse and inspect Brush shell source without expansion or execution.
LimitsPolicy: Shell-tool + egress-proxy limits (shell_tool.rs / net_proxy.rs constants). Anti-drift tests for these land with the wiring PR (#143) where the consts live.
NetPolicy: Network policy — refines how the net authority axis (Scope<String>) is interpreted/enforced; defaults to today’s exact-host behavior (empty rules). A structured rule is proxy-enforced (userspace) ⇒ the honesty report keeps a non-loopback allow-list advisory, never kernel (#152).
NoopSandbox: The no-backend sandbox: applies nothing and reports SandboxKind::None.
NormalizationPolicy: Toggles for the automatic “normalizations” (assists) — each defaults to today’s always-on behavior; only loosening-safe ones are exposed as on/off (safety normalizations like fs canonicalization and env-scrub are intentionally absent here — see ADR 0017).
PathList: A configurable path list with extend-by-default semantics: resolve() returns base ∪ extra unless replace is set, in which case only extra is used. This lets config widen a security-relevant list (add a read path) safely, while shrinking one (dropping a loader path that would break confinement) requires an explicit replace = true opt-in. A widening is surfaced via PathList::widens so it can be disclosed (never silent).
ProxyHandle: A running loopback egress proxy. Dropping the handle shuts it down.
Registry: A catalog of tools that dispatches through the leash.
RegistryBuilder: Explicit builder for a Registry. The supported, DCE-proof registration path.
RootfsCache: A content-addressed cache of materialized minimal rootfs trees (#112 / ADR 0013 D7). Building a rootfs (resolving the ldd closure + assembling the tree) is the expensive step; keying it by the (granted-binaries + resolved closure) identity lets repeated runs of the same toolchain reuse the build.
RootfsEntry: One path the minimal rootfs exposes.
RootfsPlan: The plan for a minimal rootfs: exactly the paths to expose, nothing else.
RootfsPolicy: Minimal-rootfs builder inputs (rootfs.rs constants).
Rule: One policy rule mapping an action selector to a required step-up.
SandboxPolicy: Sandbox path lists + ABI floors (sandbox.rs constants).
SandboxedWorker: Builder for a fixed Agent Bridle worker born under the ordinary confinement funnel. Unlike ConfinedCommand, the executable is mechanism configuration chosen by the trusted embedder and the entrypoint arguments are fixed by TrustedWorkerKind; model-authored arguments never reach the spawn boundary.
SandboxedWorkerChild: A fixed internal worker together with its take-once parent control channel.
ShellInspection: Parse and inspect Brush shell source without expansion or execution.
ShellInspectionError: Parse and inspect Brush shell source without expansion or execution.
ShellInvocationId: Process-local identity for one shell tool invocation.
ShellTool: The confined shell tool.
StepUpPolicy: The per-action step-up policy: a set of selector rules plus a fall-through default. Most-specific (longest matching selector) wins. This is the authoring surface behind the operator menu (yes once / yes always / yes on passkey / no); it composes on top of the Caveats grant — Caveats decides whether the authority exists, this decides what gesture admits its use.
ToolContext: Proof that a tool invocation has passed the capability leash, carrying the least-authority caveats it is permitted to act under.
ToolEnvelope: A structured execution result. Serialized to the MCP content shape via ToolEnvelope::into_json; absent fields are omitted.
TrustedWorkerRequest: Core-owned authority envelope received by a fixed trusted worker.
VmPolicy: Micro-VM / jail parameters (jaild constants). Anti-drift lands with wiring (#147).
WebPolicy: Web-fetch limits (web_fetch.rs constants). Anti-drift lands with wiring.

Enums§

AxisEnforcement: How a single restricted Caveat axis is actually enforced for a run (ADR 0004 D1).
BridleMode: The top-level confinement mode. Bridled (default) confines per the caveats + backends; Unbridle is the explicit, acknowledged, honest “off” (grant Caveats::top(), advisory floor, SandboxKind::None) — resolved by the loader (#151), never reachable by omission.
ChildNetworkPolicy: How a confined child’s direct network-socket authority is enforced, beyond the caveat-driven Landlock TCP rule. A mechanism knob (it rides SandboxPolicy), never authority (Caveats): the caller states the required floor and the backend owns the enforcement (ADR 0017).
CountBound: A numeric upper bound axis (e.g. “at most N tool calls”).
Decision: The gate’s verdict for one call under a step-up policy.
DenialKind: Which kind of capability operation the leash refused.
HostMatch: How a host is matched. #[non_exhaustive] so REST/gRPC predicate variants (#153) can be added later without breaking existing configs.
HumanGate: The human-gate posture an unbridled run still enforces (ADR 0018 D9/D11) — the step-up floor the host will demand for a HIGH-consequence act. Distinguishes the two unbridled postures: Passkey/Prompt = Supervised-free (the human leash remains); None = Autonomous (no human in the loop — reachable only via the distinct second ack, D10). Disclosed on every envelope (R5).
NetDefault: Default network posture when no rule matches.
NetRule: One network rule. #[non_exhaustive] to admit Rest {..} / Grpc {..} variants additively (#153/#153-followup).
Presence: The strength of human gesture an action demands, weakest to strongest.
RedirectOperation: Parse and inspect Brush shell source without expansion or execution.
SandboxKind: Which OS-level sandbox actually backs an authorization.
Scope: A set-valued authority axis: either unrestricted (All, the top of this axis) or exactly the listed items.
ShellConstructKind: Parse and inspect Brush shell source without expansion or execution.
ShellOutputStream: The file descriptor from which an observed shell-output chunk originated.
ToolError: Why a dispatch or a tool invocation failed.
TrustedWorkerKind: A closed set of internal worker entrypoints. The caller cannot supply arbitrary arguments: each kind maps to a fixed private protocol.

Constants§

TRUSTED_WORKER_ACK: Fixed acknowledgement emitted only after a worker authenticates its frame.
TRUSTED_WORKER_BOOTSTRAP: Fixed, non-authority prelude used to establish kernel peer metadata.
TRUSTED_WORKER_FRAME_HEADER_LEN: Exact byte length of a trusted-worker response header.
TRUSTED_WORKER_HELLO_LEN: Exact byte length of a trusted-worker hello frame.
TRUSTED_WORKER_MAX_BODY: Maximum serialized trusted-worker request body.
TRUSTED_WORKER_PROTOCOL_VERSION: Version of the private trusted-worker authority envelope.

Traits§

DischargeProvider: Runs the human-presence ceremony and returns a Discharge — the dual of DischargeVerifier (a provider produces a proof; a verifier checks one).
DischargeVerifier: Verifies a Discharge against the requirement and the gate-recomputed Challenge. Pure: it performs no ceremony and no IO — that is a host capability outside the gate. An Err(reason) is turned into a leash denial.
Sandbox: An OS-level confinement that can be applied from a set of Caveats.
ShellOutputObserver: Receives bounded shell output while a tool invocation is still running.
Tool: A capability the agent can invoke, governed by the leash.

Functions§

best_available_sandbox: Return the strongest Sandbox available in this build on this host.
brush_private_control_supported: Whether this target provides the kernel-authenticated private transport required by BrushShellTool and carried-coreutils re-exec.
build_rootfs_plan: Build the minimal-rootfs plan for effective (ADR 0013 D2). Requires exec to be confined (Only) — a minimal rootfs is meaningless when any program may run, so an ambient exec is rejected (the caller falls back to the Tier-1 boundary). The plan contains: the resolved granted program files + each one’s ldd shared-library closure (incl. the loader) + the configured data paths + the granted fs_read (ro) / fs_write (rw) roots — and nothing else.
confinement_unenforceable: Would confining this child be a lie? Decided against the real backend kind (the probe the spawn actually confines through — not a stale gate stamp; ADR 0012 D4) and the principal’s floor.
decode_trusted_worker_frame_header: Decode a supervisor-to-worker frame header.
decode_trusted_worker_hello: Decode and validate a child-to-supervisor hello.
decode_trusted_worker_request: Deserialize a verified trusted-worker request body.
default_env_denylist: The default loader/interpreter/hook environment denylist (AB-004). Each name here can hijack code execution inside an otherwise-allowed program.
default_exec_path: The default PATH for a fully-authorized (exec = Scope::All) confined child: the ambient $PATH when set and non-empty, else the conventional RootfsPolicy search dirs, joined with the platform separator.
effective_sandbox_kind: The SandboxKind honestly in force for caveats given the strongest available backend: the backend’s own kind when it will actually confine something, else SandboxKind::None. The single honesty rule shared by the subprocess primitive (crate::ConfinedCommand) and the shell engine, so neither overclaims.
egress_proxy_plan: The egress-proxy plan for caveats (#124/#257, ADR 0016), or None to fall through to the ordinary confinement paths. Some((allow_hosts, fenced)) iff the grant is a general remote-host net allow-list (net_egress_proxy_hosts) and the available backend can kernel-fence the child’s egress to the loopback interface ([loopback_net_enforceable]) — the precondition for the proxy to be real confinement instead of a walk-around-able advisory. A proxy a rogue child can dial around is not confinement, so backends that cannot address-fence stay inert (the ADR 0015 honest posture); their net remains honestly advisory.
encode_trusted_worker_frame_header: Encode a supervisor-to-worker header binding challenge, body length, and content digest.
encode_trusted_worker_hello: Encode the child-to-supervisor hello that carries a fresh challenge.
enforcement_report: Classify each restricted axis of effective under the active sandbox (ADR 0004 D1). Pure; no IO.
fence_env: Drop denied loader/hook keys from env, returning the surviving map plus the dropped names (for disclosure). See LimitsPolicy::env_denylist (AB-004).
fence_strength: The fence’s overall strength: the greatest-lower-bound (weakest) enforcement across the restricted axes of report — a fence is only as strong as its weakest confined axis (ADR 0012 D1). Returns None when no axis is restricted (an empty report: a top grant confining nothing — a vacuous top with nothing to enforce). Pure: recomputed from the report on every call, never stored, so it cannot diverge from the lattice it summarizes (ADR 0004 D3 / ADR 0012’s rejection of a parallel strength enum). Consumers that need to know which axis dropped the strength still read the per-axis EnforcementReport.
human_gate: The process human-gate posture. Defaults to HumanGate::Passkey — the human leash is assumed on unless an acked path explicitly removed it, so the Autonomous posture is never reached by omission.
inspect_shell: Parse and inspect Brush shell source without expansion or execution.
install_default_providers: Carried-coreutils registration (agent-bridle#20 / issue #206). With carried-coreutils, the Brush engine’s non-conflicting shims re-exec <self> --invoke-bundled <name> and resolve against the dispatch-capable host binary. These functions are used by the engine internally. Install the registry from all compiled-in providers. Call once, before maybe_dispatch / register_shims, so both the dispatch fast-path and the shell’s shim builtins see a populated registry.
is_unbridled: Whether this process is running unbridled. Defaults to false (bridled) — confinement stays on unless an acked loader path explicitly called set_unbridled.
loopback_fenced_caveats: The confinement caveats for a spawned child paired with a loopback egress proxy (#124, ADR 0016): identical to caveats except the net axis is replaced by the loopback set plus any explicit unix: endpoints, so its [seatbelt_profile] emits the ADR 0015 kernel fence — (deny network*) + (allow network* (remote ip "localhost:*")) — while the fs/exec rules are preserved verbatim. The child can then reach nothing off-box directly; its only path off the loopback interface is the proxy it is pointed at via *_PROXY env. Pure; no IO. Only meaningful for a grant where net_egress_proxy_hosts is Some.
materialize_copy: Materialize a plan by copying file entries (and creating empty mount-point dirs for directory entries) under dest, preserving each src’s absolute path (so /usr/bin/cat lands at dest/usr/bin/cat). This is the test / diagnostic path — production exposes the same plan via read-only bind-mounts (no copy) through the broker (#108). Directory entries are left as empty mount-points (their contents are bound at run time), so this does NOT recurse into large data trees like /usr/share.
maybe_dispatch: Private Brush-worker dispatch. An embedder’s binary calls maybe_dispatch at the top of main so the sandboxed worker re-exec resolves before normal application startup. Run the bundled-command fast path if the process was invoked for it.
net_egress_proxy_hosts: The granted host set of a general remote-host net allow-list — the case SBPL cannot express and [net_loopback_only] therefore leaves advisory (ADR 0015 D3). Some(hosts) iff net is Only(set), non-empty, with at least one non-loopback host; None for All, the empty set (deny-all), and a loopback-only allow-list — those three keep their existing owners ([net_fully_denied] / [net_loopback_only]).
register_shims: Carried-coreutils registration (agent-bridle#20 / issue #206). With carried-coreutils, the Brush engine’s non-conflicting shims re-exec <self> --invoke-bundled <name> and resolve against the dispatch-capable host binary. These functions are used by the engine internally. Register a shim builtin for every name in the installed registry, using register_builtin_if_unset so brush’s own builtins win on conflict. Call install_default_providers first.
registry: Build the default tool registry for this host’s compiled feature set.
set_human_gate: Set the process human-gate posture (ADR 0018 D10/D11). Call once, from the loader; HumanGate::None (Autonomous) is legal only when unbridle is also engaged and the distinct no-step-up ack was supplied — the loader enforces that before calling this. Idempotent.
set_unbridled: Mark this process unbridled (confinement mechanism off). Call this once, from the loader, and only after the acked two-key opt-in has been verified (ADR 0018 D3). Idempotent: a second call is a no-op (the first wins).
spawn_confined_subprocess: Spawn program args confined by cx, with the inherited stdio of the parent.
start_egress_proxy: Start the egress proxy for a general remote-host net grant (#257) — the caveats-level convenience over start, for an external caller.
trusted_worker_frame_digest: Content digest binding one trusted-worker request to its fresh challenge.

Type Aliases§

ToolResult: The result type used throughout agent-bridle-core.

Crate agent_bridle

Crate agent_bridle Copy item path

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate agent_bridle