Husk README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Husk listing page.
A local-first security scanner for developers. One binary, no account.
Install · Quickstart · Usage · Commands · How it works
husk scans your machine for compromised packages, leaked secrets, risky install
scripts, and unsafe AI/MCP configuration, then shows you what to fix. It runs
locally: no login, no account, no file ever leaves your machine. An online scan
sends only package names, versions, and CVE ids to public advisory databases
(OSV.dev, npm, PyPI, GitHub, CISA KEV / FIRST EPSS); --offline makes zero
network calls.
Pre-1.0 software without an independent audit. Interfaces can change between releases. Bug reports and questions are welcome in Issues.
Install
husk runs on Linux and macOS. On Windows, run it inside WSL, where it installs and behaves exactly as it does on Linux. There is no native Windows build.
Download the latest signed release, verify its checksum, and install it:
It installs to ~/.local/bin, overridable with HUSK_INSTALL_DIR or
--install-dir. If that directory is not already on your PATH, it asks before
adding it to your shell's startup file and names the exact file it would change.
Decline, or run it without a terminal, and it prints the one command that adds
it instead. --no-modify-path never writes to a startup file at all.
Prefer not to pipe into a shell? Download install.sh, read it, then run
it. Every release is cosign-signed and SLSA-attested; the installer verifies the
SHA-256 checksum (and the signature too, when cosign is on your PATH). See
verifying a release.
Other install sources
Source Command cargo cargo install husk-seccargo-binstall cargo binstall husk-secnpm npm install -g husk-sec
Nix
Run it without installing anything:
The flake exposes two packages:
husk(the default, with the localhost web UI) andhusk-tui(the same binary without it, so it needs no Node toolchain).For persistent use, add the flake as an input and put the package in your configuration. NixOS:
Home Manager, with the same input:
If you would rather put it on
PATHimperatively than declare it,nix profile install github:husk-security/huskalso works.
Quickstart
husk with no subcommand prints help and exits, like git or cargo. The entry
points are husk scan (scan and print the report), husk web (the local web
UI, opened in your browser), and husk tui (the terminal UI).
Usage
A few of the commands you'll actually run day to day. The full list (every subcommand and flag) is in the command reference.
Scan a directory and print the findings report:
Vet one package before you install it (a live OSV.dev lookup):
The version can be an @version suffix (split on the last @, so
@scope/pkg@1.2.3 works) or separate arguments: husk check npm lodash 4.17.20.
A bare name (husk check lodash) assumes npm and checks malware advisories only.
Protect normal and lockfile installs with the tracked Safe Chain task in the Guide. Husk recommends the free, MIT-licensed third-party tool instead of shipping a weaker package-manager wrapper:
Commit a project policy (block/allow packages, suppress triaged findings,
set the CI threshold); the .husk/ directory is meant to be committed:
Plan safe fixes (dry-run by default; --apply writes them, with backups):
Gate a build in CI, JSON on stdout, non-zero exit at or above the threshold:
Environment
husk reads a few environment variables:
| Variable | Effect |
|---|---|
HUSK_HOME | State directory (ledger, daemon state, credentials); default ~/.husk. |
HUSK_CACHE_DIR | Cache directory (reports, scan index); default ~/.cache/husk. |
HUSK_PAGER, PAGER | Pager for long reports (default less); an empty value or cat disables paging. |
NO_COLOR | Disable ANSI colors in CLI output. |
HUSK_TOKEN | Bearer-token override for cloud commands (CI or one-off use). |
Command reference
One binary, many subcommands. Run husk <command> --help for the full flags
of any of them.
husk scan: Scan now and print the findings reporthusk status: Print the last scan's report without rescanninghusk tui: Open the interactive terminal UI on the latest scanhusk web: Serve the local web UI on the latest scanhusk check: Look up one package's malware/vulnerability verdicthusk ci: Scan and gate a build; exit 1 at/above the thresholdhusk fix: Plan fixes from the latest scan; write them with --applyhusk init: Create a committed .husk/policy.toml project policyhusk approve: Record an allow/block/suppress decision in the policyhusk policy: Show the active project policy and its countshusk ledger: Show or verify the personal trust ledgerhusk daemon: Scan on an interval; report findings new since last runhusk login: Sign in to a husk account (coming soon)husk logout: Delete the credentials stored on this machinehusk account: Show the signed-in account and machine linkhusk sync: Upload the last scan's inventory for retroactive alertshusk alerts: List this account's retroactive alertshusk telemetry: Manage opt-in anonymous telemetry (off by default)husk feedback: Send feedback to the husk developershusk mcp: Run the MCP server, or register it with an AI agent
JSON output
Several commands emit the full scan report as JSON: husk scan --json,
husk status --json, husk tui --json, and husk ci (always JSON). The shape
is identical everywhere; it is the report the local cache stores and every UI
renders. It is plain JSON on stdout: never paged, never colored, safe to pipe
straight into jq.
| Field | Type | Meaning |
|---|---|---|
api_version | number | Report-shape version (currently 4). Bumped when the shape changes; check it before parsing deeply. |
generated_at | string (RFC 3339) | When the scan finished. Reports older than 24 hours are considered stale by the UIs. |
roots | string[] | The directories that were scanned. |
context | object | System context: user, OS/arch, distro, kernel, git identity, detected package managers and dev configs. |
packages | object[] | The package inventory: {ecosystem, name, version, manifest_path, line} per discovered coordinate. |
projects | object[] | Discovered projects (the unit of attention); findings join to these via Finding.project_id. |
summary | object | The security headline (counts and framing used by the UIs). |
findings | object[] | Open findings. Each has id, title, severity (critical/high/medium/low/info), category, source, path, line, summary, evidence (pre-redacted), recommendation, references, cves, plus optional package, project_id, rule_id, confidence, priority, exploit (CISA KEV / EPSS), and fixed_version. |
ignored | object[] | Findings silenced by project policy or ledger decisions, kept out of findings, stats, and scoring. |
controls | object[] | Results from registered guide controls: status, local evidence, and related finding ids. |
remediations | object[] | Typed remediation proposals owned by controls; includes execution class, severity, operation, and related finding ids. |
guidance | object | The assessed Markdown guide: baseline/recommendation items, scan priority, review decisions, and handled percentage. |
providers | object[] | Per intel source: {name, ok, checked_packages, findings, message}. ok: false means coverage was incomplete. |
benchmarks | object[] | Per-stage timing: {stage, elapsed_ms, files_checked, bytes_scanned, packages_checked, findings, workers, detail}. |
stats | object | Totals: {packages, findings, critical, high, medium, low, info}. |
delta | object? | What changed since the previous cached scan of the same roots: {previous_at, previous_score, score, new_count, unchanged_count, resolved_count, resolved}. Absent on a first scan. |
How it works
- Local-first. Scans read files and parse them statically; husk never executes what it scans. Results and state stay on your machine; an online scan sends only package coordinates and CVE ids to public advisory databases.
- Package coverage. Discovery is a pluggable registry spanning ~68 package
ecosystems (language managers, OS/distro databases, AI/agent/editor surfaces,
CI/IaC/containers, and CycloneDX/SPDX SBOMs), see
src/scan/targets/. - Exploit-aware. CISA KEV and FIRST EPSS enrichment sorts actively-exploited CVEs to the top instead of dumping an undifferentiated CVE list.
- State that compounds. A committed
.husk/policy.toml(block/allow, suppress, CI threshold) travels with your repo; a personal hash-chained trust ledger at~/.husk/ledger.jsonlrecords everyapprove. Both are local, inspectable, and deletable. - Built for agents.
husk mcpserves a Model Context Protocol server over stdio so AI agents can read findings and trigger scoped scans;husk mcp install <agent>writes the config. It is listed in the Model Context Protocol Registry asmcp-name: io.github.husk-security/husk. Agent-facing details live in AGENTS.md andintegrations/.
Building from source
Cargo and Rust 1.95 or newer is all you need.
The localhost web UI is a Vite + React app in web/ that the binary
embeds (via rust-embed) under the default web Cargo feature. There are two
build paths; pick one:
-
Full build (default feature). Build the frontend first, then compile. This is the only path that needs Node:
-
CLI/TUI-only (no Node needed). Drops the web UI entirely; nothing to build first:
web/dist is generated output and is gitignored. A plain cargo build without
building the frontend first fails with a clear error pointing you at one of the
two paths above, because the web feature requires web/dist to exist.
If you already use Nix, the flake pins the same toolchain:
nix develop gives you a shell with it, and nix build .#husk (web UI included)
or nix build .#husk-tui (Node-free) builds the binary directly. None of it is
required.
Developer documentation (the module layout, the three pluggable registries, and how to add a scanner) is in AGENTS.md.
Privacy & trust: what husk reads, what never leaves your machine, how releases are signed
husk is a security tool, so it holds itself to a higher standard than the things it scans. Every claim below is enforced by code or CI in this repository.
What husk reads. Manifests and lockfiles, package-manager databases,
dotfiles and configs, git hook files, CI workflow files, MCP/agent configs, and
text files (for secret patterns). Scans are strictly read-only. husk writes
only its own state, ~/.husk/ (ledger, daemon state, cloud
config) and the cache dir, plain files you can inspect and delete anytime.
What husk never does.
- Never executes what it scans. No package managers, install scripts, git
hooks, editor extensions, MCP servers, or repo code; detection is static
parsing only. The one opt-in, per-invocation exception is
husk fix --apply --deps, which runs your package manager's version-pin command, shown to you first. - Never uploads your files. During an online scan husk sends package names,
versions, and CVE ids only to public advisory databases (OSV.dev, npm, PyPI,
GitHub, CISA KEV / FIRST EPSS), never file contents, paths, or secrets.
husk scan --offlinemakes zero network calls. - Never phones home by default. No account, no login wall; telemetry is off
until you run
husk telemetry on, and it honorsDO_NOT_TRACKand aHUSK_TELEMETRY_DISABLEDkill switch. All cloud features are opt-in and inert until used. - Never puts secrets in output. Secret findings carry short, pre-redacted excerpts, not the matched credential.
Verifiable properties.
| Claim | Verify |
|---|---|
100% safe Rust (#![forbid(unsafe_code)]) | grep -rn "forbid(unsafe_code)" src/lib.rs src/main.rs |
No proprietary trust path: every verdict comes from a public source queried over TLS; no husk-curated feed or signing root in the scan / husk check path | src/providers.rs, src/check.rs |
| Signed releases (cosign keyless + SLSA provenance, built in CI from the tag) | verifying a release |
| Supply-chain-checked deps (cargo-deny / cargo-machete / Dependabot / Scorecard) | ci.yml, scorecard.yml |
| Every third-party GitHub Action pinned to a full commit SHA (husk flags actions that aren't) | grep -rn "uses:" .github/workflows/ |
| Deterministic fixes: no LLM in the remediation apply path | src/remediation/ |
About tst/. tst/ holds intentionally unsafe fixtures (fake AWS keys
like AKIAIOSFODNN7EXAMPLE, prompt-injection markdown, vulnerable pins) so
husk's detectors can be tested deterministically. They are fake by policy and
excluded from the crates.io package. If your scanner flags them inside this repo,
it's working as intended; so is husk. tst/README.md explains
what is in there and why, and tst/ is out of scope in
SECURITY.md.
Vulnerabilities in husk itself go through the private channel in SECURITY.md, not public issues.
Verifying a release
Release verification details
Every release archive ships a SHA-256 checksum, a cosign keyless signature
(Sigstore Fulcio + the Rekor transparency log, no long-lived key to steal), and
a SLSA build-provenance attestation, all produced in CI from the tagged
commit. install.sh verifies the checksum automatically (and the signature if
cosign is present). To verify by hand:
A successful run prints Verified OK. If the identity or issuer doesn't match,
the signature is rejected; that's the point. The exact release process
is documented in .github/workflows/release.yml.
Publishing requires a stable vX.Y.Z tag on a commit reachable from main, a
matching version in Cargo.toml and flake.nix, and an explicitly allowed
human for both the original workflow run and any re-run. The workflow does not
rely on tag protection rules: it rechecks the live remote tag and its main
ancestry immediately before publishing. An unauthorized tag can start a run, but
it cannot reach the signing job.
Support and license
- Building and developing: see building from source above and AGENTS.md. New detections ship with fixtures and tests.
- Contributing: see CONTRIBUTING.md for the build and pull-request flow.
- Getting help: usage questions, help interpreting findings, concrete bugs, and feature requests all go to Issues.
- Security: report a vulnerability in husk itself privately, per SECURITY.md. Never open a public issue for one.
- License: MIT.