Install-path guard maintenance

chainsaw guard [command]

chainsaw guard allow

Clear a false typosquat block for one package, locally and permanently

chainsaw guard allow [<ecosystem>:<name>] [flags]

Record a local decision that one package is NOT a typosquat, so the guard stops refusing it on this machine.

Typosquat detection is name-similarity inference, and no heuristic reaches zero false positives. This is the escape hatch that makes a residual one survivable: instead of turning the guard off, you clear the single coordinate that was wrong. The decision is written to a small JSON file (mode 0600) next to the guard’s other local state, with the verdict text and a timestamp, so it reads as an audit trail rather than a list of names.

Offline. Nothing is sent anywhere, and nothing is shared with other machines.

Stored in <config dir>/guard_allowlist.json (override with CHAINSAW_GUARD_ALLOWLIST).

WHAT IT CANNOT DO. The allowlist clears typosquat verdicts and nothing else. A known-malicious package (the OpenSSF feed and the built-in floor) and a known-vulnerable version are evidence about a published incident, not a guess about a name, so they are refused here and keep blocking at install time. The byte-level behavioral checks are excluded too, and deliberately: they read the package’s bytes, which change with every release, so a version-less exemption would silently cover a future compromised version of a package you vouched for while it was clean.

Exit codes: 0 on success, 1 when the coordinate is refused on evidence the allowlist cannot clear, 2 on an IO failure, 4 on a bad invocation.

Examples

# clear a false typosquat block
chainsaw guard allow npm:jsdoc

# same thing, two-token form
chainsaw guard allow pip nvidia-cudnn-cu11

# see what this machine has allowed, and why
chainsaw guard allow --list

# undo one
chainsaw guard allow --remove npm:jsdoc

Flags

The global flags apply here too.

chainsaw guard init

Print shell functions that route npm, pip, go, cargo and gem through the guard

chainsaw guard init [bash|zsh|fish|powershell|pwsh|cmd] [flags]

Print shell functions that route your package managers through the Chainsaw install guard, so installs are checked automatically without typing “chainsaw” each time.

Add to your shell config and reload:

~/.zshrc or ~/.bashrc

eval “$(chainsaw guard init zsh)”

~/.config/fish/config.fish

chainsaw guard init fish | source

PowerShell $PROFILE (Windows, macOS, Linux)

chainsaw guard init powershell | Invoke-Expression

cmd.exe — current console session only, see below

chainsaw guard init cmd

The functions delegate to the real npm, pip, pip3, go, cargo and gem after the check.

The default path is offline. Two opt-in paths do reach the network, and neither runs unless you ask for it: “chainsaw guard update” downloads the OpenSSF malicious-package set, and CHAINSAW_GUARD_DEEP=1 fetches package bytes for artifact analysis.

With –install, append the activation line to your shell rc file (idempotent) instead of printing the functions, so setup is a single command with no copy-paste:

chainsaw guard init –install

–install supports every shell that HAS a startup file: bash, zsh, sh, fish and PowerShell. cmd.exe has none — doskey macros live only in the console session that defined them — so –install refuses for cmd rather than writing a file no shell reads. Use PowerShell on Windows for a persistent wiring.

Flags

The global flags apply here too.

chainsaw guard status

Show local guard activity and privacy state

chainsaw guard status

chainsaw guard update

Fetch the full known-malicious set for offline use (opt-in; uses the network)

chainsaw guard update [flags]

Download the OpenSSF malicious-packages dataset and write a local cache that the install guard (chainsaw npm/pip/go) merges on top of its built-in offline floor. This is the only part of the guard that touches the network, and only when you run it. After updating, known-malicious coverage is the full set, evaluated entirely on-box.

Flags

The global flags apply here too.