Registries
Subscribe DefenseClaw to public or internal skill / MCP catalogs. Sources are fetched, scanned, and clean entries are auto-promoted into asset_policy so admission decisions can attribute the rule back to its origin.
A registry source is a fetchable manifest of skills or MCP servers. Synced entries go through the skill or MCP scanner, and clean ones are promoted into asset_policy.{skill,mcp}.registry. A registry is the approved catalog. It is not the block or allow list: those are the denied and allowed rules in Admission, and they always apply. To set one up, see Subscribe to a registry.
Guided example · Registry sync is on demand
Turn a catalog entry into an admission decision
On-demand sync verifies source integrity, routes through a scanner, and promotes, reviews, or denies a pre-authored variant.
asset_policy: skill: registry: - name: workspace-helper reason: registry:internal-catalogasset_policy: skill: registry: - name: workspace-helper reason: registry:internal-catalog
Integrity verified and scanner result is clean
Write attributed asset_policy rule
What DefenseClaw did — and did not do
What it did
- Run registry sync on demand
- Verify source integrity and route through existing scanners
- Attribute promoted rules to the registry source
What it did not do
- Poll registries automatically at runtime
- Let registry trust bypass scanner findings unless policy allows it
- Read a credential value from auth_env
What you just saw
Guided example with synthetic data. In the demo, an on-demand sync checks the source, scans an entry and promotes it because it is clean. A warning entry would be held for review, and with registry_required on an unknown asset is refused. Saved sync settings do not start a background poller.
The seven registry kinds
Prop
Type
Subscribe to a registry
Subscribe to a catalog of skills or MCP servers. DefenseClaw fetches it, scans each entry and promotes clean entries into asset_policy. A registry is the approved catalog. It does not replace your block and allow lists.
Before you start
- A catalog URL, or an absolute path to a manifest file. Kinds:
clawhub,smithery,skills_sh,http_yaml,http_json,git,file. See The seven registry kinds. - For
http_yaml,http_json,gitandfile, every entry'ssource_urlneeds a SHA-256.
Steps
-
Add the source.
--auth-envtakes the name of an environment variable that holds a token, never the token.defenseclaw registry add corp-skills --kind http_yaml --url https://catalog.example.com/skills.yaml --content skill --auth-env CORP_CATALOG_TOKEN --non-interactiveOK Registered registry source 'corp-skills'. Run `defenseclaw registry sync corp-skills` to fetch + scan + promote entries. -
Dry-run the fetch. Nothing is written.
defenseclaw registry test corp-skills -
Sync. Each entry goes through the skill or MCP scanner. Clean entries are promoted.
defenseclaw registry sync corp-skillsStdio MCP entries start the publisher's package on your machine. They stay
pendingunless you pass--scan-stdio. -
Look at what landed, then approve or reject held entries.
defenseclaw registry list defenseclaw registry entries corp-skills --status warning defenseclaw registry approve corp-skills my-skill --type skillRegistry sources ID KIND CONTENT ON ENTRIES LAST SYNC URL corp-skills file skill yes - - /path/to/m.yaml ENTRIES column: total (clean/warning/blocked/error/rejected) -
Optional: refuse anything the catalog does not list.
defenseclaw registry require --type skill --enabled --enforce--enforceturns onasset_policy.enabledand setsasset_policy.modetoaction. Without it nothing is blocked, and the CLI says so.
Undo
defenseclaw registry remove corp-skills removes the source and every rule it promoted.
All twelve subcommands
Prop
Type
The lifecycle of an entry
List view for small screens. Use the expand button to open the drawing.
- Add a sourceregistry addsaved in config.yaml
- Sync the source
- Sync the sourceregistry syncfetch the manifest
- Scan each entry
- Scan each entryskill scanner or MCP scanner
- Scan result?
- Scan result?
- cleanAdded to asset policy
- anything elseHeld for review
- Held for reviewwarning or blockederror or pending
- you approveAdded to asset policy
- you rejectNever promoted
- Never promotedstatus rejected
- Added to asset policyrule tagged registry:<id>
Promote and require — the deny-by-default story
Once entries are flowing in, asset_policy.<type>.registry_required flips the corresponding asset class to deny-by-default:
defenseclaw registry require --type skill --enabled
defenseclaw registry require --type mcp --enabled --enforceregistry_required is an asset policy rule, so unlike the denied and
allowed lists it follows enabled and mode. The requirement is enforced
only while asset policy is on: asset_policy.enabled: true and
asset_policy.mode: action. A per-user
install starts with enabled: false and mode: observe, so a require rule
does not take effect until asset policy is enabled for action; the CLI says so.
Add --enforce to turn both on in the same
save, or set them in the TUI config editor (Setup → c → Asset Policy). In
observe mode an unregistered asset is logged, not blocked. To turn
enforcement back off, run
defenseclaw registry require --type mcp --disabled --no-enforce
(--no-enforce sets mode: observe).
A registry rule that pins transport treats http and streamable-http as
the same HTTP transport, and a URL server added without --transport counts as
http.
An unscoped operation is broad operator intent: it updates the global default
and clears only the targeted registry_required override on every active
connector, so stale opposite overrides cannot keep enforcement disabled. All
other per-connector fields and the global registry rule/filter lists remain
unchanged. --connector <name> changes only that connector's explicit
override. Known but inactive connector overrides are preserved so future
activation does not silently inherit a weaker or stronger posture than the one
previously saved.
When registry_required=true:
- An asset whose name matches a rule in
asset_policy.<type>.registryfollows that rule. - An asset whose name does not match any rule falls through to the configured
registry_empty_action(defaultdeny). - An empty registry list with
require=onblocks every asset of that class by default until the nextsyncpopulates it. Settingregistry_empty_action: warnorallowrelaxes only this empty-registry gate and falls through to the type default;warnis non-blocking. The CLI warns you in colour when you fliprequire=onagainst an empty list — read the warning carefully.
The Go gateway tags every admission decision with Reason="registry:<id>" (or
"registry:operator-approved" for manually approved entries). Inspect the TUI
or run defenseclaw-gateway audit export --output - to see which catalog won;
an optional JSONL destination contains only the records its v8 route selects.
What --auth-env, --allow-private, and SHA-256 actually do
| Knob | Default | Purpose |
|---|---|---|
--auth-env <ENV> | "" | Name of an env var holding a bearer token sent on every fetch. The CLI rejects values that look like literal secrets. |
--allow-private | off | A registry test and registry sync flag (not add). Permits RFC 1918 / ULA destinations: off in production, on for an internal mirror on a private subnet. |
--scan-stdio | off | A registry sync flag. Also scans stdio MCP entries, which starts each publisher-controlled package on this machine. |
--non-interactive | off | Required for CI; missing required flags exit non-zero with a clear error: --foo is required. |
SHA-256 on source_url | required for http_yaml / http_json / git / file | Per-entry integrity; the scanner refuses to download an entry whose computed digest does not match. |
Registry fetches use the same hardened URL path in test and sync: loopback, link-local, cloud-metadata, and private-network destinations are refused by default, including DNS resolutions that rebind into a reserved range. Use --allow-private only for a registry mirror you intentionally run on an internal network. Local file registries must use absolute paths, and remote entry downloads must pass the per-entry SHA-256 check before scanner promotion can happen.
Inspect what landed
This is a real file source with two stdio MCP entries, synced without
--scan-stdio, so both entries are still pending:
Registry sources
────────────────
ID KIND CONTENT ON ENTRIES LAST SYNC URL
------------------------ ------------ -------- --- ------------------ ---------------------- ------------------
corp-mcp file mcp yes 2 (0/0/0/0/0) 2026-10-06T18:27:26Z /tmp/corp-mcp.yaml
ENTRIES column: total (clean/warning/blocked/error/rejected)
Entries for corp-mcp
────────────────────
NAME TYPE STATUS SEV A/R
-------------------------------- ------ ---------- -------- ---
context7 mcp pending - --
filesystem mcp pending - --ENTRIES reads the total, then the clean, warning, blocked, error and
rejected counts; a dash means the source was never synced. A/R shows whether
you approved or rejected an entry.
defenseclaw registry list # one row per source, with cached counts
defenseclaw registry show corp-skills # full detail + verdict summary
defenseclaw registry entries corp-skills --status warning
defenseclaw registry approve corp-skills my-skill --type skill
defenseclaw registry reject corp-skills evil-skill --type skillapprove and reject re-promote against the cached manifest immediately by default, so the new rule lands without a network round-trip. Pass --no-repromote if you want to defer the change to the next registry sync. --type is optional when the source holds one content type (--content skill or --content mcp) or the entry name exists under one type only.
Sync schedules
Syncing is on demand. Stored sync settings do not start a poller. Run registry sync --all on a schedule (cron, a systemd timer or a CI schedule).
DefenseClaw configuration is per user, so schedule the sync as the user who
runs DefenseClaw, for example in that user's crontab (crontab -e):
0 * * * * defenseclaw registry sync --allKeep the gateway running: with it stopped, registry sync still fetches, scans
and promotes, but it warns that the audit event was not recorded. Use the full
path to defenseclaw if cron's PATH does not include it.
Common gotchas
Reference
cli/defenseclaw/commands/cmd_registry.py has every subcommand and validator. cli/defenseclaw/registries/ has the adapters, manifest schema, sync engine and promotion rules. Full CLI catalog: CLI reference.
- Skill scanner and MCP scanner: what the scanners look at when verdicts are computed
- Admission and the block/allow list: the
deniedandallowedlists and the admission actions that sit beside a registry
MCP scanner
Behavioural scan of every Model Context Protocol server an agent might call. DefenseClaw wraps cisco-ai-mcp-scanner to surface hidden tool intents and shadow capabilities, takes its analyzers and judge from config.yaml, and maps each verdict through the admission policy.
AI Discovery
Find AI agents, installed local models, running model servers, MCP servers, skills, and providers on the host, and see which of them actually ran. DefenseClaw runs a continuous fingerprinting scanner and three runtime detection planes in the gateway, plus defenseclaw agent discover for an instant connector inventory.