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:
curl -fsSL https://husk-security.dev/install.sh | sh
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-sec |
| cargo-binstall | cargo binstall husk-sec |
| npm | npm install -g husk-sec |
Nix
Run it without installing anything:
nix run github:husk-security/husk -- scan
The flake exposes two packages: husk (the default, with the localhost web
UI) and husk-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:
{
inputs.husk.url = "github:husk-security/husk";
inputs.husk.inputs.nixpkgs.follows = "nixpkgs";
outputs = { nixpkgs, husk, ... }: {
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
{ environment.systemPackages = [ husk.packages.x86_64-linux.husk ]; }
];
};
};
}
Home Manager, with the same input:
home.packages = [ husk.packages.x86_64-linux.husk ];
If you would rather put it on PATH imperatively than declare it,
nix profile install github:husk-security/husk also works.
Quickstart
husk
husk scan
husk web
husk tui
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:
$ husk scan --offline .
packages: 286 findings: 36 critical: 5 high: 16 medium: 15 low: 0 info: 0
critical risky-agent-config AI agent is allowed unrestricted shell access
.claude/settings.local.json:4
high lifecycle-script Dangerous npm postinstall script
package.json:6
high risky-agent-config MCP config contains hardcoded secret
.mcp.json:7
...
Vet one package before you install it (a live OSV.dev lookup):
$ husk check lodash@4.17.20
!! vulnerable npm lodash@4.17.20
advisory GHSA-35jh-r3h4-6jhm via OSV.dev
Command Injection in lodash
Install a fixed version instead, or avoid the dependency until one is available.
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:
Review Aikido Safe Chain
Commit a project policy (block/allow packages, suppress triaged findings,
set the CI threshold); the .husk/ directory is meant to be committed:
$ husk init
Created ./.husk/policy.toml
`husk scan` and `husk ci` in this project now read this policy.
$ husk approve npm:lodash
Plan safe fixes (dry-run by default; --apply writes them, with backups):
husk fix
husk fix --apply
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. |
husk scan --json | jq -r '.findings[].id'
test "$(husk status --json | jq .stats.critical)" -eq 0
husk ci | jq '.providers[] | select(.ok | not)'
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.jsonl records every approve. Both are local,
inspectable, and deletable.
- Built for agents.
husk mcp serves 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 as mcp-name: io.github.husk-security/husk. Agent-facing details
live in AGENTS.md and integrations/.
Building from source
Cargo and Rust 1.95 or newer is all you need.
git clone https://github.com/husk-security/husk
cd husk
cargo build --release --no-default-features
./target/release/husk scan /path/to/your/project
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:
npm --prefix web ci
npm --prefix web run build
cargo build --release
-
CLI/TUI-only (no Node needed). Drops the web UI entirely; nothing to build
first:
cargo build --release --no-default-features
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 --offline makes zero network calls.
- Never phones home by default. No account, no login wall; telemetry is off
until you run
husk telemetry on, and it honors
DO_NOT_TRACK and a
HUSK_TELEMETRY_DISABLED kill 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:
VERSION="v0.0.1"
TARGET="x86_64-unknown-linux-gnu"
ARCHIVE="husk-${VERSION}-${TARGET}.tar.gz"
sha256sum -c "${ARCHIVE}.sha256"
cosign verify-blob \
--bundle "${ARCHIVE}.sigstore.json" \
--certificate-identity-regexp "^https://github.com/husk-security/husk/\.github/workflows/release\.yml@refs/tags/v" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
"${ARCHIVE}"
gh attestation verify "${ARCHIVE}" --repo husk-security/husk
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.
