Configuration — Zyrax Guard

01 / Reference

Commands

Run zyrax-guard <command>. Package commands default to the npm ecosystem.

Command	What it does
`check <name>[@version]`	Vet a single package before installing it.
`install <names...>`	Vet one or more packages, then run the install if they pass.
`scan`	Vet every dependency in the project's lockfile (or a base/head diff).
`scan-agents [dir]`	Audit AI agent config files in a directory (defaults to the current one).
`allow <name>`	Add a package to the local allowlist so it skips checks.
`init <bash\|zsh\|powershell> [npm\|pip\|cargo]`	Print the shell hook that auto-gates installs.
`mcp`	Run the MCP server (exposes scan_agents + check_package to your AI agent).
`mcp install [--global]`	Write a project .mcp.json (or register at user scope) for Claude Code.
`upgrade`	Update Zyrax Guard in place, verifying the download.
`version [--check]`	Print the version; --check forces an update check now.

02 / Reference

Flags

Flags apply only to the commands listed. Combine them freely.

Flag	Commands	Effect
`--ecosystem npm\|pypi\|crates`	check, install, scan, allow	Selects the package registry. Defaults to npm.
`--strict`	check, install, scan, scan-agents	Turns WARN into a failure for package commands; for scan-agents, any finding fails. Also ignores zyrax-allow suppression.
`--deep`	check, install, scan	Downloads the package and statically analyzes its install/build scripts.
`--json`	check, install, scan, scan-agents	Emits machine-readable JSON output.
`--sarif`	check, scan, scan-agents	Emits SARIF for code-scanning integrations.
`--ignore-scripts`	install	Passes through to the package manager so install/build scripts don't run.
`--base <file> / --head <file>`	scan	Diff two lockfiles and only vet what changed between base and head.
`--method npm\|brew\|go\|scoop\|binary`	upgrade	Overrides install-method detection when self-updating.
`--require-signature`	upgrade	On by default: binary upgrades verify the cosign signature and abort if cosign is missing. Pass `--require-signature=false` to accept checksum-only.
`--global / --command binary\|npx`	mcp install	Register at Claude Code user scope, and choose how the server is launched.
`--check`	version	Forces an update check immediately.

03 / Reference

Ecosystems

Pick a registry with --ecosystem on the package commands.

Ecosystem	Flag	Registry
npm	`(default)`	npmjs.com
PyPI	`--ecosystem pypi`	pypi.org
crates	`--ecosystem crates`	crates.io

04 / Reference

Verdicts & exit codes

Zyrax Guard fails closed: if it cannot verify a package, it returns ERROR and a non-zero exit code rather than letting it through.

Verdict	Exit code	Meaning
SAFE	0	No issues found.
WARN	0 · 1 with --strict	Low-confidence or advisory finding.
BLOCK	1	A blocking risk was found.
ERROR	1 (always)	Guard could not verify — registry / OSV unreachable. Fail-closed.

scan-agents exits 1 on any CRITICAL or HIGH finding — and with --strict, on any finding at all.

05 / Reference

Shell hook

Auto-gate every npm / pip / cargo install by adding the hook to your shell startup file. An optional ecosystem argument (pip or cargo) tunes which installs are intercepted.

bash / zsh — add to ~/.bashrc or ~/.zshrc

eval "$(zyrax-guard init bash)"

eval "$(zyrax-guard init zsh)"

# optional ecosystem:

eval "$(zyrax-guard init bash pip)"

PowerShell — add to $PROFILE

Invoke-Expression (zyrax-guard init powershell | Out-String)

06 / Reference

MCP setup

Give your AI agent the scan_agents and check_package tools. The one-step installer writes a project .mcp.json; --global registers it at Claude Code user scope. Or wire it up manually per client.

zyrax-guard mcp install

zyrax-guard mcp install --global

# or, manually (Claude Code):

claude mcp add zyrax-guard -- npx -y zyrax-guard mcp

For manual setup, add this server to your client's config (Claude Code, Cursor, Windsurf, VS Code, Continue.dev):

{

"mcpServers": {

"zyrax-guard": {

"command": "zyrax-guard",

"args": ["mcp"]

}

Per-client instructions: docs/mcp-integrations.md ↗

07 / Reference

CI / GitHub Action

Gate pull requests with tiagosilva07/zyrax-guard@v0.

- uses: tiagosilva07/zyrax-guard@v0

with:

scan: both

ecosystem: npm

strict: true

Input	Default	Effect
`scan`	both	What to scan: deps, agents, or both.
`ecosystem`	npm	Package registry for dependency scanning.
`lockfile`	—	Path to the lockfile to scan.
`base`	—	Base ref/file for diff scanning.
`strict`	false	Escalate WARN / any finding to a failure.
`deep`	false	Download and analyze install/build scripts.
`version`	—	Pin a specific Zyrax Guard version.
`fail-on-block`	true	Fail the job on a BLOCK verdict.
`sarif-file`	—	Write dependency findings as SARIF.
`agents-sarif-file`	—	Write agent-scan findings as SARIF.
`args`	—	Extra raw CLI arguments.

08 / Reference

Local policy file

Commit .zyrax/policy.json to share team policy. Allowlisted packages skip checks; denylisted packages always BLOCK.

{

"allow": ["internal-pkg"],

"deny": ["sketchy-pkg"]

}

09 / Reference

Suppressing agent-config false positives

Mark a known-good line or file inline. Suppression is never silent — the scan reports how many findings were suppressed — and --strict ignores it entirely.

Marker	Scope	Effect
`zyrax-allow`	the line it's on	Suppress all findings on that line.
`zyrax-allow: <rule-prefix>`	the line it's on	Suppress only findings whose rule matches the prefix.
`zyrax-allow-file`	the whole file	Suppress findings for the entire file.

10 / Reference

Environment variables

Variable	Effect
`ZYRAX_NO_UPDATE_CHECK=1`	Disables the daily background update check.

11 / Reference

Privacy

Nothing leaves your machine except the public package name you query.

Package checks

Only the public package name you query leaves your machine, for registry / OSV lookups.

Agent-config scanning

Fully local — no network, no telemetry.

Upgrades

zyrax-guard upgrade downloads a release from GitHub and verifies its SHA-256 checksum and cosign signature (required by default) before replacing the binary.

← Back to home