zyrax-guard

# Zyrax Guard

[![CI](https://github.com/tiagosilva07/zyrax-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/tiagosilva07/zyrax-guard/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Go Report Card](https://goreportcard.com/badge/github.com/tiagosilva07/zyrax-guard)](https://goreportcard.com/report/github.com/tiagosilva07/zyrax-guard)
[![Website](https://img.shields.io/badge/website-zyrax.io-2cc9da)](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):**

```bash
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 <pkg>` to vet a package.
Full install options (signed binary, `curl|sh`) and verification are below.

🌐 **Homepage:** [zyrax.io](https://zyrax.io)

---

## Install

### npm / npx

```bash
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)

```bash
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)

```powershell
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)

```bash
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+)

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

### Signed release binary

Download from [Releases](https://github.com/tiagosilva07/zyrax-guard/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:

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

### Build from source

```bash
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:

```bash
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](https://github.com/tiagosilva07/scoop-zyrax) 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

```bash
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

```bash
zyrax-guard check lodash                          # npm (default)
zyrax-guard check requests --ecosystem pypi       # PyPI
zyrax-guard check serde --ecosystem crates        # crates.io
```

### Check-then-install

```bash
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)

```bash
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

```bash
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.

```bash
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-al