diff --git a/CHANGELOG.md b/CHANGELOG.md index faffb9e1..b4c17f93 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,11 @@ a caller is here, what it changes inside a guard is in the commits. ## Unreleased +- Each crate carries a README of its own (what it reads, how to depend on + it, its example, compiled with the doctests), where every crate showed the + workspace's; the front door `milo-guards` keeps that one. +- The README's logo is named by its absolute URL, so crates.io shows it. + ## 0.1.0 (2026-11-05) The first release, on crates.io as `milo-guards` with the guards behind it. diff --git a/crates/code/Cargo.toml b/crates/code/Cargo.toml index 1ba49bea..e7b9b0e0 100644 --- a/crates/code/Cargo.toml +++ b/crates/code/Cargo.toml @@ -7,7 +7,7 @@ edition.workspace = true license.workspace = true repository.workspace = true homepage.workspace = true -readme.workspace = true +readme = "README.md" keywords.workspace = true categories.workspace = true rust-version.workspace = true diff --git a/crates/code/README.md b/crates/code/README.md new file mode 100644 index 00000000..c017d108 --- /dev/null +++ b/crates/code/README.md @@ -0,0 +1,85 @@ +# milo-guards-code + +Reads Python and JavaScript code and says what it is certain to do to files +and what it runs, or that it does not understand it. Part of +[milo-guards](https://github.com/camiloazula/milo-guards); a reader, not a guard. + +A shell line can hand an interpreter code (`python3 -c`, `node -e`), and an +agent can write a script or run a snippet directly. What matters to a guard +is which files the code deletes, writes, reads and moves, and what it runs. +This crate reads Python and JavaScript (Node, Bun and Deno) with their own +tree-sitter grammars and answers two questions of a piece of code: + +- **What is it certain to do?** `read` gives the `Act`s the code makes, in + order: a delete, a write, a read, a move, a program started, an + environment changed, each with the paths it names. What the reader cannot + follow comes out as `Act::Unread`, never left out. +- **Does it understand the code?** `understand` holds the code to a strict + allow-list: a few plain statements whose every call, name and import is on + a short list that only computes. Anything else is + `Understanding::NotUnderstood`, and a caller must not take "no acts" for + "does nothing" for such code. + +The reader judges nothing. Whether a delete of a path is risky is the +caller's: the shell guard of milo-guards turns an act into what it already +judges (a delete is `rm -rf PATH`, a command line a script a shell reads). + +## Install + +Through the front door, where it is the `code` feature (on by default) and +what the shell guard reads inline code with: + +```toml +[dependencies] +milo-guards = "0.1" +``` + +Or on its own: + +```toml +[dependencies] +milo-guards-code = "0.1" +``` + +If your program also links tree-sitter, it has to be on the 0.26 runtime: +tree-sitter allows one version per lockfile. + +## Example + +```rust +use milo_guards_code::{read, understand, Act, Arg, Language, Understanding}; + +// A snippet that computes is understood, and does nothing to a file. +let code = "print(1 + 1)"; +assert!(read(Language::Python, code).acts.is_empty()); +assert_eq!( + understand(Language::Python, code), + Understanding::Understood { imports: true }, +); + +// A delete is an act with the path it names, kept whatever the code is. +let code = "import shutil\nshutil.rmtree('/home/me')"; +let reading = read(Language::Python, code); +assert!(matches!(&reading.acts[..], [Act::Remove(Arg::Known(path))] if path == "/home/me")); +assert_eq!(understand(Language::Python, code), Understanding::NotUnderstood); + +// A name only known when the code runs is an argument it does not know. +let reading = read(Language::JavaScript, "require('fs').rmSync(process.argv[1])"); +assert!(matches!(&reading.acts[..], [Act::Remove(Arg::Unknown(_))])); +``` + +## Contract + +Like every milo-guards crate: no I/O and no environment reads, deterministic +(the same input gives the same answer on every machine), no policy (it +reports, and what to do with a finding is the caller's), what cannot be read +is risky, and nothing it is given makes it panic. The rules are on the +repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md). + +## License + +MIT or Apache-2.0, at your option +([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT), +[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of +[milo-guards](https://github.com/camiloazula/milo-guards); the API is on +[docs.rs](https://docs.rs/milo-guards-code). diff --git a/crates/code/src/lib.rs b/crates/code/src/lib.rs index aa86bab6..0cf76160 100644 --- a/crates/code/src/lib.rs +++ b/crates/code/src/lib.rs @@ -1000,3 +1000,14 @@ pub(crate) fn loads(specifier: &str, code: &str) -> Option { Foreign::Outside => Act::Loads(shorten(code)), }) } + +/// The README's example, compiled and run with the doctests so it cannot +/// drift from the code. Only rustdoc's doctest pass reads the file, so +/// building this crate never needs the README. +#[cfg(doctest)] +#[allow( + clippy::disallowed_macros, + reason = "the README include is read by rustdoc's doctest pass only" +)] +#[doc = include_str!("../README.md")] +mod readme {} diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml index 7ada5e3d..5817e3af 100644 --- a/crates/core/Cargo.toml +++ b/crates/core/Cargo.toml @@ -7,7 +7,7 @@ edition.workspace = true license.workspace = true repository.workspace = true homepage.workspace = true -readme.workspace = true +readme = "README.md" keywords.workspace = true categories.workspace = true rust-version.workspace = true diff --git a/crates/core/README.md b/crates/core/README.md new file mode 100644 index 00000000..1db87e3f --- /dev/null +++ b/crates/core/README.md @@ -0,0 +1,64 @@ +# milo-guards-core + +What every guard of [milo-guards](https://github.com/camiloazula/milo-guards) shares: the verdict types, the path +model and the test kit. + +A guard reads what an agent is about to do and says whether it is safe to do +without asking, or risky and why. This crate holds the parts of that which do +not depend on what is being read: + +- **The verdict.** `Assessment` is `Safe`, or `Risky` with a `Finding` for + each reason. A finding names a rule of the guard's own enum (which + implements `RuleName`, with a stable wire name), the reason in words, the + target it is about, and where there is one, what to do instead. +- **The directories everything is judged against.** `Paths`: the working + directory, the home directory and the workspace folders, with the files + the caller gates (`Protected`). +- **The path model.** `Resolver` says where a path spelled out as text lands + (`Place`), by its spelling alone, for POSIX and Windows (`Flavour`), on + whatever host it runs. +- **For guard crates**, helpers that take a path's spelling apart + (`spelling`), and behind the `testing` feature the table checker and the + sample directories the guards test themselves with. + +It depends on nothing beyond `std`, and does no I/O. + +## Install + +A caller of the guards depends on [`milo-guards`](https://docs.rs/milo-guards), +which re-exports this crate's types; depend on this crate directly only to +write a guard of your own. + +```toml +[dependencies] +milo-guards-core = "0.1" +``` + +## Example + +```rust +use milo_guards_core::{Flavour, Paths, Place, Resolver, Spelling}; + +let paths = Paths::new("/home/me/work/repo", "/home/me", ["/home/me/work/repo"]); +let resolver = Resolver::new(&paths); +let place = |path| resolver.place(Spelling::Plain(path), Flavour::Posix); +assert_eq!(place("src/../target"), Place::Inside); +assert_eq!(place("/home/me"), Place::Home { exact: true }); +assert_eq!(place("/etc/hosts"), Place::Top("a system folder")); +``` + +## Contract + +Like every milo-guards crate: no I/O and no environment reads, deterministic +(the same input gives the same answer on every machine), no policy (it +reports, and what to do with a finding is the caller's), what cannot be read +is risky, and nothing it is given makes it panic. The rules are on the +repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md). + +## License + +MIT or Apache-2.0, at your option +([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT), +[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of +[milo-guards](https://github.com/camiloazula/milo-guards); the API is on +[docs.rs](https://docs.rs/milo-guards-core). diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs index cbaea40d..66a592f1 100644 --- a/crates/core/src/lib.rs +++ b/crates/core/src/lib.rs @@ -44,3 +44,14 @@ pub use paths::{Paths, Protected, ProtectedKind}; pub use place::{Place, Sensitivity}; pub use resolve::{Flavour, Resolver, Spelling}; pub use verdict::{Assessment, Finding, RuleName}; + +/// The README's example, compiled and run with the doctests so it cannot +/// drift from the code. Only rustdoc's doctest pass reads the file, so +/// building this crate never needs the README. +#[cfg(doctest)] +#[allow( + clippy::disallowed_macros, + reason = "the README include is read by rustdoc's doctest pass only" +)] +#[doc = include_str!("../README.md")] +mod readme {} diff --git a/crates/file/Cargo.toml b/crates/file/Cargo.toml index 78443d12..83e9990a 100644 --- a/crates/file/Cargo.toml +++ b/crates/file/Cargo.toml @@ -7,7 +7,7 @@ edition.workspace = true license.workspace = true repository.workspace = true homepage.workspace = true -readme.workspace = true +readme = "README.md" keywords.workspace = true categories.workspace = true rust-version.workspace = true diff --git a/crates/file/README.md b/crates/file/README.md new file mode 100644 index 00000000..3379db8b --- /dev/null +++ b/crates/file/README.md @@ -0,0 +1,79 @@ +# milo-guards-file + +Judges one read or write of a path through a file API and says whether it is +safe without asking, or risky and why. The file guard of +[milo-guards](https://github.com/camiloazula/milo-guards). + +A shell line shows what a shell is about to do; an agent also reads and +writes files through a file API, and no line shows those calls. This guard +takes the two things such a call has, an `Access` and the path as the agent +wrote it, and judges them: `judge`. + +The path is one literal path, resolved by its spelling alone against the +`Paths` the caller passes: relative to the working directory, `~` as the home +directory, `..` applied, and the Windows spellings (drives, shares, long +paths, short names, any case) read as Windows reads them, whatever host the +guard runs on. Nothing is read from the disk, so a symlink is judged by its +own name. + +- A **read** is safe wherever it lands, except a key or a credential + (`read_secret`). An agent reads widely, and reading is what a caller lets + run unasked. +- A **write** (an edit, a create, an append, a rename's target) is safe + inside a workspace folder, to a temporary file and to the null device. + Anywhere else is a finding: beyond the workspace (`write_outside`), to a + key, a startup file, a file a tool runs on its own or the repository's + history (`write_sensitive`), or to what the caller gates + (`write_protected`). +- A path that is not one literal path, or that cannot be placed, is + `unreadable`; one on another machine is `network_share`. + +## Install + +Through the front door, where it is the `file` feature (on by default): + +```toml +[dependencies] +milo-guards = "0.1" +``` + +Or on its own: + +```toml +[dependencies] +milo-guards-file = "0.1" +``` + +## Example + +```rust +use milo_guards_file::{judge, Access, Paths, Rule}; + +let paths = Paths::new("/home/me/work/repo", "/home/me", ["/home/me/work/repo"]); + +assert!(judge(Access::Read, "src/main.rs", &paths).is_safe()); +assert!(judge(Access::Write, "src/main.rs", &paths).is_safe()); + +let assessment = judge(Access::Read, "~/.ssh/id_ed25519", &paths); +assert_eq!(assessment.findings()[0].rule, Rule::ReadSecret); +assert_eq!(assessment.findings()[0].reason, "reads your SSH keys"); + +let assessment = judge(Access::Write, "../other/x", &paths); +assert_eq!(assessment.findings()[0].rule, Rule::WriteOutside); +``` + +## Contract + +Like every milo-guards crate: no I/O and no environment reads, deterministic +(the same input gives the same answer on every machine), no policy (it +reports, and what to do with a finding is the caller's), what cannot be read +is risky, and nothing it is given makes it panic. The rules are on the +repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md). + +## License + +MIT or Apache-2.0, at your option +([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT), +[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of +[milo-guards](https://github.com/camiloazula/milo-guards); the API is on +[docs.rs](https://docs.rs/milo-guards-file). diff --git a/crates/file/src/lib.rs b/crates/file/src/lib.rs index 398918a2..ae39f1fb 100644 --- a/crates/file/src/lib.rs +++ b/crates/file/src/lib.rs @@ -343,3 +343,14 @@ fn has_variable(path: &str) -> bool { _ => false, }) } + +/// The README's example, compiled and run with the doctests so it cannot +/// drift from the code. Only rustdoc's doctest pass reads the file, so +/// building this crate never needs the README. +#[cfg(doctest)] +#[allow( + clippy::disallowed_macros, + reason = "the README include is read by rustdoc's doctest pass only" +)] +#[doc = include_str!("../README.md")] +mod readme {} diff --git a/crates/secrets/Cargo.toml b/crates/secrets/Cargo.toml index 4fd7ea52..64ebfc9b 100644 --- a/crates/secrets/Cargo.toml +++ b/crates/secrets/Cargo.toml @@ -7,7 +7,7 @@ edition.workspace = true license.workspace = true repository.workspace = true homepage.workspace = true -readme.workspace = true +readme = "README.md" keywords.workspace = true categories.workspace = true rust-version.workspace = true diff --git a/crates/secrets/README.md b/crates/secrets/README.md new file mode 100644 index 00000000..fb86ec6e --- /dev/null +++ b/crates/secrets/README.md @@ -0,0 +1,84 @@ +# milo-guards-secrets + +Reads a text and says whether it holds a credential (a key, a token, a +password) or personal data, and where. The secrets guard of +[milo-guards](https://github.com/camiloazula/milo-guards). + +A caller that puts text in front of a model scrubs it first, and a caller +that lets an agent write a source file asks whether the content carries a key +into it. Both are the same question of a text: what in it is a secret. The +text has no place, so unlike the guards that judge a path there is no `Paths` +here: a text in, findings out. + +- **A finding never carries the secret.** Its target is masked: the public + prefix of a key and its length (`AKIA… (20 chars)`), only the length when + what was found begins with the secret itself, or the first line of a block + of private key. +- **The spans are offsets, not text.** `find_spans` gives the byte range of + each thing found, on character boundaries, so a caller can replace it and + leave the text around it as it was. +- **The table is judged by shape and by value.** A key is found by the prefix + and the length its provider publishes; a password only where a name says + so; a number only when it passes its own check (the Luhn check of a card). +- **A text that is no key is safe.** SHAs, UUIDs, base64 fixtures, hashes, + minified code and a lockfile's integrity hashes are safe. +- **Shapeless secrets are a second function**, `find_high_entropy`, never a + part of `find`: a guard has no modes, and a caller that wants a guess calls + it. + +The text is read in time linear in its length, whatever it holds. + +## Install + +Through the front door, where it is the `secrets` feature (opt in: most +callers want the other guards and not a table of credential patterns in +their binary): + +```toml +[dependencies] +milo-guards = { version = "0.1", features = ["secrets"] } +``` + +Or on its own: + +```toml +[dependencies] +milo-guards-secrets = "0.1" +``` + +## Example + +```rust +use milo_guards_secrets::{find, find_spans, Rule}; + +assert!(find("let sha = \"3f786850e387550fdab836ed7e6dc881de23001b\";").is_safe()); + +// `AKIA` and sixteen characters: an AWS access key. +let text = format!("key = {}", ["AKIA", "FAKE2KEY3ID4TEST"].concat()); +let assessment = find(&text); +let finding = &assessment.findings()[0]; +assert_eq!(finding.rule, Rule::CloudKey); +assert_eq!(finding.reason, "holds an AWS access key"); +assert_eq!(finding.target.as_deref(), Some("AKIA… (20 chars)")); + +// A caller that scrubs replaces the span, and nothing else. +let span = find_spans(&text)[0]; +assert_eq!((span.rule, span.start, span.end), (Rule::CloudKey, 6, 26)); +assert_eq!(format!("{}[hidden]{}", &text[..span.start], &text[span.end..]), "key = [hidden]"); +``` + +## Contract + +Like every milo-guards crate: no I/O and no environment reads, deterministic +(the same input gives the same answer on every machine), no policy (it +reports, and what to do with a finding is the caller's), what cannot be read +is risky, and nothing it is given makes it panic. The rules are on the +repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md). + +## License + +MIT or Apache-2.0, at your option +([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT), +[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of +[milo-guards](https://github.com/camiloazula/milo-guards); the API is on +[docs.rs](https://docs.rs/milo-guards-secrets). diff --git a/crates/secrets/src/lib.rs b/crates/secrets/src/lib.rs index f6fae8b4..fb4cdd5c 100644 --- a/crates/secrets/src/lib.rs +++ b/crates/secrets/src/lib.rs @@ -273,3 +273,14 @@ pub fn find_high_entropy(text: &str, bits: f64) -> Vec { }) .collect() } + +/// The README's example, compiled and run with the doctests so it cannot +/// drift from the code. Only rustdoc's doctest pass reads the file, so +/// building this crate never needs the README. +#[cfg(doctest)] +#[allow( + clippy::disallowed_macros, + reason = "the README include is read by rustdoc's doctest pass only" +)] +#[doc = include_str!("../README.md")] +mod readme {} diff --git a/crates/shell/Cargo.toml b/crates/shell/Cargo.toml index 5675b02d..506af1df 100644 --- a/crates/shell/Cargo.toml +++ b/crates/shell/Cargo.toml @@ -7,7 +7,7 @@ edition.workspace = true license.workspace = true repository.workspace = true homepage.workspace = true -readme.workspace = true +readme = "README.md" keywords.workspace = true categories.workspace = true rust-version.workspace = true diff --git a/crates/shell/README.md b/crates/shell/README.md new file mode 100644 index 00000000..ddbc77c5 --- /dev/null +++ b/crates/shell/README.md @@ -0,0 +1,91 @@ +# milo-guards-shell + +Reads a shell command line (POSIX shell, PowerShell or cmd) and says whether +it is safe to run without asking, or risky and why. The shell guard of +[milo-guards](https://github.com/camiloazula/milo-guards). + +It works in three steps: + +1. **Split** the line into units, one per program it runs, with the grammar + of the shell that runs it (`Shell`). Chains, pipes, substitutions, loops + and blocks are walked, every branch whether or not it would run; wrappers + (`sudo`, `env`, `xargs`, `find -exec`) are taken off, and a shell started + with a script (`bash -c`, `eval`, `cmd /c`, `powershell -Command`) has + that script split in its own grammar. Python and JavaScript given inline + (`python3 -c`, `node -e`, a here-document) are read with their own + grammars, through `milo-guards-code`. +2. **Detect** with rules that read a unit's program, flags, operands and + redirects, never the raw text, and judge each path by where it resolves + against the `Paths` the caller passes. +3. **Combine**: the line is safe only when no unit is risky, and a risky line + carries every finding. + +Three functions answer three questions of the same reading: `classify`, +whether the line is safe; `effect`, whether it only reads (and whether the +reads stay in the workspace), changes something, or cannot be told; and +`explain`, how the line was read, unit by unit, drawn as a short tree for a +person to see. + +What cannot be read is risky: a program or a script known only when it runs, +a line the grammar cannot parse, shells nested past a limit. Nothing here +touches the file system or the environment: a Windows line is judged on macOS +as it would be on Windows. + +## Install + +Through the front door, where it is the `shell` feature (on by default): + +```toml +[dependencies] +milo-guards = "0.1" +``` + +Or on its own: + +```toml +[dependencies] +milo-guards-shell = "0.1" +``` + +The `inline` feature (on by default) reads the Python and JavaScript a line +gives an interpreter; off, such a line is still found but none of its code is +read, every inline line is `unknown`, and neither grammar is built. If your +program also links tree-sitter, it has to be on the 0.26 runtime. + +## Example + +```rust +use milo_guards_shell::{classify, effect, Effect, Paths, Reach, Rule, Shell}; + +let paths = Paths::new("/home/me/work/repo", "/home/me", ["/home/me/work/repo"]); + +// Building inside the workspace is the agent's own business. +assert!(classify("cargo build && rm -rf target", Shell::Posix, &paths).is_safe()); + +// Deleting the home directory is not, and the answer says why. +let assessment = classify("rm -rf ~", Shell::Posix, &paths); +let finding = &assessment.findings()[0]; +assert_eq!(finding.rule, Rule::Delete); +assert_eq!(finding.target.as_deref(), Some("~")); + +// Whether a line only reads is a second answer, from the same split. +assert_eq!(effect("git status", Shell::Posix, &paths), Effect::ReadsOnly(Reach::Workspace)); +assert_eq!(effect("mkdir build", Shell::Posix, &paths), Effect::Changes); +assert_eq!(effect("./script.sh", Shell::Posix, &paths), Effect::Unknown); +``` + +## Contract + +Like every milo-guards crate: no I/O and no environment reads, deterministic +(the same input gives the same answer on every machine), no policy (it +reports, and what to do with a finding is the caller's), what cannot be read +is risky, and nothing it is given makes it panic. The rules are on the +repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md). + +## License + +MIT or Apache-2.0, at your option +([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT), +[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of +[milo-guards](https://github.com/camiloazula/milo-guards); the API is on +[docs.rs](https://docs.rs/milo-guards-shell). diff --git a/crates/shell/src/lib.rs b/crates/shell/src/lib.rs index 682d1dad..c95e22f3 100644 --- a/crates/shell/src/lib.rs +++ b/crates/shell/src/lib.rs @@ -472,3 +472,14 @@ pub fn effect_paths(command: &str, shell: Shell, paths: &Paths) -> Option, findings: &mut Vec) -> bool { } ipv4 } + +/// The README's example, compiled and run with the doctests so it cannot +/// drift from the code. Only rustdoc's doctest pass reads the file, so +/// building this crate never needs the README. +#[cfg(doctest)] +#[allow( + clippy::disallowed_macros, + reason = "the README include is read by rustdoc's doctest pass only" +)] +#[doc = include_str!("../README.md")] +mod readme {}