Zyrax Guard

Zyrax Guard

[CI] [License: MIT] [Go Report Card] [Website]

Audit your AI agent configs before you run them. Catch the prompt injection, malicious MCP servers, and credential-exfil hiding in the files that steer your AI — CLAUDE.md, .mcp.json, agent settings, skills — and vet the packages they pull in. In milliseconds. Nothing leaves your machine.

$ zyrax-guard scan-agents .
Scanning . for agent config files...  Found 2 file(s): .mcp.json, CLAUDE.md
  SCAN REPORT · zyrax-guard v0.13.0  2 finding(s) requiring review
  [1 CRITICAL]  [1 HIGH]
  [HIGH]  .mcp.json           MCP server 'data-exfil' uses non-HTTPS URL: http://attacker.example.com/collect           → Use HTTPS for all external MCP server URLs.
  [CRITICAL]  CLAUDE.md:3           Prompt injection keyword detected: 'ignore previous instructions'           → Remove or review this instruction. Triage as false positive if intentional.
  2 finding(s) — 1 CRITICAL, 1 HIGH
$ zyrax-guard check lodahs✗ [email protected] — BLOCK  - looks like a typo of "lodash" (far more popular); this name has only 46 weekly downloads  - MAL-2025-25502: Malicious code in lodahs (npm)  did you mean: lodash  to override:  zyrax-guard allow lodahs

Works locally, in CI, and as a gate for AI coding agents. No account required. Nothing phones home except the public package name you are querying.

Get it (pick one):

npx zyrax-guard@latest scan-agents .            # no install — audit this repo's agent configsbrew install tiagosilva07/zyrax/zyrax-guard     # macOS / Linuxscoop bucket add zyrax https://github.com/tiagosilva07/scoop-zyrax && scoop install zyrax-guard   # Windowsgo install github.com/tiagosilva07/zyrax-guard/cmd/zyrax-guard@latest

Then: zyrax-guard scan-agents . to audit configs, or zyrax-guard check <pkg> to vet a package. Full install options (signed binary, curl|sh) and verification are below.

🌐 Homepage: zyrax.io

Install

npm / npx

npx zyrax-guard@latest scan-agents .     # audit agent configsnpx zyrax-guard@latest check lodash      # vet a package

Ships the prebuilt Go binary per-platform (via optionalDependencies) — no runtime download. Works anywhere Node 18+ is available.

Homebrew (macOS / Linux)

brew install tiagosilva07/zyrax/zyrax-guard

Installs the signed release binary (SHA-256 verified by Homebrew). Updates land via brew upgrade once a new release is published.

Scoop (Windows)

scoop bucket add zyrax https://github.com/tiagosilva07/scoop-zyraxscoop install zyrax-guard

