Skip to content

feat(governance): govern which discovery registries Discover may query - #28530

Merged
bolichen97 merged 1 commit into
mainfrom
fix/12677-registries-scope
Nov 10, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/12677-registries-scope

Conversation

@dodgeblaster

@dodgeblaster dodgeblaster commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let an operator's security policy choose which skill and MCP discovery registries the Discover surfaces may query.

The Discover surfaces (Add Skill, Add MCP Server, and the agent's skill_discover) query skills.sh, the GitHub API and the official MCP registry. The policy has no key for that: a security_policy.json naming one is refused whole as an unknown governed key, and the public default admits every registry. An LTS build queries all three too, although the accepted LTS-edition RFC lists this control ("Extension sources") as off by default.

Why it matters

An enterprise deployment that must limit which registries developer machines browse (the reporter's case in #12677) cannot say so in the policy it already controls, and an LTS build reaches public registries its own RFC says stay off until the policy names them.

Not a goal

  • Governing local or manual installs (the RFC row's _local_sources half), or install itself (capabilities.extension_install already does).
  • Live revocation: invalidating the provider catalogs when the policy changes.
  • Separate keys per catalog, or a kirocrew policy validate warning when a list covers one catalog and not the other.
  • Governing where a provider's redirects go once its starting host is admitted.

What changed (motivation → approach → change)

The registry gate already existed: every provider is admitted through _shared_access.admits_registry, and a refused one is never registered. It only asked the edition's policy. The design was agreed in #12677's comments, and the key comes from the accepted LTS-edition RFC, appendix row "Extension sources". Following the maintainer review, the key ships additive: it adds no refusal main does not already make. Whether LTS should default it to off and fail closed, as the RFC row says, is proposed separately in #34006.

  • New catalog key external_access.registry_hosts (platform/governance_parts/catalog.py, listed in BASELINE_UNGATED in baseline.py): a host-matched list, like network.egress. One list covers both catalogs.
  • admits_registry asks that key first, through registry_host_denied in src/kiro_crew/extension_governance.py, on the host of the provider's base URL (never its name), then the edition's policy. The stricter wins, so an edition cannot loosen the operator's policy.
  • Without the key nothing changes, on oss or LTS: every registry is admitted, as before. An allow or deny list a policy sets narrows Discover on both.
  • A governance error on the key is logged and written to the SEL as governance_degraded, and the registry is admitted, as Discover did before the key existed. _denied gains a fail_closed switch for this; every other key keeps failing closed. A PlatformCompositionError still propagates.
  • A policy change applies at the next gateway start. The spec records this and the one-list cost.

Backwards compatibility

Not breaking. With no policy naming the key, Discover queries the same registries as on main, on oss and LTS. Writer sweep on origin/main @ f745d26: admits_registry has four callers, discover.py (skills.sh, GitHub, edition providers) and mcp_discover.py (official registry); each already drops a refused provider, so a registry a policy refuses is simply absent. A policy that names the key, which the parser refused before, now loads.

Reader: src/kiro_crew/dashboard/handlers/discover.py:_build_registry -- chat -- a refused provider is not registered, as for an edition denial | test_a_denied_registry_is_never_registered
Reader: src/kiro_crew/dashboard/handlers/mcp_discover.py:_build_registry -- chat -- same | test_a_denied_registry_is_never_registered
Reader: src/kiro_crew/mcp_tools/skills.py:skill_discover -- subagent -- goes through the gateway's discover endpoint, so it sees the same registry set | test_lts_unnamed_key_admits_every_registry

Tests

test/test_governance_registry_hosts.py: the key loads with the host matcher (flat and nested); oss and LTS without the key admit everything (skills.sh, GitHub, the official MCP registry) and write no audit; allow and deny lists by host, on oss and LTS; the host is matched, never the URL or provider name; an empty host matches only *; the stricter of edition and ceiling wins; a governance error, raised around or inside the evaluation, is logged through audit_governance_degraded and admits; a PlatformCompositionError propagates; a refused registry is never registered. test_governance_lts_baseline.py lists the key among the open scopes, so its generic tests check that an unnamed key keeps Crew's default and a policy deny still closes it.

Proof: PROVEN test/test_governance_registry_hosts.py::test_lts_unnamed_key_admits_every_registry[no-ceiling], test/test_governance_registry_hosts.py::test_lts_policy_deny_list_narrows, test/test_governance_registry_hosts.py::test_a_governance_error_is_logged_and_admits[lts] (head dabb002)

Determinism: the new file passed 20 serial repeats and an -n 4 run with its neighbours. Mutation check: putting back the LTS _OFF row fails 5 tests, and making the key fail closed fails 4.

Manual verification

N/A — unit coverage sufficient: the tests drive the real parser, baseline and both _build_registry functions; no UI changes.

Related Issues

Fixes #12677

Refs #16007 (the reporter's RFC asking whether this belongs in the public policy).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 2, 2026
@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 7d76f9ecc97248af69cf531ffc398575268da142 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 7d76f9ecc97248af69cf531ffc398575268da142 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. The key is named in the accepted LTS-edition RFC's "Extension sources" row. It is open by default in every edition, so main's defaults do not change, and all four existing admits_registry call sites use it.

What this change ships

Inventory (6 items) — 6 justified

Intent: let an enterprise operator's security policy limit which skill and MCP discovery registries Discover queries. This is an ADDITION.

  1. A security_policy.json that names external_access.registry_hosts now loads; before, the whole policy was refused — justified
  2. An allow or deny list in the policy, matched on host, narrows which registries Discover offers: skills.sh, GitHub, edition providers, the official MCP registry, and the agent's skill_discover — justified
  3. With no key in the policy, every registry is still admitted on oss and LTS, as on main — justified
  4. When governance cannot evaluate the key, the registry is admitted, and the error is logged and written to the SEL as governance_degraded — justified
  5. An edition's own external_access policy can no longer admit a registry the operator's key refuses (the stricter answer wins) — justified
  6. A policy change takes effect at the next gateway start, not immediately — justified

[FIRST-PRINCIPLES-REVIEWED] 7d76f9e

Description read

[DESCRIPTION-READ] 616296cc367fc622e74c28165aacefaac64e67a2a9fa3593564da232438e9cda

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 7d76f9ecc97248af69cf531ffc398575268da142 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The key only adds restriction: an unnamed key admits everything, as before, and it narrows Discover in the one shared gate that all four registry call sites go through.

Notes

[DESIGN-REVIEWED] 7d76f9e

Description read

[DESCRIPTION-READ] 533637047203b7bbf5e4ccc3069d2e3168b13792d7ede987f6e6d6e0ac3478a1

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 7d76f9ecc97248af69cf531ffc398575268da142 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 7d76f9e

Verdict parsed from the review's SHA-scoped output markers for commit 7d76f9ecc97248af69cf531ffc398575268da142.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 7d76f9ecc97248af69cf531ffc398575268da142 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 7d76f9ecc97248af69cf531ffc398575268da142 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 7d76f9e

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 7d76f9ecc97248af69cf531ffc398575268da142 false-positive: <reason, 20 to 500 characters>

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

The enterprise off baseline also drops edition-contributed providers (discover.py:167) until the policy names their hosts. Say this in the release notes so an enterprise operator doesn't read an empty Discover as an outage.

Disposition: accepted, release-notes only. The Backwards compatibility section now names edition-contributed providers and flags this as a release-notes item. CHANGELOG.md belongs to the release PR (AGENTS.md), so this PR doesn't edit it. No code change.

@dodgeblaster
dodgeblaster force-pushed the fix/12677-registries-scope branch from 0c55800 to 1df3c51 Compare November 2, 2026 22:59
@dodgeblaster
dodgeblaster marked this pull request as ready for review November 3, 2026 00:46
@dodgeblaster
dodgeblaster requested review from a team and KiroCrewCaptain as code owners November 3, 2026 00:46
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 3, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Hold for human review at 1df3c51 (security-policy change).

This PR changes which external discovery registries the gateway is allowed to contact. It adds the governed key external_access.registry_hosts, which is off by default in enterprise builds, and makes admits_registry ask it before the edition policy (_shared_access.py#L113-L140, extension_governance.py#L151-L165). Admission and egress policy changes are reserved for a human reviewer.

I found no defect. The key is matched on the host of api_base, the stricter of key and edition wins, evaluation errors deny, and a refused provider is never registered. The tests cover each of these. All AI lanes at this head pass (UX skipped), checks are green, and there is no conflict with main. What would clear this: a maintainer's review of the enterprise default-off break and the admission order.

— crew-pr-reviewer (r143)

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 3, 2026

@hkrishg-aws hkrishg-aws left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for building this, and for the credit. Reviewed against the branch; the design matches what we agreed in #12677.

What I checked: the key is asked in the shared admits_registry gate before the edition policy, so the stricter wins, and reading the context first keeps a composition failure from reading as a policy denial. registry_host_denied judges the host of api_base, never the provider name, and goes through _denied, so it fails closed and audits governed decisions. The enterprise baseline is off and covered in test_governance_enterprise_baseline.py. The new tests cover allow, deny, the * catch-all for hostless providers, host-only matching, stricter-wins, enterprise defaults, error-denies and never-registered. CI is green.

One non-blocking suggestion: registry_host_denied derives the host with _url_host, a single stdlib reading. The other host-keyed checks use url_policy_hosts (decisions/capability.py:286, metrics/otlp_governance.py:53), which asks every client's parser and requires all readings to permit. api_base comes only from built-in and edition providers today, so nothing exploits the difference. But if a provider ever takes api_base from config, https://evil.example\@skills.sh/ reads as skills.sh here while aiohttp connects to evil.example. Checking every reading from url_policy_hosts would keep this key consistent with the others. Happy for that to be a follow-up.

I'll close #16007 as superseded by this PR and the enterprise-edition RFC. I'm also glad to take operator docs with an example security_policy.json as a follow-up, since this PR only touches the system specs.

@bolichen97

Copy link
Copy Markdown
Contributor

Could you update this branch onto the latest main? The branch has a merge conflict on head 1df3c51, so it cannot merge as is. The gate shows 98 checks passed and none red.

I read the full diff (8 files, 393 lines). I have no change to ask for on the design: in the default edition an unnamed external_access.registry_hosts key admits every registry as before, so nothing changes until an admin sets it, and the enterprise baseline of "off" matches the other keys in the baseline table, such as network.egress. The key is checked first in admits_registry, so an edition policy cannot loosen it. After the update I will review the new head again.

@dodgeblaster
dodgeblaster force-pushed the fix/12677-registries-scope branch from 1df3c51 to 26917fb Compare November 6, 2026 18:35
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 6, 2026
@dodgeblaster
dodgeblaster force-pushed the fix/12677-registries-scope branch from 26917fb to 9ebf66a Compare November 6, 2026 20:43
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 6, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, the opt-in key itself is good to keep: external_access.registry_hosts as a host-matched ruleset, checked in the shared admits_registry gate, with the edition policy asked after it. Two parts of this head add new refusals where main admits today, and our current rule is not to add security strictness in a PR like this. Please drop just those two parts.

  1. Unset key in Enterprise must behave as main does. platform/governance_parts/baseline.py adds "external_access.registry_hosts": _OFF, so an Enterprise install with no policy for the key now refuses every discovery registry (skills.sh, GitHub, the official MCP registry, and skill_discover through the gateway). test_governance_enterprise_baseline.py pins that as ((), ("skills.sh",)). Please remove the baseline entry so an unset key admits as main does, and an org that wants the ceiling sets the key on purpose. Please update the baseline test to match, and add a test that an Enterprise install with the key unset still admits skills.sh and the official MCP registry.

  2. A governance read error must not newly deny Discover. registry_host_denied goes through _denied, which is fail-closed, so test_a_governance_error_denies pins that an unreadable profile store with no key set refuses skills.sh. Main admits in that case. Please log the error (through the same audit/log path as other decisions) and admit, as main does, instead of refusing. Please replace that test with one asserting the error is logged and the registry is still admitted. An explicit allow or deny list that the policy does set should keep working as in your other tests.

The docs in governance.md ("fail-closed") and platform-context.md should follow both changes. Happy to re-review once these are in.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 7, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-checked at 8ec6d28: both points from my 11-06 review are still open, so I'm restating them briefly. Keeping the external_access.registry_hosts key itself is fine.

  1. Unset key in Enterprise still refuses every registry. platform/governance_parts/baseline.py still adds "external_access.registry_hosts": _OFF, and test_enterprise_unnamed_key_admits_no_registry pins it. Please drop that entry so an unset key admits as main does, and test that Enterprise with the key unset still admits skills.sh and the official MCP registry.
  2. A governance read error still denies. registry_host_denied goes through the fail-closed _denied, and test_a_governance_error_denies pins that. Please log the error and admit, as main does, with a test for that.

The "baseline is off" line in governance.md should follow. An allow or deny list that a policy sets should keep working as your other tests show.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 7, 2026
@dodgeblaster
dodgeblaster force-pushed the fix/12677-registries-scope branch from 8ec6d28 to b987983 Compare November 9, 2026 16:31
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 9, 2026
@dodgeblaster
dodgeblaster force-pushed the fix/12677-registries-scope branch from b987983 to dabb002 Compare November 9, 2026 17:20
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

@bolichen97 thanks for the review (review). Both asks are done on head dabb002bd3, rebased onto current main (including the #32970 rename to the LTS Edition):

  1. No LTS default. "external_access.registry_hosts": _OFF is gone from platform/governance_parts/baseline.py. The key is now in BASELINE_UNGATED, so an unnamed key admits every registry on LTS as on oss, the same as main. test_lts_unnamed_key_admits_every_registry checks that skills.sh, GitHub and the official MCP registry are still admitted with no ceiling and with a policy that does not name the key. test_governance_lts_baseline.py now lists the key among the open scopes.
  2. Log and admit on a governance error. registry_host_denied asks with a new fail_closed=False switch on _denied. A governance error is logged and written to the SEL as governance_degraded (the same audit_governance_degraded path governance_permits uses), and the registry is admitted. test_a_governance_error_denies is replaced by test_a_governance_error_is_logged_and_admits (on oss and LTS) and test_an_error_inside_the_evaluation_is_logged_and_admits. Every other key in extension_governance still fails closed, and a PlatformCompositionError still propagates.

An allow or deny list a policy sets still narrows Discover, now tested on LTS too (test_lts_policy_allow_list_narrows, test_lts_policy_deny_list_narrows). The "fail-closed" and "baseline is off" wording in governance.md, the module docstring and the PR description now match.

The stricter LTS default the RFC row describes (off by default, fail closed) is split out as a proposal for a maintainer to decide in #34006. hkrishg-aws's suggestion to read the host through url_policy_hosts stays a separate follow-up.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Follow-up: #34006 proposes, for a maintainer to decide, that on Enterprise/LTS installs external_access.registry_hosts defaults to off (admin opt-in) and a governance read error fails closed, per the LTS-edition RFC appendix row "Extension sources". This PR ships the key additive, as requested in review; #34006 tracks the stricter LTS default separately.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 9, 2026
@dodgeblaster
dodgeblaster force-pushed the fix/12677-registries-scope branch from dabb002 to 880ed5e Compare November 10, 2026 17:32
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 10, 2026
Add the governance key external_access.registry_hosts, a host-matched
ruleset that lists the skill and MCP discovery registries the Discover
surfaces may query. It is the LTS-edition RFC's "Extension sources" row.
admits_registry asks it on the host of the provider's api_base before the
edition's external_access policy, so the stricter of the two wins and an
edition cannot loosen the operator's policy.

The key is additive. An unnamed key admits every registry, as before, in
oss and LTS alike (it is in BASELINE_UNGATED), so only a policy that names
it narrows Discover; an allow or deny list a policy sets applies on both. A
governance error on the key is logged and audited as governance_degraded and
the registry is admitted, as Discover did before the key existed. A policy
that names the key, which the parser refused before, now loads. The catalogs
are built once per process, so a change binds at the next gateway start.

Whether LTS should default the key to off and fail closed is proposed
separately in #34006.

Fixes #12677
@dodgeblaster
dodgeblaster force-pushed the fix/12677-registries-scope branch from 880ed5e to 7d76f9e Compare November 10, 2026 19:20
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 10, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at 7d76f9e. Thank you: both points from my reviews are done.

  1. An unset key now admits every registry in every edition. baseline.py marks external_access.registry_hosts as _OPEN ("Discover queries every registry unless a policy names the key"), and test_lts_unnamed_key_admits_every_registry checks that LTS with the key unset still admits skills.sh, GitHub and the official MCP registry, and writes nothing new to the SEL. So with no policy, Discover behaves as on main.
  2. A governance read error now admits. registry_host_denied calls _denied(..., fail_closed=False), which logs the error and records governance_degraded instead of denying. test_a_governance_error_is_logged_and_admits (oss and LTS) and test_an_error_inside_the_evaluation_is_logged_and_admits pin it. The other governed keys stay fail-closed as before.

What a policy turns on is an opt-in admin narrowing: an allow or deny list of registry hosts, matched on the host of the provider's base URL. The allow and deny tests show it works. governance.md and the module docs follow the new defaults, and the RFC references now point at rfc-crew-lts-edition.

A PlatformCompositionError still propagates from this gate, as it does from the other governance gates. That only happens when the platform context is not composed at all, so it is not a refusal a working install meets.

No regex, and with no policy nothing is refused that main allows. All checks on this head are green.

@bolichen97
bolichen97 merged commit 68094c3 into main Nov 10, 2026
97 checks passed
@bolichen97
bolichen97 deleted the fix/12677-registries-scope branch November 10, 2026 21:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

governance: SCOPE_CATALOG row for skill/MCP discovery registries

4 participants