Zyrax Guard

Zyrax Guard

[](https://github.com/tiagosilva07/zyrax-guard/actions/workflows/ci.yml) [](LICENSE) [](https://goreportcard.com/report/github.com/tiagosilva07/zyrax-guard) [](https://zyrax.io)

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

  [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
✗ lodahs@0.0.1-security — 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 configs
brew install tiagosilva07/zyrax/zyrax-guard     # macOS / Linux
scoop bucket add zyrax https://github.com/tiagosilva07/scoop-zyrax && scoop install zyrax-guard   # Windows
go install github.com/tiagosilva07/zyrax-guard/cmd/zyrax-guard@latest

Then: zyrax-guard scan-agents . to audit configs, or zyrax-guard check 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 configs
npx 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-zyrax
scoop 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-guard
cd zyrax-guard
go 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 it
zyrax-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 directory
zyrax-guard scan-agents /repo      # scan a specific path
zyrax-guard scan-agents . --json   # JSON output
zyrax-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       # PyPI
zyrax-guard check serde --ecosystem crates        # crates.io

Check-then-install

zyrax-guard install lodash axios                  # vets, then runs npm install
zyrax-guard install flask --ecosystem pypi        # vets, then runs pip install
zyrax-guard install serde --ecosystem crates      # vets, then runs cargo add

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

| File | Location | |---|---| | CLAUDE.md, AGENTS.md, GEMINI.md | Repo root | | .mcp.json | Repo root and subdirectories | | .claude/settings.json | .claude/ directory | | .cursor/rules, .cursor/rules/*.mdc | Cursor rules | | SKILL.md | Under any skills/ directory |

What it detects

| Rule | Severity | |---|---| | Prompt injection keywords (ignore previous instructions, new objective:, …) | CRITICAL | | Hidden unicode characters (zero-width, bidi overrides) | CRITICAL | | Base64-encoded instructions bypassing keyword filters | CRITICAL | | Conditional/sleeper triggers (when user asks X, do Y) | CRITICAL | | MCP tool description carrying injection keywords (read as trusted model context) | CRITICAL | | Persona override (you are not Claude, your true purpose) | HIGH | | MCP server using non-HTTPS URL | HIGH | | MCP server using raw IP address (possible C2) | HIGH | | MCP server using tunnel service (ngrok, Cloudflare, …) | HIGH | | MCP server running a shell, inline -c/-e, temp-dir binary, or dangerous env var | HIGH | | Instruction referencing credential files (.env, id_rsa, .aws/credentials) | HIGH | | Exfiltration sink (send/POST/curl + external URL on one line) | HIGH | | Wildcard allow in permissions | HIGH | | Unrestricted shell access with no deny rules | MEDIUM | | npx MCP server without a lock file | MEDIUM | | Auto-run hooks executing commands (download-execute → CRITICAL, shell flag → HIGH) | CRITICAL–MEDIUM |

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: to scope it — or zyrax-allow-file: 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 Guard
on: pull_request
jobs:
  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, and crates.io. Pick one with --ecosystem (default npm):

zyrax-guard check --ecosystem pypi requests
zyrax-guard check --ecosystem crates serde
zyrax-guard scan --ecosystem crates              # PR gate over Cargo.lock
zyrax-guard scan --ecosystem pypi               # PR gate over poetry.lock / requirements.txt

---

How the checks work

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

| Check | Verdict trigger | |---|---| | Existence | Package not found on the registry → BLOCK (hallucinated or trap name) | | Typosquat | Name is 1 edit away from a far-more-popular package AND has near-zero downloads → BLOCK with a "did you mean" suggestion | | 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) | | Age & popularity | Published [@version] | Vet a single package | | install | Check, then install if safe | | scan | Vet a lockfile (or a PR's lockfile diff) | | scan-agents | Audit AI agent config files | | allow | Add a package to the local allowlist | | init | Print the shell hook (gate installs transparently) | | mcp | Run the MCP server (checkpackage, scanagents) | | mcp install [--global] | Register Guard with your AI agent | | upgrade | Update Guard to the latest release (verified) | | version [--check] | Print version; --check` checks for a newer release |

Flags

| Flag | Commands | Default | Effect | |---|---|---|---| | --ecosystem npm\|pypi\|crates | check, install, scan | npm | Target package ecosystem | | --strict | check, install, scan, scan-agents | off | Tighten failure: WARN → fail (package commands); any finding → fail (scan-agents) | | --deep | check, install, scan | off | Download + statically analyze install/build scripts | | --json | check, install, scan, scan-agents | off | JSON output | | --sarif | check, scan | off | SARIF 2.1.0 output (for code-scanning ingestion) | | --ignore-scripts | install | off | Pass --ignore-scripts through to npm | | --base | scan | — | Base lockfile to diff against (scan only added/changed deps) | | --head | scan | per-ecosystem (package-lock.json / poetry.lock, falling back to requirements.txt / Cargo.lock) | Head lockfile to scan | | --require-signature | upgrade | on | Verify the cosign signature before replacing the binary; pass --require-signature=false to accept checksum-only |

Local policy file

zyrax-guard allow records decisions in .zyrax/policy.json at the project root:

{ "allow": ["my-

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tiagosilva07](https://github.com/tiagosilva07)
- **Source:** [tiagosilva07/zyrax-guard](https://github.com/tiagosilva07/zyrax-guard)
- **License:** MIT
- **Homepage:** https://zyrax.io

Install and usage instructions live in the source repository linked above.