chainsaw guard
Install-path guard maintenance
Install-path guard maintenance
| Subcommand | What it does |
|---|---|
chainsaw guard agent-hook | Check package installs in a coding agent’s shell commands (Claude Code PreToolUse hook) |
chainsaw guard allow | Clear a false typosquat block for one package, locally and permanently |
chainsaw guard auto-update | Turn background refresh of the malicious-package feed on or off |
chainsaw guard init | Print shell functions that route npm, pip, go, cargo, gem, yarn, pnpm, uv, poetry and pipx through the guard |
chainsaw guard status | Show local guard activity and privacy state |
chainsaw guard uninstall | Remove the shell guard activation line from your shell config files |
chainsaw guard update | Fetch the full known-malicious set for offline use (opt-in; uses the network) |
chainsaw guard [command]
chainsaw guard agent-hook
Check package installs in a coding agent’s shell commands (Claude Code PreToolUse hook)
chainsaw guard agent-hook [--format claude]
Check the package installs in a coding agent’s shell command before it runs.
Claude Code calls this as a PreToolUse hook on the Bash tool. It reads the hook payload on stdin and, when an install would be refused, answers with a deny and the reason; otherwise it prints nothing and the command runs. The checks are the install guard’s own (offline by default), applied to npm, pnpm, yarn, pip, uv, poetry, pipx, go, cargo, gem and brew installs, and also to npx, npm exec, npm/pnpm/yarn create, pnpm/yarn dlx, bunx, uvx, uv tool run and pipx run.
Install the Claude Code plugin, which also warns at session start when this CLI is missing or too old:
claude plugin marketplace add Chain305/chainsaw-core claude plugin install chainsaw-guard@chainsaw
Or add the hook to ~/.claude/settings.json yourself:
{“hooks”: {“PreToolUse”: [{“matcher”: “Bash”, “hooks”: [{“type”: “command”, “command”: “chainsaw guard agent-hook; s=$?; [ "$s" -eq 2 ] && exit 1; exit "$s"”}]}]}}
The exit-status line matters: Claude Code treats exit status 2 as “block this command”, so it is turned into 1, an error Claude Code shows without blocking. This command never exits 2 itself; the line guards against a crash.
This is a second check beside the shell guard, not enforcement: a command the hook cannot read (a script file, node -e) is not checked.
Flags
This command forwards its arguments to the underlying tool unchanged, so it parses no flags of its own. Anything after the command name goes to the wrapped package manager verbatim.
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
| Flag | Type | Default | Description |
|---|---|---|---|
--list | bool | — | list the allowed coordinates and exit |
--remove | bool | — | remove the coordinate from the allowlist instead of adding it |
The global flags apply here too.
chainsaw guard auto-update
Turn background refresh of the malicious-package feed on or off
chainsaw guard auto-update [on|off]
Turn background refresh of the malicious-package feed on or off.
When on, a guarded install that finds the feed more than 7 days old starts “chainsaw guard update” in the background and carries on; the install never waits for the download. When off, the install says how old the feed is and how to refresh it by hand. With no argument, prints the current setting.
You are asked once, the first time a guarded install in a terminal finds the feed out of date. Nothing starts when CHAINSAW_OFFLINE is set.
chainsaw guard init
Print shell functions that route npm, pip, go, cargo, gem, yarn, pnpm, uv, poetry and pipx 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, gem, brew, yarn, pnpm, uv, poetry and pipx 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
To leave some managers unwrapped, pass –skip, or set CHAINSAW_GUARD_SKIP. –install records the list in the rc line as CHAINSAW_GUARD_SKIP=…, which doctor and uninstall-hook read back. An older chainsaw ignores the variable and wraps every manager, so a downgrade fails safe:
chainsaw guard init –install –skip npm,brew eval “$(CHAINSAW_GUARD_SKIP=npm chainsaw guard init zsh)”
–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
| Flag | Type | Default | Description |
|---|---|---|---|
--dry-run | bool | — | With –install: print the target rc file and the exact line that would be added, without writing anything. |
--install | bool | — | Append the guard activation line to your shell rc file (idempotent) instead of printing it. |
--skip | stringSlice | — | Package managers to leave unwrapped, comma-separated (e.g. –skip npm,brew). “pip” also skips pip3. |
The global flags apply here too.
chainsaw guard status
Show local guard activity and privacy state
chainsaw guard status
chainsaw guard uninstall
Remove the shell guard activation line from your shell config files
chainsaw guard uninstall [flags]
Remove the shell guard: delete every active “chainsaw guard init” line (and the “# chainsaw install guard” comment –install writes above it) from your shell config files: ~/.zshrc, ~/.zshenv, ~/.zprofile, ~/.bashrc, ~/.bash_profile, ~/.profile, fish’s config.fish and the PowerShell profiles. Each file it changes is first copied to <file>.chainsaw-uninstall.bak.
Commented-out lines are left alone; they do nothing.
A running shell keeps the functions it already defined, so open a new shell afterwards (the command prints how to drop them from the current one).
This removes only the shell guard. Package managers wired through their own config files (“yes” in chainsaw doctor) are unwired with:
chainsaw uninstall-hook –all
To leave only some managers unwrapped instead, use:
chainsaw guard init –install –skip npm,yarn
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--dry-run | bool | — | Print the lines that would be removed, without changing any file. |
The global flags apply here too.
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
| Flag | Type | Default | Description |
|---|---|---|---|
--allow-network | bool | — | fetch even when CHAINSAW_OFFLINE is set (this command is the guard’s only network call) |
--force | bool | — | re-download and re-index even if the dataset is unchanged (skip the ETag check) |
The global flags apply here too.