agent-bridle-tool-shell 0.7.4

Capability-confined shell tool for agent-bridle (argv + safe-subset engine).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

//! `agent-bridle-tool-shell` — capability-confined shell tool (argv + safe-subset engine).
//!
//! Per **ADR 0005** the object-capability *boundary* is L3 (kernel) and this
//! crate is the L2 *convenience* engine: `agent-bridle` is the **exec funnel**,
//! parsing each request itself ([`crate::parse`]) and running only what it can
//! confine. [`ShellTool`] accepts either argv form (`program` + `args`) or a
//! free-form `cmd` string, checks the `exec`/`fs` leash, spawns the program
//! directly, and **refuses the dynamic constructs by design** (`$(...)`,
//! backticks, subshells — the undecidable interiors of ADR 0001). The L3
//! backstop is wired (agent-bridle#35): when it will actually confine the run —
//! today the Landlock `fs_write` axis on a capable Linux build with `fs_write`
//! restricted — children spawn inside a kernel-enforced ruleset and
//! `sandbox_kind` reports [`agent_bridle_core::SandboxKind::Landlock`]; else the
//! run is honestly *advisory* with [`agent_bridle_core::SandboxKind::None`]
//! (I9, never overclaiming). Read/exec/net axes + macOS/Windows backends are
//! follow-ups (ADR 0006).
//!
//! The engine (agent-bridle#34 Track A + #45): a sequence of pipelines joined by
//! `&&`/`||`/`;` (short-circuit semantics), each pipeline simple commands with
//! quoted arguments, **redirections** (`> out`, `>> out`, `< in`, `2> err`,
//! `2>&1`), **filename globbing** (`*`/`?`/`[…]`) and **allowlisted `$VAR`
//! expansion** — every filesystem/env touch bridle performs (redirect opens,
//! glob directory listings, variable allowlist) is leash-/policy-checked before
//! any spawn. The dynamic constructs (`$(…)`, backticks, subshells) stay refused
//! by design. The process spawning is behind a `Spawner` seam (mocked in unit
//! tests; real path in `tests/real_spawn.rs`). `brush-bridle-core` remains the
//! deferred, reversible
//! full-bash alternative engine behind the same registry seam (ADR 0005 D4 —
//! tracked on agent-bridle#20).

#![forbid(unsafe_code)]
#![warn(missing_docs)]

#[cfg(feature = "brush")]
mod brush_shell;
#[cfg(feature = "brush")]
mod caveat_interceptor;
#[cfg(feature = "carried-coreutils")]
mod coreutils_dispatch;
#[cfg(feature = "host-shell")]
mod host_shell;
#[cfg(feature = "shell")]
mod net_proxy;
#[cfg(feature = "shell")]
mod parse;
#[cfg(feature = "shell")]
mod shell_tool;

#[cfg(feature = "shell")]
pub use shell_tool::ShellTool;

/// The sandboxed-host engine (ADR 0019 / #194): full-shell semantics with the
/// guarantee entirely on L3. Opt-in via the `host-shell` feature; a
/// construction-time alternative to [`ShellTool`] behind the ADR 0005 D2 seam.
#[cfg(feature = "host-shell")]
pub use host_shell::HostShellTool;

/// The carried **brush** engine (agent-bridle#20 / Track 2): a bash-in-Rust
/// shell run in-process, confined by the `CommandInterceptor` L2 leash — the
/// only engine that also confines a *restricted* `exec`/`net` grant, on any
/// platform. 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).
#[cfg(feature = "brush")]
pub use brush_shell::BrushShellTool;

/// Carried-coreutils dispatch (agent-bridle#20 / issue #206). An embedder's
/// binary calls [`maybe_dispatch`] at the top of `main` to become
/// dispatch-capable, so the brush engine's carried `ls`/`cat`/… shims (which
/// re-exec `<self> --invoke-bundled <name>`) resolve in-process against the host
/// binary — carried coreutils with no host tools. [`register_shims`] /
/// [`install_default_providers`] are used by the engine internally.
#[cfg(feature = "carried-coreutils")]
pub use coreutils_dispatch::{install_default_providers, maybe_dispatch, register_shims};

/// Network egress audit surface (#124, ADR 0016): the loopback proxy records
/// every proxy-visible connection as a [`NetAuditEvent`] through an [`AuditSink`]
/// (default off; enable via the `BRIDLE_NET_AUDIT` setting). The `bridle-netmon`
/// binary renders the JSON-lines stream as a live monitor.
#[cfg(feature = "shell")]
pub use net_proxy::{AuditSink, JsonlSink, NetAuditEvent, NetDecision, NetKind, NullSink};