Husk

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.}

Quickstart

husk            # print help (no subcommand does nothing else)husk scan       # one-shot scan of the current directory, plain terminal summaryhusk web        # serve the local web UI and open it in your browserhusk tui        # browse the latest scan in the terminal UI

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 [email protected]!! vulnerable npm [email protected]   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/[email protected] 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 initCreated ./.husk/policy.toml  `husk scan` and `husk ci` in this project now read this policy.
$ husk approve npm:lodash          # allow a package; recorded in policy + ledger

Plan safe fixes (dry-run by default; --apply writes them, with backups):

husk fix                          # show the plan, change nothinghusk fix --apply                  # write the auto-safe fixes

Gate a build in CI, JSON on stdout, non-zero exit at or above the threshold:

husk ci                           # exit 1 on high+ findings (see JSON output below)

Environment

husk reads a few environment variables:

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 report
• husk status: Print the last scan's report without rescanning
• husk tui: Open the interactive terminal UI on the latest scan
• husk web: Serve the local web UI on the latest scan
• husk check: Look up one package's malware/vulnerability verdict
• husk ci: Scan and gate a build; exit 1 at/above the threshold
• husk fix: Plan fixes from the latest scan; write them with --apply
• husk init: Create a committed .husk/policy.toml project policy
• husk approve: Record an allow/block/suppress decision in the policy
• husk policy: Show the active project policy and its counts
• husk ledger: Show or verify the personal trust ledger
• husk daemon: Scan on an interval; report findings new since last run
• husk login: Sign in to a husk account (coming soon)
• husk logout: Delete the credentials stored on this machine
• husk account: Show the signed-in account and machine link
• husk sync: Upload the last scan's inventory for retroactive alerts
• husk alerts: List this account's retroactive alerts
• husk telemetry: Manage opt-in anonymous telemetry (off by default)
• husk feedback: Send feedback to the husk developers
• husk 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.

husk scan --json | jq -r '.findings[].id'                 # every finding id, worst firsttest "$(husk status --json | jq .stats.critical)" -eq 0   # fail a script on any criticalhusk ci | jq '.providers[] | select(.ok | not)'           # which intel sources had problems

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/huskcd huskcargo 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:

  sh

  npm --prefix web cinpm --prefix web run build      # → web/distcargo build --release           # rust-embed embeds web/dist

• CLI/TUI-only (no Node needed). Drops the web UI entirely; nothing to build first:

  sh

  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.

Verifying a release

VERSION="v0.0.1"TARGET="x86_64-unknown-linux-gnu"          # or aarch64-apple-darwin, etc.ARCHIVE="husk-${VERSION}-${TARGET}.tar.gz"
# 1. Checksumsha256sum -c "${ARCHIVE}.sha256"           # macOS: shasum -a 256 -c ...
# 2. cosign signature: pin the workflow identity and the OIDC issuercosign 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}"
# 3. SLSA provenancegh attestation verify "${ARCHIVE}" --repo husk-security/husk

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.