Crate soothsay 

soothsay

Read the omens before you curl | sh.

soothsay statically reads a shell script, usually an installer you’re about to pipe into your shell, and explains what it will do to your machine: which files it writes, which shell profiles it edits, whether it uses sudo, installs startup items, downloads and runs more code, decodes hidden payloads, or reaches for your SSH keys.

let report = soothsay::analyze("echo 'export PATH=$HOME/.tool/bin:$PATH' >> ~/.zshrc\n");
let f = &report.findings[0];
assert_eq!(f.category, soothsay::Category::ShellProfile);
assert_eq!(f.message, "appends to ~/.zshrc");

It is advisory static analysis, not a sandbox: anything the script downloads and runs is listed as a blind spot rather than guessed at.

Re-exports

pub use analyze::analyze;

pub use analyze::Category;

pub use analyze::FileTouch;

pub use analyze::Finding;

pub use analyze::Report;

pub use analyze::Severity;

pub use analyze::Touch;

pub use analyze::Url;

Modules

analyze

The rules: what each command in a script will do to the machine.

diff

What changed in a script’s behaviour between two versions.

guard

Guarding an agent’s shell commands: the logic behind soothsay hook and soothsay --check-command.

json

Just enough JSON to read a hook’s input: strict, bounded, no dependencies.

lexer

A small, forgiving tokenizer for POSIX-ish shell scripts.

packages

Package runners: npx -y pkg, uvx tool, pipx run pkg and friends run code straight from a package registry, so the guard looks the package up before they do.

parse

Turns tokens into a flat list of simple commands, remembering which pipeline each belongs to and which function (if any) encloses it.

render

Human and machine output.

sha256

Minimal SHA-256 (FIPS 180-4), so the report can pin the exact bytes that were analyzed without pulling in a dependency.

Functions

analyze_bytes

Like [analyze], but for raw bytes: invalid UTF-8 is replaced for the analysis, while sha256 is the hash of the bytes exactly as given (what a shell would run), not of the decoded text.