bezoar

The open-source security scanner for the AI-agent supply chain — skills, MCP servers, plugins, subagents, and CLI add-ons across every major agent platform.

Bezoar: the legendary stone believed to neutralize any poison. This one neutralizes poisoned agent add-ons.

bezoar scan audits an add-on before it enters your agent's context: static detectors, four verdict bands, and a policy layer that turns those bands into decisions. Think npm audit for agent add-ons — offline-first, deterministic, CI-friendly, SARIF/JSON output.

1.0.0a2 ships the scanner, CLI, SARIF/JSON reporters, GitHub Action, and web console. The commands below and the guides in docs/ describe that shipped surface.

60-second quickstart

Requires Python ≥ 3.11.

# From this checkout (works before PyPI)
uv tool install .

# After the 1.0.0a2 tag is published
# uv tool install bezoar==1.0.0a2

bezoar version
bezoar scan tests/corpus/benign/claude_code/skill-markdown-lint --fail-on unsafe

Point bezoar scan at any skill directory or repo root. Flags: --format text|json|sarif (reports go to stdout; there is no --output), --fail-on, --config, --changed-since, --baseline. Exit 0 = gate passed, 1 = band ≥ --fail-on, 2 usage, 3 incomplete, 4 internal.

See Getting started for reading findings.

Illustrative text report

The live text reporter prints a band table, then per-component rows. The excerpt below is the finding shape: band is a fact; decision is policy; locations are raw file:line:column; rule ids use <family>/<rule>.

✗  band=malicious  decision=block  components=1  findings=4

generic:skill:pdf-optimizer@<hash12>  malicious → block  (band_default)

  [critical] harness_forgery/control-tag-close      SKILL.md:16:1  [hidden]
             Close of a trusted harness wrapper — the breakout primitive
             evidence: </system-reminder>

  [    high] harness_forgery/control-tag-open       SKILL.md:17:1  [hidden]
             Open of a reminder-role control tag with an imperative body
             evidence: <system-reminder priority="critical">

  [    high] harness_forgery/prose-terminator       SKILL.md:22:1  [hidden]
             Prose-form function-end marker (semantic escape)
             evidence: [Function results halted by user]

  [critical] prompt_injection/instruction-override  SKILL.md:27:1
             Instruction-override language
             evidence: Ignore all previous instructions

--format json and --format sarif are the stable machine interfaces. JSON/SARIF are byte-identical across runs (modulo stats.duration_ms).

Bands and decisions

Band is a fact about the component. Decision is what the org does. No exception, pin, baseline, or vendor trust rewrites a band.

Four bands, four decisions. The three enforcement outcomes people quote (allow / alert / block) are the same table: allow_with_notice is the fourth decision — allow, but surface the risk. Capability-only findings (permissions, unpinned-only supply-chain, metadata) cap the band at potential_risk unless an intent-bearing finding corroborates them. Details: Policy.

Why bezoar

Enterprises deploy coding agents with no seatbelt. Skills and MCPs are executable supply-chain artifacts that load straight into an agent's context. Public scanners catch generic jailbreak phrases and leaked keys; they miss the class that actually steers the model — harness-envelope forgery (content impersonating the host harness's own control syntax). bezoar maps findings to the OWASP Agentic Skills Top 10 and adds that missing family. See Harness-envelope forgery.

A default scan performs no network requests and never executes scanned artifacts. Same inputs → same JSON/SARIF.

Comparison

Public posture as of 2026-09. “Harness-envelope forgery” means a first-class, per-platform vocabulary of harness control syntax plus structural-sequence matchers — not generic “ignore previous instructions” or “system message” regexes.

invariantlabs-ai/mcp-scan now redirects into Snyk agent-scan; the column reflects the historical Invariant CLI that still appears in comparisons. AIR is the commercial category reference — see FAQ.

Docs

Web console

The console never computes security facts — it renders bezoar.scan/v1 JSON from the CLI.

• Viewer: open the static export (console/apps/web/out/index.html or bezoar_console.dist_path() after pip install bezoar-console). Drag-drop a JSON report; it stays in IndexedDB. SARIF is rejected — re-scan with --format json.
• Serve: bezoar serve (loopback + /api/v1). Needs the console extra:

pip install 'bezoar[console]'   # bezoar-console==1.0.0a2
bezoar serve

Details: docs/console.md.

Self-host the console — enterprise features are a config file

Everything the AI-agent security vendors charge enterprise prices for — SSO, role-based access, a tamper-evident audit log, retention — ships in bezoar as optional YAML. No SKU, no sales call, no per-seat pricing. One container, one volume, Apache-2.0.

# docker compose (any VPS)
curl -fsSLO https://raw.githubusercontent.com/IsmailKharoub/bezoar/v1.0.0a3/deploy/compose/docker-compose.yml
BEZOAR_SERVE_TOKEN="$(openssl rand -hex 32)" docker compose up -d
# → http://127.0.0.1:8080  (add the `tls` profile + BEZOAR_DOMAIN for HTTPS via Caddy)

# Fly.io
fly launch --from https://github.com/IsmailKharoub/bezoar --no-deploy
fly secrets set BEZOAR_SERVE_TOKEN="$(openssl rand -hex 32)" && fly deploy

Then turn on the "enterprise" bits by editing bezoar-serve.yml:

auth:
  mode: oidc
  oidc: { issuer: https://login.example.com, client_id: bezoar, client_secret_file: /run/secrets/oidc }
  roles:
    default: viewer
    groups: { admin: [security-leads], editor: [security-eng] }
audit: { enabled: true }
retention: { reports: { max_age_days: 180 } }

Default posture is unchanged: bezoar serve still binds loopback with a random bearer token and touches no network. Every feature above is opt-in. → Self-hosting

GitHub Action

# permissions: { contents: read, security-events: write }
- uses: IsmailKharoub/bezoar@v1.0.0a2
  with:
    path: .
    fail-on: malicious
    upload-sarif: true

The Action always writes bezoar.sarif from bezoar scan --format sarif (stdout; the CLI has no --output), uploads it to Code Scanning when upload-sarif is true — including after a failed gate — then re-raises the CLI exit code.

License

Apache-2.0. Rule-pack pattern attributions (gitleaks) are in NOTICE and src/bezoar/data/NOTICE.