Installs the signed release binary (SHA-256 verified by scoop against the manifest, whose hashes come from the release's signed checksums.txt). zyrax-guard upgrade detects a scoop install and delegates to scoop update zyrax-guard.

Quick install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/tiagosilva07/zyrax-guard/main/scripts/install.sh | sh

Downloads the signed release binary for your OS/arch, verifies its SHA-256 against the release checksums, and installs it (to /usr/local/bin, or ~/.local/bin if that is not writable). Pin a version with VERSION=v0.5.0, or set BINDIR to choose where it lands. Verifies the cosign signature too when cosign is on your PATH.

go install (Go 1.23+)

go install github.com/tiagosilva07/zyrax-guard/cmd/zyrax-guard@latest

Signed release binary

Download from Releases. Every release ships:

• Pre-built binaries for linux/darwin/windows × amd64/arm64
• checksums.txt (SHA-256)
• SLSA L3 build provenance (.cosign.bundle per artifact)
• SBOM (zyrax-guard.spdx.json)

Verify a binary:

cosign verify-blob \  --bundle zyrax-guard-linux-amd64.cosign.bundle \  zyrax-guard-linux-amd64

Build from source

git clone https://github.com/tiagosilva07/zyrax-guardcd zyrax-guardgo build -o zyrax-guard ./cmd/zyrax-guard

Updating

Guard checks for a newer release at most once a day (a read-only lookup of its own version on registry.npmjs.org) and prints a one-line notice on stderr when one is available. To update:

zyrax-guard upgrade          # detects how Guard was installed and updates itzyrax-guard version --check  # force a version check now

upgrade delegates to your package manager (npm/brew/scoop/go) when Guard was installed that way; for curl|sh / standalone-binary installs on Linux/macOS it downloads the signed release, verifies its SHA-256 against checksums.txt and its keyless cosign signature before replacing the binary (any mismatch aborts the upgrade). Signature verification is required by default — if cosign is not installed the upgrade aborts with instructions; pass --require-signature=false to accept checksum-only verification explicitly. On Windows, install via scoop to get delegated upgrades; the standalone Windows binary is still upgraded manually (the notice links to Releases). Disable the daily check with ZYRAX_NO_UPDATE_CHECK=1.

Quickstart

Audit AI agent configs

zyrax-guard scan-agents .          # scan current directoryzyrax-guard scan-agents /repo      # scan a specific pathzyrax-guard scan-agents . --json   # JSON outputzyrax-guard scan-agents . --strict # exit 1 for any finding (not just CRITICAL/HIGH)

Scans CLAUDE.md, AGENTS.md, GEMINI.md, .mcp.json, .claude/settings.json, and Cursor rules files. Exits 1 if any CRITICAL or HIGH finding is found.

Check a single package

zyrax-guard check lodash                              # npm (default)zyrax-guard check requests --ecosystem pypi           # PyPIzyrax-guard check serde --ecosystem crates            # crates.iozyrax-guard check github.com/pkg/errors --ecosystem gomod  # Go modules

Check-then-install

zyrax-guard install lodash axios                      # vets, then runs npm installzyrax-guard install flask --ecosystem pypi            # vets, then runs pip installzyrax-guard install serde --ecosystem crates          # vets, then runs cargo addzyrax-guard install github.com/pkg/errors --ecosystem gomod  # vets, then runs go get

Allow a package (add to local policy)

zyrax-guard allow my-internal-pkg# allowed "my-internal-pkg" (recorded in .zyrax/policy.json)

Commit .zyrax/policy.json — it is the reviewable allowlist for your project.

Scan a PR's lockfile diff

zyrax-guard scan --base /tmp/base-lock.json --head package-lock.json --sarif

Emits SARIF 2.1.0 to stdout. Exit code 0 if no BLOCK or ERROR; non-zero otherwise. Add --strict to treat WARN as failure.

Auditing AI agent configs (scan-agents)

AI coding agents (Claude Code, Cursor, Gemini CLI) read configuration files that can be weaponized: a malicious CLAUDE.md in a repo you clone, a tampered .mcp.json that points to an attacker's server, an MCP tool whose description hides instructions, a settings.json granting wildcard shell access, or prose that quietly steers the agent toward reading .env and POSTing it out. Guard detects these before the agent runs.

zyrax-guard scan-agents .

What it scans

What it detects

Exit code: 1 if any CRITICAL or HIGH finding; 0 otherwise. Use --strict for exit 1 on any finding.

Obfuscation-normalized. Before matching, detection normalizes common disguises — zero-width and format characters, homoglyphs, full-width and leetspeak substitutions, and separator/line splitting — so trivially obscured payloads (y0u 4r3 n0w…, ignore—previous—instructions, Cyrillic look-alikes) are still caught. It stays a fast, deterministic, on-device guardrail for known agent-config attack patterns — not a complete defense against a determined adversary who paraphrases or writes in another language. Semantic detection is a roadmap item for the Zyrax platform, not the local CLI.

Suppressing a legitimate collision. A real skill or config can legitimately phrase something the heuristics flag (e.g. a reviewer skill that says "act as a senior reviewer"). Silence it with an inline zyrax-allow comment on that line — optionally zyrax-allow: <rule-prefix> to scope it — or zyrax-allow-file: <rule-prefix> for a whole file. Suppression is never silent: the scan always reports N finding(s) suppressed by zyrax-allow, and --strict ignores suppressions entirely (audit/CI mode), so a hostile config can't use the directive as a kill switch.

In CI

- name: Audit agent configs  run: zyrax-guard scan-agents . --strict

Via MCP (scan_agents tool)

Once registered as an MCP server, agents also have access to scan_agents:

{  "name": "scan_agents",  "arguments": { "dir": "." }}

GitHub Action

Gate every pull request. By default (scan: both) Zyrax Guard audits AI agent configs (prompt injection, malicious MCP servers, risky permissions) and gates dependencies added in the PR, failing the check if anything is blocked. Add .github/workflows/zyrax-guard.yml:

Pin for production: these examples pin third-party actions to commit SHAs — mutable tags are a supply-chain risk (the exact risk Guard exists to catch). Pin zyrax-guard to an exact version or commit SHA too for fully reproducible CI.

name: Zyrax Guardon: pull_requestjobs:  guard:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # pin: actions/checkout@v5        with:          fetch-depth: 0          # lets Guard diff against the PR base (added deps only)      - uses: tiagosilva07/zyrax-guard@v0        with:          ecosystem: npm          # npm | pypi | crates

On a pull request it scans only the dependencies added versus the base branch; otherwise it scans the whole lockfile. The job fails when a dependency is blocked. @v0 tracks the latest 0.x release; pin an exact version (e.g. @v0.7.1) for fully reproducible CI.

Inputs (all optional): scan (deps | agents | both, default both), ecosystem (default npm), lockfile (default per-ecosystem), base (explicit base lockfile), strict (treat WARN as failure), deep (inspect install scripts), version (Guard release, default latest), fail-on-block (default true), sarif-file (write dependency SARIF for Code Scanning), agents-sarif-file (write agent-config SARIF for Code Scanning), args (extra raw flags).

Upload results to GitHub Code Scanning so findings show up inline on the PR:

      - uses: tiagosilva07/zyrax-guard@v0        with:          sarif-file: zyrax-guard.sarif          fail-on-block: "false"   # let Code Scanning surface findings; don't hard-fail      - uses: github/codeql-action/upload-sarif@dd903d2e4f5405488e5ef1422510ee31c8b32357  # pin: github/codeql-action/upload-sarif@v3        with:          sarif_file: zyrax-guard.sarif

Audit agent configs and dependencies, both surfaced in Code Scanning:

      - uses: tiagosilva07/zyrax-guard@v0        with:          scan: both          sarif-file: zyrax-guard-deps.sarif          agents-sarif-file: zyrax-guard-agents.sarif          fail-on-block: "false"      - uses: github/codeql-action/upload-sarif@dd903d2e4f5405488e5ef1422510ee31c8b32357  # pin: github/codeql-action/upload-sarif@v3        with:          sarif_file: zyrax-guard-deps.sarif          category: zyrax-guard-deps      - uses: github/codeql-action/upload-sarif@dd903d2e4f5405488e5ef1422510ee31c8b32357  # pin: github/codeql-action/upload-sarif@v3        with:          sarif_file: zyrax-guard-agents.sarif          category: zyrax-guard-agents

(That job needs permissions: { security-events: write }.)

Ecosystems

Guard supports npm, PyPI, crates.io, and Go modules. Pick one with --ecosystem (default npm):

zyrax-guard check --ecosystem pypi requestszyrax-guard check --ecosystem crates serdezyrax-guard check --ecosystem gomod github.com/pkg/errorszyrax-guard scan --ecosystem crates              # PR gate over Cargo.lockzyrax-guard scan --ecosystem pypi               # PR gate over poetry.lock / requirements.txtzyrax-guard scan --ecosystem gomod              # PR gate over go.sum

Go modules are queried against proxy.golang.org (the standard Go module proxy — no auth, no download-count API). Two differences from the other ecosystems, both by design:

• Typosquat/popularity checks are skipped. Unlike npm/PyPI/crates.io, the module proxy has no download-count endpoint, so Guard has no real usage signal to compare against — it reports "download statistics unavailable" rather than fabricate a "0 downloads" typosquat verdict against a real module. Existence and known-malware (OSV) checks still run normally.
• --deep reports "no install/build scripts found" for every Go module. go get / go mod download never execute code from the fetched module — there is no npm-postinstall/pip-setup.py/cargo-build.rs analog to statically analyze.

How the checks work

Guard runs against public registry metadata only — no local execution, no installs, no sandboxing:

Transient registry/OSV failures (429 or 5xx) are retried with backoff (honoring Retry-After) before Guard gives up; only a persistent failure yields ERROR (fail closed — see Verdicts).

Deep check (--deep)

By default checks are metadata-only (milliseconds). Add --deep to also download the package's distribution artifact and statically inspect the code it runs at install/build time — npm preinstall/install/postinstall scripts, PyPI setup.py, crates build.rs (Go modules have no such hook — see Ecosystems):

zyrax-guard check --deep some-pkgzyrax-guard scan --deep                          # PR gate, deep mode

It flags red-flag patterns — network calls, process spawning, base64/obfuscated eval — and BLOCKs on dangerous combinations (e.g. "download a script and run it"). It runs no code (purely static) and is best-effort: if the artifact cannot be fetched you get an informational note, never a false block.

Zero added dependencies — the extractor uses stdlib archive/tar + compress/gzip only.

Verdicts

Guard fails closed: if it cannot reach the registry or the malware database, it returns ERROR and exits non-zero rather than letting an unverified package through. Disrupting the network cannot silently bypass the gate.

Configuration

Zyrax Guard is configured entirely through command flags and an optional local policy file — no config file or environment variables required.

Commands

Flags

Local policy file

zyrax-guard allow <name> [--reason "why"] records decisions in .zyrax/policy.json at the project root. Every allow is timestamped (UTC); a reason is optional but recorded alongside it when given, so a teammate reviewing the diff sees why a package was trusted, not just its name:

{  "allow": [    "my-internal-pkg",    { "name": "graphifyy", "reason": "reviewed setup.py — FP on tree-sitter-bash", "at": "2026-07-23T15:00:00Z" }  ],  "deny": ["known-bad-pkg"]}

Both forms are accepted on load — a bare string is still a valid entry, so files written before reason/at existed keep working unchanged.

Allowlisted packages skip checks; denylisted packages always BLOCK. Commit the file to share policy across a team. (Org-wide policy is a paid drop-in via the Policy seam.)

Guard deliberately does not offer an inline "block or continue?" prompt at check time: an AI agent driving the CLI could auto-answer such a prompt, and non-interactive contexts (CI, scripts) can't answer one at all. allow requires a separate, deliberate command — outside whatever automated loop hit the BLOCK — and leaves a reviewable trail in git.

Exit codes

See Verdicts for package verdict meanings.

Make it automatic — shell hook

The shell hook intercepts npm install / pip install / cargo add / go get transparently. Every new package gets checked before the real installer runs; already-installed and non-install commands pass through untouched.

macOS / Linux (bash or zsh)

Add to ~/.bashrc, ~/.zshrc, or ~/.bash_profile:

# Gate npm installs (default)eval "$(zyrax-guard init bash)"
# Gate pip installseval "$(zyrax-guard init bash pip)"
# Gate cargo addeval "$(zyrax-guard init bash cargo)"
# Gate go geteval "$(zyrax-guard init bash go)"

Apply immediately without restarting your terminal:

source ~/.zshrc        # or ~/.bashrc

Windows (PowerShell)

Add to your PowerShell profile ($PROFILE). To find and open it:

notepad $PROFILE      # creates the file if it doesn't exist

Add this line and save:

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

Apply immediately:

. $PROFILE

From now on every npm install, pip install, cargo add, or go get in a PowerShell window is automatically checked before anything installs.

Using with AI coding agents

Register zyrax-guard mcp as an MCP server and your agent gains a scan_agents tool to audit the configs it's about to act on — and a check_package tool it calls before every install (AI agents hallucinate package names; attackers pre-register them as malware, and Guard breaks that chain).

One-step register (recommended):

zyrax-guard mcp install            # writes ./.mcp.json for this projectzyrax-guard mcp install --global   # registers globally with Claude Code (user scope)

mcp install writes a standard .mcp.json (read by Claude Code, Cursor, and VS Code) and auto-detects whether to register zyrax-guard mcp (binary on PATH) or npx -y zyrax-guard mcp. Override with --command binary|npx. --global delegates to claude mcp add -s user (it prints the manual command if the claude CLI isn't installed).

Manual one-liner (Claude Code):

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

→ MCP setup for Claude Code, Cursor, Windsurf, VS Code, and Continue.dev

Guard is on the official MCP registry as io.github.tiagosilva07/zyrax-guard — register it in one line with npx -y zyrax-guard mcp.

Using in CI

Gate pull requests so a malicious or hallucinated dependency fails the build. The GitHub Action is the quickest path; zyrax-guard scan recipes for GitHub Actions, PyPI, crates.io, and Go modules live in the CI guide.

→ CI recipes (GitHub Actions PR gate, PyPI, crates.io, Go modules)

Privacy promise

Only the public package names you query leave your machine, as read-only lookups against public registry APIs:

• registry.npmjs.org — existence and metadata
• api.npmjs.org — download counts
• proxy.golang.org — Go module existence and version metadata
• api.osv.dev — known advisories
• registry.npmjs.org — Guard's own latest version (update check, ≤1×/day; disable with ZYRAX_NO_UPDATE_CHECK=1)
• github.com — only when you run zyrax-guard upgrade (downloads the signed release binary)

No telemetry. No account. No secrets sent anywhere. The binary is reproducible (-trimpath), and every release ships SLSA L3 provenance so you can verify the build chain yourself.

Free & open source

Zyrax Guard is MIT-licensed and free — the agent-config auditor (scan-agents + the scan_agents MCP tool), every package check, the PR gate with JSON/SARIF output, the check_package MCP tool, and the shell hook. Read the code and verify the binary yourself.

A Zyrax platform for teams (organization-wide policy, continuous monitoring, dashboards, and audit/compliance reporting) is in development — learn more at zyrax.io.

Roadmap

The roadmap items drop in via the existing Ecosystem, ThreatIntel, Policy, and Reporter seams — no re-architecting required.

License

MIT — see LICENSE.