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.

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:

`sh

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:

`nix

{

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:

`nix

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            # 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 --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 first

test "$(husk status --json | jq .stats.critical)" -eq 0 # fail a script on any critical husk 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 commi