agnt_tools/lib.rs
1//! # agnt-tools
2//!
3//! Built-in tools for the agnt agent runtime.
4//!
5//! Ships seven default tools that implement [`agnt_core::Tool`]:
6//!
7//! - **Filesystem**: `ReadFile`, `WriteFile`, `EditFile`, `ListDir`
8//! - **Search**: `Glob`, `Grep`
9//! - **Network**: `Fetch`
10//!
11//! Plus one **opt-in CVE-class** tool behind the `shell` feature:
12//!
13//! - **Shell** (`shell` feature): [`Shell`] — arbitrary command execution,
14//! default-OFF, requires an explicit sandbox config at construction.
15//!
16//! ## Security notes
17//!
18//! - All filesystem tools accept an optional [`sandbox::FilesystemRoot`] via
19//! `with_sandbox`. Without a sandbox they can read / write / list anywhere
20//! the process has access; with one, every path is canonicalized and
21//! rejected if it escapes the root.
22//! - `Fetch` has a built-in SSRF guard that runs *atomically* with DNS
23//! resolution via a custom [`ureq::Resolver`] ([`ssrf::SsrfResolver`]).
24//! http/https only, IPv4/IPv6 private / loopback / link-local /
25//! multicast / metadata addresses rejected in the same lookup that
26//! `ureq` then uses to connect — no DNS-rebinding TOCTOU. Redirects
27//! are disabled on the per-instance agent.
28//! - `Shell` is gated behind the `shell` cargo feature; it has no
29//! unsandboxed constructor. On Linux, the `bwrap-shell` feature adds
30//! a bubblewrap namespace on top of the argv allowlist for defense
31//! in depth.
32//!
33//! See `THREAT_MODEL.md` in the repo root for the current threat model
34//! (updated for v0.3.1).
35
36pub mod builtins;
37pub mod http;
38pub mod sandbox;
39pub mod ssrf;
40
41pub use builtins::{EditFile, Fetch, Glob, Grep, ListDir, ReadFile, WriteFile};
42pub use sandbox::FilesystemRoot;
43
44/// The CVE-class `Shell` tool. Only available when the `shell` cargo feature
45/// is enabled. See [`builtins::Shell`] for the full threat-model rustdoc.
46#[cfg(feature = "shell")]
47pub use builtins::Shell;