Policy & allowlist

The policy file is the org allowlist: which MCP servers devs may load, what gets escalated, and which tool-call patterns the runtime guards deny. It is plain JSON, designed to be committed to the repo and reviewed like code.

The policy file

The CLI and harness guards walk up from the working directory looking for .ringzero/mcp-policy.json — commit one at the repo root. Point RINGZERO_MCP_POLICY (or --policy) at a shared path to distribute one policy across many repos.

Schema reference

.ringzero/mcp-policy.json

{
  "version": 1,
  "organization": "org_9f3k",
  "mode": "warn",
  "allow": [
    { "name": "github", "source": "npm:@modelcontextprotocol/server-github@*", "requirePinned": true },
    { "source": "https://mcp.linear.app/*" },
    { "source": "npm:@acme-internal/*" }
  ],
  "runtime": {
    "blockUnapproved": false,
    "dangerousPatterns": [
      { "id": "acme-secrets-path", "pattern": "/etc/acme/secrets", "action": "deny" }
    ],
    "disableBuiltinPatterns": []
  },
  "audit": { "enabled": true, "dir": null, "logArgs": false }
}

Field	Meaning
version	Schema version — currently 1; bumps only on breaking change
organization	Your org id (org_…, Settings → General). Not a secret — attribution for scans and usage records
mode	warn (report, never gate/block) or enforce (unapproved servers gate scans; runtime guards may deny)
allow[]	The allowlist — see matching rules
runtime.blockUnapproved	In enforce mode, let harness guards deny calls to unapproved servers
runtime.dangerousPatterns[]	Org-specific regexes matched against tool-call arguments
runtime.disableBuiltinPatterns[]	Built-in pattern ids to turn off
audit.enabled	Write usage records (default true)
audit.dir	Audit log directory override
audit.logArgs	Include redacted raw args in records (default false — hashes only)

Caution

The org id belongs here; the API key never does. Keys stay in RINGZERO_API_KEY — the policy file is committed, distributed, and readable by everyone.

Bootstrapping: propose → review → allow

1. Generate a proposal from what’s actually configured today:

   ringzero-mcp init

   Every discovered server becomes a proposed allow entry in .ringzero/mcp-policy.json.

2. Review the proposals like a PR. Delete entries you don’t recognize, narrow overly-broad sources, add requirePinned to anything supply-chain-sensitive. A slack-mpc in the proposal list is exactly the thing this review exists to catch.

3. Commit the file and run ringzero-mcp scan — anything added later shows up as an Unapproved server finding until it goes through the same review.

Warn vs enforce

	warn	enforce
Scan: unapproved server	Reported, doesn’t gate	Reported, gates exit 1
Runtime: dangerous pattern	Audited as warn	Denied
Runtime: unapproved server	Audited as warn	Denied when blockUnapproved: true

Start in warn, watch ringzero-mcp audit report for a week, then flip to enforce. RINGZERO_MCP_MODE overrides the file per-environment (e.g. enforce in CI only), and RINGZERO_MCP_DISABLE=1 is the per-dev kill switch (everything allowed, still audited).

Org control levels

When your org distributes a registry catalog, it may carry an org-wide control level — a single dial the org Owner sets in the RingZero dashboard (MCP registry page) that overrides the policy file’s mode:

Level	Runtime: unapproved server	Runtime: dangerous pattern	Scan
open	Allowed — recorded in the audit log with rule: unapproved-server, no warning	Warned	Unchanged
monitored	Warned (same as warn mode)	Warned	Unchanged
strict	Denied unless the server is in the registry catalog or the policy allowlist	Denied	Unapproved-server findings gate

Under strict, enabled catalog entries count as approved at runtime (exact name, plus source match where the harness knows it) — the catalog is the allowlist, and it works even in repos with no policy file at all.

Precedence (highest wins): RINGZERO_MCP_DISABLE=1 → RINGZERO_MCP_MODE (also accepts open | monitored | strict; the legacy warn/enforce tokens keep their policy-file semantics) → catalog controlLevel → policy-file mode → default warn. Repos that never pull a catalog keep pure policy-file behavior.

Matching rules

Allow entries match a server when its source matches the source glob, optionally narrowed by a name glob:

• Glob dialect (same as the Gradle plugin): * matches within a segment — never across /. No **, no ?.
• npm:@modelcontextprotocol/server-github@* — any version of the official GitHub server.
• https://mcp.linear.app/* — any single path segment under the vendor’s official MCP domain.
• npm:@acme-internal/* — every package in your internal scope.
• requirePinned: true escalates that server’s Unpinned version finding to gating regardless of --fail-on — approved-but-floating is still a supply-chain hole.

Tip

Give entries a name when you plan to enforce at runtime: the Claude Code hook only knows the server’s configured name, so name-less entries cannot be matched there. The OpenCode plugin knows sources and matches either way.

Registry entries are pre-approved

Servers managed by the MCP Registry count as approved automatically — a server matching a catalog entry (name + source) never raises Unapproved server, so you don’t duplicate allow entries for anything the org distributes. The policy still governs everything the registry doesn’t manage, plus all runtime rules. ringzero-mcp init skips proposing allow entries for registry-covered servers.

Runtime rules: dangerous patterns

Harness guards match tool-call arguments against these patterns — the data-exfiltration and destructive-command net. Built-ins (disable by id via disableBuiltinPatterns):

Id	Catches
curl-pipe-sh	Download-and-execute: curl … | sh
rm-rf-root	Recursive deletion of /, ~, $HOME
ssh-key-read	Reads under ~/.ssh/, id_rsa/id_ed25519
env-exfil	Environment dumps piped to network tools
base64-env	Env or .env content piped through base64 (encode-then-exfil)
reverse-shell	nc -e, /dev/tcp/, bash -i >&
dotenv-post	.env files in upload/POST bodies

Org-specific patterns are regexes with a stable id (shown in audit records and deny reasons) matched case-insensitively against the JSON-stringified tool arguments.

Validating

ringzero-mcp validate

Checks schema shape, glob syntax, duplicate entries, unknown keys, and regex validity. Exit 1 lists every problem; wire it into pre-commit or CI next to scan.

Org-managed central allowlist

The MCP Registry catalog is the org-managed allowlist for everything it distributes — propose → review → allow as a PR to .ringzero/mcp-registry.json. Managing it in the RingZero dashboard (per-repo overrides, review workflows, GET /v1/mcp/servers as the org-wide inventory) is a platform feature Coming soon; today the catalog and policy files in git are the review workflow.