{
  "markdown": "# Zyrax Guard\n\n[![CI](https://github.com/tiagosilva07/zyrax-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/tiagosilva07/zyrax-guard/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Go Report Card](https://goreportcard.com/badge/github.com/tiagosilva07/zyrax-guard)](https://goreportcard.com/report/github.com/tiagosilva07/zyrax-guard)\n[![Website](https://img.shields.io/badge/website-zyrax.io-2cc9da)](https://zyrax.io)\n\n**Audit your AI agent configs before you run them.**\nCatch the prompt injection, malicious MCP servers, and credential-exfil hiding in the\nfiles that steer your AI — `CLAUDE.md`, `.mcp.json`, agent settings, skills — and vet the\npackages they pull in. In milliseconds. Nothing leaves your machine.\n\n```\n$ zyrax-guard scan-agents .\n\nScanning . for agent config files...\n  Found 2 file(s): .mcp.json, CLAUDE.md\n\n  SCAN REPORT · zyrax-guard v0.13.0\n  2 finding(s) requiring review\n\n  [1 CRITICAL]  [1 HIGH]\n\n  [HIGH]  .mcp.json\n           MCP server 'data-exfil' uses non-HTTPS URL: http://attacker.example.com/collect\n           → Use HTTPS for all external MCP server URLs.\n\n  [CRITICAL]  CLAUDE.md:3\n           Prompt injection keyword detected: 'ignore previous instructions'\n           → Remove or review this instruction. Triage as false positive if intentional.\n\n  2 finding(s) — 1 CRITICAL, 1 HIGH\n\n$ zyrax-guard check lodahs\n✗ lodahs@0.0.1-security — BLOCK\n  - looks like a typo of \"lodash\" (far more popular); this name has only 46 weekly downloads\n  - MAL-2025-25502: Malicious code in lodahs (npm)\n  did you mean: lodash\n  to override:  zyrax-guard allow lodahs\n```\n\nWorks locally, in CI, and as a gate for AI coding agents. No account required. Nothing\nphones home except the public package name you are querying.\n\n**Get it (pick one):**\n\n```bash\nnpx zyrax-guard@latest scan-agents .            # no install — audit this repo's agent configs\nbrew install tiagosilva07/zyrax/zyrax-guard     # macOS / Linux\nscoop bucket add zyrax https://github.com/tiagosilva07/scoop-zyrax && scoop install zyrax-guard   # Windows\ngo install github.com/tiagosilva07/zyrax-guard/cmd/zyrax-guard@latest\n```\n\nThen: `zyrax-guard scan-agents .` to audit configs, or `zyrax-guard check <pkg>` to vet a package.\nFull install options (signed binary, `curl|sh`) and verification are below.\n\n🌐 **Homepage:** [zyrax.io](https://zyrax.io)\n\n---\n\n## Install\n\n### npm / npx\n\n```bash\nnpx zyrax-guard@latest scan-agents .     # audit agent configs\nnpx zyrax-guard@latest check lodash      # vet a package\n```\n\nShips the prebuilt Go binary per-platform (via `optionalDependencies`) — no runtime\ndownload. Works anywhere Node 18+ is available.\n\n### Homebrew (macOS / Linux)\n\n```bash\nbrew install tiagosilva07/zyrax/zyrax-guard\n```\n\nInstalls the signed release binary (SHA-256 verified by Homebrew). Updates land via\n`brew upgrade` once a new release is published.\n\n### Scoop (Windows)\n\n```powershell\nscoop bucket add zyrax https://github.com/tiagosilva07/scoop-zyrax\nscoop install zyrax-guard\n```\n\nInstalls the signed release binary (SHA-256 verified by scoop against the manifest, whose\nhashes come from the release's signed `checksums.txt`). `zyrax-guard upgrade` detects a\nscoop install and delegates to `scoop update zyrax-guard`.\n\n### Quick install (Linux / macOS)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/tiagosilva07/zyrax-guard/main/scripts/install.sh | sh\n```\n\nDownloads the signed release binary for your OS/arch, verifies its SHA-256 against\nthe release checksums, and installs it (to `/usr/local/bin`, or `~/.local/bin` if that\nis not writable). Pin a version with `VERSION=v0.5.0`, or set `BINDIR` to choose where\nit lands. Verifies the cosign signature too when `cosign` is on your PATH.\n\n### `go install` (Go 1.23+)\n\n```bash\ngo install github.com/tiagosilva07/zyrax-guard/cmd/zyrax-guard@latest\n```\n\n### Signed release binary\n\nDownload from [Releases](https://github.com/tiagosilva07/zyrax-guard/releases).\nEvery release ships:\n\n- Pre-built binaries for linux/darwin/windows × amd64/arm64\n- `checksums.txt` (SHA-256)\n- SLSA L3 build provenance (`.cosign.bundle` per artifact)\n- SBOM (`zyrax-guard.spdx.json`)\n\nVerify a binary:\n\n```bash\ncosign verify-blob \\\n  --bundle zyrax-guard-linux-amd64.cosign.bundle \\\n  zyrax-guard-linux-amd64\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/tiagosilva07/zyrax-guard\ncd zyrax-guard\ngo build -o zyrax-guard ./cmd/zyrax-guard\n```\n\n---\n\n## Updating\n\nGuard checks for a newer release at most once a day (a read-only lookup of its own version\non `registry.npmjs.org`) and prints a one-line notice on stderr when one is available. To\nupdate:\n\n```bash\nzyrax-guard upgrade          # detects how Guard was installed and updates it\nzyrax-guard version --check  # force a version check now\n```\n\n`upgrade` delegates to your package manager (`npm`/`brew`/`scoop`/`go`) when Guard was installed\nthat way; for `curl|sh` / standalone-binary installs on Linux/macOS it downloads the signed release,\n**verifies its SHA-256 against `checksums.txt` and its keyless cosign signature before replacing\nthe binary** (any mismatch aborts the upgrade). Signature verification is **required by default**\n— if `cosign` is not installed the upgrade aborts with instructions; pass\n`--require-signature=false` to accept checksum-only verification explicitly. On Windows, install\nvia [scoop](https://github.com/tiagosilva07/scoop-zyrax) to get delegated upgrades; the standalone\nWindows binary is still upgraded manually (the notice links to Releases).\nDisable the daily check with `ZYRAX_NO_UPDATE_CHECK=1`.\n\n---\n\n## Quickstart\n\n### Audit AI agent configs\n\n```bash\nzyrax-guard scan-agents .          # scan current directory\nzyrax-guard scan-agents /repo      # scan a specific path\nzyrax-guard scan-agents . --json   # JSON output\nzyrax-guard scan-agents . --strict # exit 1 for any finding (not just CRITICAL/HIGH)\n```\n\nScans `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.mcp.json`, `.claude/settings.json`,\nand Cursor rules files. Exits 1 if any CRITICAL or HIGH finding is found.\n\n### Check a single package\n\n```bash\nzyrax-guard check lodash                              # npm (default)\nzyrax-guard check requests --ecosystem pypi           # PyPI\nzyrax-guard check serde --ecosystem crates            # crates.io\nzyrax-guard check github.com/pkg/errors --ecosystem gomod  # Go modules\n```\n\n### Check-then-install\n\n```bash\nzyrax-guard install lodash axios                      # vets, then runs npm install\nzyrax-guard install flask --ecosystem pypi            # vets, then runs pip install\nzyrax-guard install serde --ecosystem crates          # vets, then runs cargo add\nzyrax-guard install github.com/pkg/errors --ecosystem gomod  # vets, then runs go get\n```\n\n### Allow a package (add to local policy)\n\n```bash\nzyrax-guard allow my-internal-pkg\n# allowed \"my-internal-pkg\" (recorded in .zyrax/policy.json)\n```\n\nCommit `.zyrax/policy.json` — it is the reviewable allowlist for your project.\n\n### Scan a PR's lockfile diff\n\n```bash\nzyrax-guard scan --base /tmp/base-lock.json --head package-lock.json --sarif\n```\n\nEmits SARIF 2.1.0 to stdout. Exit code 0 if no BLOCK or ERROR; non-zero otherwise.\nAdd `--strict` to treat WARN as failure.\n\n---\n\n## Auditing AI agent configs (`scan-agents`)\n\nAI coding agents (Claude Code, Cursor, Gemini CLI) read configuration files that can be\nweaponized: a malicious `CLAUDE.md` in a repo you clone, a tampered `.mcp.json` that\npoints to an attacker's server, an MCP tool whose description hides instructions, a\n`settings.json` granting wildcard shell access, or prose that quietly steers the agent\ntoward reading `.env` and POSTing it out. Guard detects these before the agent runs.\n\n```bash\nzyrax-guard scan-agents .\n```\n\n### What it scans\n\n| File | Location |\n|---|---|\n| `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` | Repo root |\n| `.mcp.json` | Repo root and subdirectories |\n| `.claude/settings.json` | `.claude/` directory |\n| `.cursor/rules`, `.cursor/rules/*.mdc` | Cursor rules |\n| `SKILL.md` | Under any `skills/` directory |\n\n### What it detects\n\n| Rule | Severity |\n|---|---|\n| Prompt injection keywords (`ignore previous instructions`, `new objective:`, …) | CRITICAL |\n| Hidden unicode characters (zero-width, bidi overrides) | CRITICAL |\n| Base64-encoded instructions bypassing keyword filters | CRITICAL |\n| Conditional/sleeper triggers (`when user asks X, do Y`) | CRITICAL |\n| MCP tool description carrying injection keywords (read as trusted model context) | CRITICAL |\n| Persona override (`you are not Claude`, `your true purpose`) | HIGH |\n| MCP server using non-HTTPS URL | HIGH |\n| MCP server using raw IP address (possible C2) | HIGH |\n| MCP server using tunnel service (ngrok, Cloudflare, …) | HIGH |\n| MCP server running a shell, inline `-c`/`-e`, temp-dir binary, or dangerous env var | HIGH |\n| Instruction referencing credential files (`.env`, `id_rsa`, `.aws/credentials`) | HIGH |\n| Exfiltration sink (`send`/`POST`/`curl` + external URL on one line) | HIGH |\n| Wildcard `allow` in `permissions` | HIGH |\n| Unrestricted shell access with no deny rules | MEDIUM |\n| `npx` MCP server without a lock file | MEDIUM |\n| Auto-run hooks executing commands (download-execute → CRITICAL, shell flag → HIGH) | CRITICAL–MEDIUM |\n\nExit code: `1` if any CRITICAL or HIGH finding; `0` otherwise. Use `--strict` for exit `1` on any finding.\n\n**Obfuscation-normalized.** Before matching, detection normalizes common disguises — zero-width and\nformat characters, homoglyphs, full-width and leetspeak substitutions, and separator/line splitting —\nso trivially obscured payloads (`y0u 4r3 n0w…`, `ignore—previous—instructions`, Cyrillic look-alikes)\nare still caught. It stays a fast, deterministic, on-device guardrail for **known** agent-config\nattack patterns — not a complete defense against a determined adversary who paraphrases or writes in\nanother language. Semantic detection is a roadmap item for the Zyrax platform, not the local CLI.\n\n**Suppressing a legitimate collision.** A real skill or config can legitimately phrase something the\nheuristics flag (e.g. a reviewer skill that says \"act as a senior reviewer\"). Silence it with an\ninline `zyrax-allow` comment on that line — optionally `zyrax-allow: <rule-prefix>` to scope it — or\n`zyrax-allow-file: <rule-prefix>` for a whole file. Suppression is **never silent**: the scan always\nreports `N finding(s) suppressed by zyrax-allow`, and **`--strict` ignores suppressions entirely**\n(audit/CI mode), so a hostile config can't use the directive as a kill switch.\n\n### In CI\n\n```yaml\n- name: Audit agent configs\n  run: zyrax-guard scan-agents . --strict\n```\n\n### Via MCP (`scan_agents` tool)\n\nOnce registered as an MCP server, agents also have access to `scan_agents`:\n\n```json\n{\n  \"name\": \"scan_agents\",\n  \"arguments\": { \"dir\": \".\" }\n}\n```\n\n---\n\n## GitHub Action\n\nGate every pull request. By default (`scan: both`) Zyrax Guard audits AI agent configs\n(prompt injection, malicious MCP servers, risky permissions) **and** gates dependencies\nadded in the PR, failing the check if anything is blocked. Add\n`.github/workflows/zyrax-guard.yml`:\n\n> **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.\n\n```yaml\nname: Zyrax Guard\non: pull_request\njobs:\n  guard:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # pin: actions/checkout@v5\n        with:\n          fetch-depth: 0          # lets Guard diff against the PR base (added deps only)\n      - uses: tiagosilva07/zyrax-guard@v0\n        with:\n          ecosystem: npm          # npm | pypi | crates\n```\n\nOn a pull request it scans only the dependencies added versus the base branch; otherwise\nit scans the whole lockfile. The job fails when a dependency is blocked. `@v0` tracks the\nlatest 0.x release; pin an exact version (e.g. `@v0.7.1`) for fully reproducible CI.\n\n**Inputs** (all optional): `scan` (`deps | agents | both`, default `both`), `ecosystem`\n(default `npm`), `lockfile` (default per-ecosystem), `base` (explicit base lockfile),\n`strict` (treat WARN as failure), `deep` (inspect install scripts), `version` (Guard\nrelease, default `latest`), `fail-on-block` (default `true`), `sarif-file` (write\ndependency SARIF for Code Scanning), `agents-sarif-file` (write agent-config SARIF for\nCode Scanning), `args` (extra raw flags).\n\nUpload results to **GitHub Code Scanning** so findings show up inline on the PR:\n\n```yaml\n      - uses: tiagosilva07/zyrax-guard@v0\n        with:\n          sarif-file: zyrax-guard.sarif\n          fail-on-block: \"false\"   # let Code Scanning surface findings; don't hard-fail\n      - uses: github/codeql-action/upload-sarif@dd903d2e4f5405488e5ef1422510ee31c8b32357  # pin: github/codeql-action/upload-sarif@v3\n        with:\n          sarif_file: zyrax-guard.sarif\n```\n\nAudit agent configs **and** dependencies, both surfaced in Code Scanning:\n\n```yaml\n      - uses: tiagosilva07/zyrax-guard@v0\n        with:\n          scan: both\n          sarif-file: zyrax-guard-deps.sarif\n          agents-sarif-file: zyrax-guard-agents.sarif\n          fail-on-block: \"false\"\n      - uses: github/codeql-action/upload-sarif@dd903d2e4f5405488e5ef1422510ee31c8b32357  # pin: github/codeql-action/upload-sarif@v3\n        with:\n          sarif_file: zyrax-guard-deps.sarif\n          category: zyrax-guard-deps\n      - uses: github/codeql-action/upload-sarif@dd903d2e4f5405488e5ef1422510ee31c8b32357  # pin: github/codeql-action/upload-sarif@v3\n        with:\n          sarif_file: zyrax-guard-agents.sarif\n          category: zyrax-guard-agents\n```\n\n(That job needs `permissions: { security-events: write }`.)\n\n---\n\n## Ecosystems\n\nGuard supports **npm, PyPI, crates.io, and Go modules**. Pick one with `--ecosystem`\n(default `npm`):\n\n```bash\nzyrax-guard check --ecosystem pypi requests\nzyrax-guard check --ecosystem crates serde\nzyrax-guard check --ecosystem gomod github.com/pkg/errors\nzyrax-guard scan --ecosystem crates              # PR gate over Cargo.lock\nzyrax-guard scan --ecosystem pypi               # PR gate over poetry.lock / requirements.txt\nzyrax-guard scan --ecosystem gomod              # PR gate over go.sum\n```\n\nGo modules are queried against `proxy.golang.org` (the standard Go module proxy — no\nauth, no download-count API). Two differences from the other ecosystems, both\nby design:\n\n- **Typosquat/popularity checks are skipped.** Unlike npm/PyPI/crates.io, the module\n  proxy has no download-count endpoint, so Guard has no real usage signal to compare\n  against — it reports \"download statistics unavailable\" rather than fabricate a\n  \"0 downloads\" typosquat verdict against a real module. Existence and known-malware\n  (OSV) checks still run normally.\n- **`--deep` reports \"no install/build scripts found\" for every Go module.** `go get`\n  / `go mod download` never execute code from the fetched module — there is no\n  npm-postinstall/pip-setup.py/cargo-build.rs analog to statically analyze.\n\n---\n\n## How the checks work\n\nGuard runs against public registry metadata only — no local execution, no installs, no sandboxing:\n\n| Check | Verdict trigger |\n|---|---|\n| **Existence** | Package not found on the registry → **BLOCK** (hallucinated or trap name) |\n| **Typosquat** | Name is 1 edit away from a far-more-popular package AND has near-zero downloads → **BLOCK** with a \"did you mean\" suggestion |\n| **Known-bad** | OSV advisory match → known-malicious package → **BLOCK**; vulnerability in a legitimate package (any severity, shown in the message) → **WARN** (use `--strict` to fail on it) |\n| **Age & popularity** | Published < 30 days AND < 50 weekly downloads → **WARN** |\n| **Lockfile integrity** | *(scan only)* Resolved URL or integrity hash changed → **BLOCK** |\n\nTransient registry/OSV failures (429 or 5xx) are retried with backoff (honoring `Retry-After`)\nbefore Guard gives up; only a persistent failure yields **ERROR** (fail closed — see [Verdicts](#verdicts)).\n\n---\n\n## Deep check (`--deep`)\n\nBy default checks are metadata-only (milliseconds). Add `--deep` to also download the\npackage's distribution artifact and **statically inspect the code it runs at install/build\ntime** — npm `preinstall`/`install`/`postinstall` scripts, PyPI `setup.py`, crates `build.rs`\n(Go modules have no such hook — see [Ecosystems](#ecosystems)):\n\n```bash\nzyrax-guard check --deep some-pkg\nzyrax-guard scan --deep                          # PR gate, deep mode\n```\n\nIt flags red-flag patterns — network calls, process spawning, base64/obfuscated `eval` —\nand **BLOCKs** on dangerous combinations (e.g. \"download a script and run it\"). It runs\n**no code** (purely static) and is **best-effort**: if the artifact cannot be fetched you\nget an informational note, never a false block.\n\nZero added dependencies — the extractor uses stdlib `archive/tar` + `compress/gzip` only.\n\n---\n\n## Verdicts\n\n| Verdict | Meaning | Default exit code |\n|---|---|---|\n| **SAFE** | No signals worth noting | `0` |\n| **WARN** | Suspicious — review before proceeding | `0` (use `--strict` to make it `1`) |\n| **ERROR** | Guard could not verify (registry/OSV unreachable, 5xx, or rate-limited) — **fails closed** | `1` (always) |\n| **BLOCK** | Strong indicator of malicious or hallucinated package | `1` |\n\nGuard 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.\n\n---\n\n## Configuration\n\nZyrax Guard is configured entirely through command flags and an optional local\npolicy file — no config file or environment variables required.\n\n### Commands\n\n| Command | Purpose |\n|---|---|\n| `check <name>[@version]` | Vet a single package |\n| `install <name>` | Check, then install if safe |\n| `scan` | Vet a lockfile (or a PR's lockfile diff) |\n| `scan-agents <dir>` | Audit AI agent config files |\n| `allow <name>` | Add a package to the local allowlist |\n| `init` | Print the shell hook (gate installs transparently) |\n| `mcp` | Run the MCP server (`check_package`, `scan_agents`) |\n| `mcp install [--global]` | Register Guard with your AI agent |\n| `upgrade` | Update Guard to the latest release (verified) |\n| `version [--check]` | Print version; `--check` checks for a newer release |\n\n### Flags\n\n| Flag | Commands | Default | Effect |\n|---|---|---|---|\n| `--ecosystem npm\\|pypi\\|crates\\|gomod` | check, install, scan | `npm` | Target package ecosystem |\n| `--strict` | check, install, scan, scan-agents | off | Tighten failure: WARN → fail (package commands); any finding → fail (`scan-agents`) |\n| `--deep` | check, install, scan | off | Download + statically analyze install/build scripts |\n| `--json` | check, install, scan, scan-agents | off | JSON output |\n| `--sarif` | check, scan | off | SARIF 2.1.0 output (for code-scanning ingestion) |\n| `--ignore-scripts` | install | off | Pass `--ignore-scripts` through to npm |\n| `--reason <text>` | allow | — | Recorded with the allowlist entry in `.zyrax/policy.json` for later review |\n| `--base <file>` | scan | — | Base lockfile to diff against (scan only added/changed deps) |\n| `--head <file>` | scan | per-ecosystem (`package-lock.json` / `poetry.lock`, falling back to `requirements.txt` / `Cargo.lock` / `go.sum`) | Head lockfile to scan |\n| `--require-signature` | upgrade | **on** | Verify the cosign signature before replacing the binary; pass `--require-signature=false` to accept checksum-only |\n\n### Local policy file\n\n`zyrax-guard allow <name> [--reason \"why\"]` records decisions in `.zyrax/policy.json` at\nthe project root. Every `allow` is timestamped (UTC); a reason is optional but recorded\nalongside it when given, so a teammate reviewing the diff sees why a package was trusted,\nnot just its name:\n\n```json\n{\n  \"allow\": [\n    \"my-internal-pkg\",\n    { \"name\": \"graphifyy\", \"reason\": \"reviewed setup.py — FP on tree-sitter-bash\", \"at\": \"2026-07-23T15:00:00Z\" }\n  ],\n  \"deny\": [\"known-bad-pkg\"]\n}\n```\n\nBoth forms are accepted on load — a bare string is still a valid entry, so files written\nbefore `reason`/`at` existed keep working unchanged.\n\nAllowlisted packages skip checks; denylisted packages always BLOCK. Commit the file to\nshare policy across a team. (Org-wide policy is a paid drop-in via the `Policy` seam.)\n\nGuard deliberately does **not** offer an inline \"block or continue?\" prompt at check time:\nan AI agent driving the CLI could auto-answer such a prompt, and non-interactive contexts\n(CI, scripts) can't answer one at all. `allow` requires a separate, deliberate command —\noutside whatever automated loop hit the BLOCK — and leaves a reviewable trail in git.\n\n### Exit codes\n\n| Context | Exits `1` when |\n|---|---|\n| `check` / `install` / `scan` | a **BLOCK** or **ERROR** verdict — or a **WARN** with `--strict` (ERROR exits 1 regardless of `--strict`) |\n| `scan-agents` | a **CRITICAL** or **HIGH** finding — or **any** finding with `--strict` |\n\nSee [Verdicts](#verdicts) for package verdict meanings.\n\n---\n\n## Make it automatic — shell hook\n\nThe shell hook intercepts `npm install` / `pip install` / `cargo add` / `go get`\ntransparently. Every new package gets checked before the real installer runs;\nalready-installed and non-install commands pass through untouched.\n\n### macOS / Linux (bash or zsh)\n\nAdd to `~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`:\n\n```bash\n# Gate npm installs (default)\neval \"$(zyrax-guard init bash)\"\n\n# Gate pip installs\neval \"$(zyrax-guard init bash pip)\"\n\n# Gate cargo add\neval \"$(zyrax-guard init bash cargo)\"\n\n# Gate go get\neval \"$(zyrax-guard init bash go)\"\n```\n\nApply immediately without restarting your terminal:\n\n```bash\nsource ~/.zshrc        # or ~/.bashrc\n```\n\n### Windows (PowerShell)\n\nAdd to your PowerShell profile (`$PROFILE`). To find and open it:\n\n```powershell\nnotepad $PROFILE      # creates the file if it doesn't exist\n```\n\nAdd this line and save:\n\n```powershell\nInvoke-Expression (zyrax-guard init powershell | Out-String)\n```\n\nApply immediately:\n\n```powershell\n. $PROFILE\n```\n\nFrom now on every `npm install`, `pip install`, `cargo add`, or `go get` in a\nPowerShell window is automatically checked before anything installs.\n\n---\n\n## Using with AI coding agents\n\nRegister `zyrax-guard mcp` as an MCP server and your agent gains a `scan_agents` tool to\naudit the configs it's about to act on — and a `check_package` tool it calls before every\ninstall (AI agents hallucinate package names; attackers pre-register them as malware,\nand Guard breaks that chain).\n\n**One-step register (recommended):**\n\n```bash\nzyrax-guard mcp install            # writes ./.mcp.json for this project\nzyrax-guard mcp install --global   # registers globally with Claude Code (user scope)\n```\n\n`mcp install` writes a standard `.mcp.json` (read by Claude Code, Cursor, and VS Code) and\nauto-detects whether to register `zyrax-guard mcp` (binary on PATH) or `npx -y zyrax-guard mcp`.\nOverride with `--command binary|npx`. `--global` delegates to `claude mcp add -s user` (it prints\nthe manual command if the `claude` CLI isn't installed).\n\nManual one-liner (Claude Code):\n\n```bash\nclaude mcp add zyrax-guard -- npx -y zyrax-guard mcp\n```\n\n→ **[MCP setup for Claude Code, Cursor, Windsurf, VS Code, and Continue.dev](docs/mcp-integrations.md)**\n\nGuard is on the official MCP registry as `io.github.tiagosilva07/zyrax-guard` — register it\nin one line with `npx -y zyrax-guard mcp`.\n\n---\n\n## Using in CI\n\nGate pull requests so a malicious or hallucinated dependency fails the build. The\n[GitHub Action](#github-action) is the quickest path; `zyrax-guard scan` recipes for\nGitHub Actions, PyPI, crates.io, and Go modules live in the CI guide.\n\n→ **[CI recipes (GitHub Actions PR gate, PyPI, crates.io, Go modules)](docs/ci.md)**\n\n---\n\n## Privacy promise\n\nOnly the **public package names you query** leave your machine, as read-only lookups\nagainst public registry APIs:\n\n- `registry.npmjs.org` — existence and metadata\n- `api.npmjs.org` — download counts\n- `proxy.golang.org` — Go module existence and version metadata\n- `api.osv.dev` — known advisories\n- `registry.npmjs.org` — Guard's own latest version (update check, ≤1×/day; disable with `ZYRAX_NO_UPDATE_CHECK=1`)\n- `github.com` — only when you run `zyrax-guard upgrade` (downloads the signed release binary)\n\nNo telemetry. No account. No secrets sent anywhere. The binary is reproducible\n(`-trimpath`), and every release ships SLSA L3 provenance so you can verify the build\nchain yourself.\n\n---\n\n## Free & open source\n\nZyrax Guard is **MIT-licensed and free** — the agent-config auditor (`scan-agents` +\nthe `scan_agents` MCP tool), every package check, the PR gate with JSON/SARIF output, the\n`check_package` MCP tool, and the shell hook. Read the code and verify the binary yourself.\n\nA **Zyrax platform** for teams (organization-wide policy, continuous monitoring, dashboards,\nand audit/compliance reporting) is in development — learn more at **[zyrax.io](https://zyrax.io)**.\n\n---\n\n## Roadmap\n\n| Version | Item | Status |\n|---|---|---|\n| **v0.1.0** | npm CLI: `check` + PR-gate `scan` (lockfile diff) + JSON/SARIF + self-hardening CI | shipped |\n| **v0.2.0** | MCP server (`check_package`) + shell-hook (`zyrax-guard init`) | shipped |\n| **v0.3.0** | PyPI + crates.io parity across check/install/hook/MCP/scan | shipped |\n| **v0.4.x** | Deep check (`--deep`): static install/build-script analysis + overall time budget | shipped |\n| **v0.5.0** | Rebrand to Zyrax; public release | shipped |\n| **v0.6.x** | GitHub Action + Marketplace listing + `curl\\|sh` installer; floating `@v0` tag | shipped |\n| **v0.7.0** | `scan-agents`: AI agent config audit (prompt injection, MCP hosts, permissions) + Phase 2 detections (credential access, exfiltration sinks, MCP tool-description injection) | shipped |\n| **v0.8** | First-class CI surfacing for `scan-agents`: SARIF output + GitHub code-scanning upload + inline PR annotations | shipped |\n| **v0.9.0** | Update detection (daily opt-out notice + verified `upgrade`) + one-step `mcp install`; **production-readiness**: fail-closed `ERROR` verdict (network failure no longer bypasses the gate), retries/backoff, MCP panic recovery, cosign-verified upgrade, hardened CI (gitleaks/staticcheck/dependency-review); **agent-config detection hardening** (obfuscation-normalized matching, allowlist-style MCP/exec/perms, `zyrax-allow` suppression) | shipped |\n| **v0.10.0** | **Correctness & fail-closed hardening** from a full audit: npm-workspace lockfile support in `scan` (monorepos no longer crash), `install` installs the exact vetted `name@version`, `scan-agents` fails on a missing directory and reports unscannable (oversize/unreadable) configs, registry-derived text sanitized against terminal-escape/prompt injection, unknown download stats no longer read as \"0\" (no false typosquat BLOCKs), wall-clock budgets on every check entry point, **signature-verified `upgrade` by default**, `--help` exits 0 + documented exit codes, `install --json` | shipped |\n| **v0.11.x** | **Verdict policy: BLOCK is malware-only** (v0.11.0) — vulnerabilities in legitimate packages WARN at any severity (`--strict` to fail); **Windows scoop bucket** ([`scoop-zyrax`](https://github.com/tiagosilva07/scoop-zyrax)) + `upgrade` delegation, closing Windows upgrade parity | shipped |\n| **v0.12.0** | Reduce suspicious-install false positives on declarative PyPI config (signals now carry file:line evidence); advisory-only repo-context signal (GitHub stars/age/last-push — never affects the verdict); `allow --reason` with a timestamped audit trail in `.zyrax/policy.json` | shipped |\n| **v0.13.0** | **Go modules** ecosystem (`--ecosystem gomod`, `proxy.golang.org`) across check/install/hook/MCP/scan, with go.sum lockfile support | shipped |\n| **exploring** | Semantic detection layer (LLM/heuristic judge for paraphrased/non-English prompt injection) as a Zyrax-platform capability; community-curated threat intel (shared malicious-package & MCP-host feeds); more ecosystems (RubyGems) via the `Ecosystem` seam | — |\n\nThe roadmap items drop in via the existing `Ecosystem`, `ThreatIntel`, `Policy`, and\n`Reporter` seams — no re-architecting required.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 28396,
  "sha": "a204c149ea30c13db5a37bd3f36686959f6f0ebfabf21f5f06ff00da84263d6a",
  "repo_slug": "tiagosilva07/zyrax-guard",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tiagosilva07_zyrax_guard_9bfe87c9/readme"
}