Husk

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:

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 summary
husk web        # serve the local web UI and open it in your browser
husk 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 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          # 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 nothing
husk 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.