Registries

A registry source is a fetchable manifest of skills and/or MCP servers that DefenseClaw ingests on demand. Public catalogs (clawhub, smithery, skills.sh), internal HTTPS YAMLs / JSONs, git repos, and on-disk YAMLs are all supported. Synced entries flow through the existing skill / MCP scanners; clean ones land in asset_policy.{skill,mcp}.registry so a later admission decision can say "approved by registry:<id>" instead of "approved by an unattributed rule someone wrote in 2024."

1asset_policy:2  skill:3    registry:4      workspace-helper@1.2.0:5        action: allow6        reason: registry:internal-catalog11asset_policy:2  skill:3    registry:4      workspace-helper@1.2.0:5        action: allow6        reason: registry:internal-catalog1

What you just saw

An on-demand registry sync verified source integrity, routed an entry through its existing scanner, and selected a deterministic outcome: promote a clean entry, hold a warning for review, or deny an unknown asset when registry_required=true. Stored sync settings do not create a runtime poller.

The seven registry kinds

Three worked examples

defenseclaw registry add corp-skills \
  --kind http_yaml \
  --url https://catalog.corp.example.com/skills.yaml \
  --content skill \
  --auth-env CORP_CATALOG_TOKEN \
  --non-interactive

export CORP_CATALOG_TOKEN="$(vault kv get -field=token kv/defenseclaw/catalog)"
defenseclaw registry test corp-skills              # dry-run: fetch + parse, no writes
defenseclaw registry sync corp-skills              # fetch + scan + promote

defenseclaw registry add smithery-public \
  --kind smithery \
  --content mcp \
  --non-interactive

defenseclaw registry sync smithery-public

defenseclaw registry add clawhub \
  --kind clawhub \
  --content skill \
  --non-interactive

defenseclaw registry sync clawhub

All twelve subcommands

The lifecycle of an entry

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 --enforce

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 require alone blocks nothing and 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>.registry follows that rule.
• An asset whose name does not match any rule falls through to the configured registry_empty_action (default deny).
• An empty registry list with require=on blocks every asset of that class by default until the next sync populates it. Setting registry_empty_action: warn or allow relaxes only this empty-registry gate and falls through to the type default; warn is non-blocking. The CLI warns you in colour when you flip require=on against 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

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)          2026-10-03T04:25:28Z   /tmp/corp-mcp.yaml

  ENTRIES column: total (clean/warning/blocked)

  Entries for corp-mcp
  --------------------
  NAME                             TYPE   STATUS     SEV      A/R
  -------------------------------- ------ ---------- -------- ---
  context7                         mcp    pending    -        --
  filesystem                       mcp    pending    -        --

ENTRIES reads total, then clean, warning and blocked 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 skill

approve 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

Today, syncing is on demand: scheduled sync is not available yet, and add / edit refuse --auto-sync and --sync-interval-hours. Run registry sync --all on a schedule (cron, a systemd timer or a CI schedule) until scheduled sync ships in a future release.

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 --all

Keep the gateway running: registry sync records an audit event and exits with an error when the gateway is unavailable. Use the full path to defenseclaw if cron's PATH does not include it.

Common gotchas

Reference

• cli/defenseclaw/commands/cmd_registry.py — every subcommand, validator, and the lifecycle helpers.
• cli/defenseclaw/registries/ — adapters, manifest schema, sync engine, promotion rules.
• Reference → CLI — full CLI catalog.
• Skill scanner and MCP scanner — what the scanners look at when verdicts get computed.
• Policies — how asset_policy decisions blend with repo policies and the LLM judge.