Repository navigation
fix(policy): check mcp.transport.allow on the effective MCP transport - #3788
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
… declared Panel folds for #3788: - A registry server's declared transport now narrows the check only when the registry offers it (same overlay install applies); e.g. `transport: stdio` on a remote-only SSE server is judged as sse. The declaration is the offline fallback when the registry cannot resolve the server. Self-defined servers stay offline. - Guard also requires the resolver to reuse MCPIntegrator._apply_overlay and _build_self_defined_info (install parity). - Lifecycle: unreachable registry blocks `install --mcp` with the `transport:` remedy and fails audit --ci. - Tests stay off the public registry through the mcp_transport_resolution._registry_client seam (autouse fixture). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Supply Chain Security Expert | 0 | 3 | 0 | Declared-transport offline trust created a check-write parity gap (folded); lookup seam and audit egress deferred. |
| Test Coverage Expert | 0 | 1 | 0 | Regression has e2e lifecycle proof; unreachable-registry path needed e2e proof (folded). |
| Python Architect | 0 | 1 | 0 | Owner placement, single-seam routing and layering are sound; guard should pin parity-critical helpers (folded). |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 3 follow-ups
- [Supply Chain Security Expert] Share one registry resolution between the policy check and the install write. -- Independent lookups leave a window where a non-deterministic registry serves different metadata to policy and install.
- [Supply Chain Security Expert] Add private-IP and cloud-metadata guards to registry egress from per-dependency
registry:URLs. -- audit --ci now contacts MCP registries when transport.allow is set. - [Python Architect] Promote
MCPIntegrator._apply_overlayand_build_self_defined_infoto public API. -- They are parity-critical and now pinned by the guard.
Recommendation
The regression is closed, in-scope findings are folded, the lifecycle proof is hermetic, and the lint chain is green. Ship once the 0.37 captain confirms the condition-(a) refinement and the PR is rebased onto the 0.36.1 transport-normalization owner. Track the lookup seam and the egress guard as backlog issues; they harden an existing trust boundary, not a new one.
Full per-persona findings
Supply Chain Security Expert
- [recommended] Declared transport trusted offline can diverge from the transport install writes at
src/apm_cli/integration/mcp_transport_resolution.py
transport: stdioon a remote-only registry server: the overlay keeps the remote, the adapter writes SSE, policy saw stdio. (Folded.) - [recommended] Policy transport resolution and install prevalidation use independent registry lookups at
src/apm_cli/integration/mcp_transport_resolution.py
A purpose-built registry could answer differently within one invocation. (Deferred.) - [recommended] audit --ci gains egress to per-dependency
registry:URLs atsrc/apm_cli/integration/mcp_transport_resolution.py
SimpleRegistryClient has no private-IP or metadata-range guard. (Deferred.)
Test Coverage Expert
- [recommended] No lifecycle test for the unresolved-transport path (registry unreachable or server not found).
Proof (missing at):tests/integration/test_mcp_transport_policy_lifecycle.py::test_unreachable_registry_blocks_with_remedy-- proves: with the registry unreachable, install --mcp is rejected with thetransport:remedy before any write. [governed-by-policy,devx] (Folded; now passes.)
Python Architect
- [recommended] Lint guard does not assert parity-critical private-helper calls in the resolver at
scripts/architecture_linter/checks/install_policy_mcp_transport.py
Removing _apply_overlay or _build_self_defined_info from the resolver would silently break install parity. (Folded; public-API promotion deferred.)
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
Critical inconsistencies in metadata snapshots, transport normalization, and dependency selection can allow disallowed transports to be installed while audit misses violations.
4 open issues
What changed in this PR
This PR addresses #3764 by extending APM’s MCP transport policy checks from manifest declarations to resolved registry metadata, using a shared transport-normalization module.
Changes:
- Canonicalizes transport names, including the
httpalias, when parsing policy. - Adds effective-transport resolution and passes direct-install registry overrides into policy preflight.
- Adds architecture guards, regression coverage, and documentation for the stricter enforcement.
| File | Description |
|---|---|
tests/unit/scripts/test_architecture_runner.py |
Registers the new guard in the expected rule inventory. |
tests/unit/policy/test_policy_checks.py |
Tests canonical, dual, and unresolved transport checks. |
tests/unit/policy/test_parser.py |
Tests aliases, unknown names, and inheritance. |
tests/unit/integration/test_mcp_transport_resolution.py |
Adds hermetic resolver and overlay coverage. |
tests/integration/test_wave7_policy_registry_coverage.py |
Updates transport checks to use canonical inputs. |
tests/integration/test_mcp_transport_policy_lifecycle.py |
Adds install and audit lifecycle scenarios. |
tests/integration/test_architecture_owner_rule_mutations.py |
Tests detection of raw transport reads. |
tests/fixtures/policy/test_fixtures_load.py |
Expects canonical transport names. |
tests/fixtures/policy/golden/parsed-policies.json |
Updates normalized policy snapshots. |
tests/conftest.py |
Prevents public registry lookups during tests. |
src/apm_cli/policy/schema.py |
Documents the canonical allow-list representation. |
src/apm_cli/policy/policy_checks.py |
Checks resolved transports and reports unresolved servers. |
src/apm_cli/policy/parser.py |
Normalizes allow lists and warns on unknown names. |
src/apm_cli/mcp_transport.py |
Introduces transport vocabulary and metadata projection. |
src/apm_cli/integration/mcp_transport_resolution.py |
Resolves registry metadata, applies overlays, and memoizes lookups. |
src/apm_cli/install/mcp/command.py |
Applies registry overrides during policy preflight. |
src/apm_cli/commands/install.py |
Passes registry selection into MCP preflight. |
scripts/architecture_linter/checks/install_policy_mcp_transport.py |
Adds the canonical transport-projection guard. |
scripts/architecture_linter/checks/install_policy_intent.py |
Registers the new architecture rule. |
packages/apm-guide/.apm/skills/apm-usage/governance.md |
Updates transport-policy guidance and remedies. |
docs/src/content/docs/reference/policy-schema.md |
Documents aliases and effective-transport checks. |
docs/src/content/docs/enterprise/policy-reference.md |
Explains resolution, enforcement, and failure handling. |
CHANGELOG.md |
Announces stricter transport enforcement and migration guidance. |
.apm/architecture/owners/install-deployment.json |
Records transport-projection ownership and its guard. |
Review effort: Balanced
Copilot review folds for #3788: - install writes the registry info org policy judged (policy_checked_registry_info), so a registry that answers differently later cannot change the written transport; guard pins the call. - transport resolution dedupes MCP deps first-wins, as install does. - audit --ci checks production and dev MCP servers, as the install gate does. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1e773ca to
5654564
Compare
…allback Delta panel folds for #3788 (stacked on #3789): - When the registry could not be read during the policy check, policy judges the declared transport and records it; install now re-projects the overlaid info it would write and refuses, before any write in the group, when the result differs (unverified_policy_fallbacks). - server_write_transports takes the adapters' remote selector from the caller, so the owner module no longer imports the adapter layer; the owner record lists the policy symbols and the guard pins the definition site and the install refusal. - Tests: flaky-registry fallback refusal, multi-remote projection, every-adapter remote parity, snapshot reuse on a per-dependency registry, and `install --mcp --registry` resolving policy against the flag's registry (lifecycle). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…allback Delta panel folds for #3788 (stacked on #3789): - When the registry could not be read during the policy check, policy judges the declared transport and records it; install now re-projects the overlaid info it would write and refuses, before any write in the group, when the result differs (unverified_policy_fallbacks). - server_write_transports takes the adapters' remote selector from the caller, so the owner module no longer imports the adapter layer; the owner record lists the policy symbols and the guard pins the definition site and the install refusal. - Tests: flaky-registry fallback refusal, multi-remote projection, every-adapter remote parity, snapshot reuse on a per-dependency registry, and `install --mcp --registry` resolving policy against the flag's registry (lifecycle). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
485321c to
ddb2174
Compare
…allback Delta panel folds for #3788 (stacked on #3789): - When the registry could not be read during the policy check, policy judges the declared transport and records it; install now re-projects the overlaid info it would write and refuses, before any write in the group, when the result differs (unverified_policy_fallbacks). - server_write_transports takes the adapters' remote selector from the caller, so the owner module no longer imports the adapter layer; the owner record lists the policy symbols and the guard pins the definition site and the install refusal. - Tests: flaky-registry fallback refusal, multi-remote projection, every-adapter remote parity, snapshot reuse on a per-dependency registry, and `install --mcp --registry` resolving policy against the flag's registry (lifecycle). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
ddb2174 to
b1ca0a4
Compare
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 3 | 0 | Owner routing sound; layer inversion and missing definition-site guard folded; private-helper coupling deferred to the owner. |
| Supply Chain Security Expert | 1 | 1 | 0 | Declared-fallback bypass reproduced and now folded; registry egress guard still open (pre-existing). |
| Test Coverage Expert | 0 | 3 | 0 | --registry preflight, multi-remote parity and per-dep snapshot parity tests added. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 4 follow-ups
- [Supply Chain Security Expert] Track hardening of MCP registry egress for per-dependency
registry:URLs. -- Pre-existing client behaviour that audit --ci now reaches when transport.allow is set. - [Test Coverage Expert] Get a full green CI run on the head that includes b1ca0a4 once fix(mcp): render remote transports per harness and heal retired shapes #3789 is rebased onto main. -- The last full CI run was green at 5654564; workflows only run for PRs targeting main, and fix(mcp): render remote transports per harness and heal retired shapes #3789 currently conflicts with main.
- [Python Architect] Promote
_registry_group_keyand_overlaid_server_infosto a public module owned by fix(mcp): render remote transports per harness and heal retired shapes #3789, and make theoperations=Nonecontract explicit. -- The resolver and install share private helpers. - [Python Architect] Replace the process-global
warnings.catch_warningsaround overlay projection with a scoped mechanism. -- catch_warnings is not thread-safe.
Recommendation
The blocking bypass is fixed and covered by a test that fails when the fix is removed, and every recommended finding except the two accepted deferrals is folded with tests. Next: rebase #3789 onto main, confirm full CI on the #3788 head, and land #3788 after #3789.
Full per-persona findings
Python Architect
- [recommended] server_write_transports imported the adapter layer from the leaf owner module at
src/apm_cli/mcp_transport.py. (Folded: the selector is passed in, and an every-adapter parity test was added.) - [recommended] No owner record or guard covered the policy symbols defined in mcp_transport.py at
.apm/architecture/owners/hooks-integrations.json. (Folded: owner record and definition-site needles.) - [recommended] Resolver and install import each other's private helpers;
operations=Nonerelies onknownbeing complete; the warning filter is process-global, atsrc/apm_cli/integration/mcp_transport_resolution.py. (Deferred: refactor of the fix(mcp): render remote transports per harness and heal retired shapes #3789 surface.)
Supply Chain Security Expert
- [blocking] When the registry lookup is unresolved, a declared transport passes policy, then install refetches and can write a disallowed transport, at
src/apm_cli/integration/mcp_transport_resolution.py. (Folded at b1ca0a4: install refuses unverified fallbacks before any write.) - [recommended] No egress guard on per-dependency
registry:URLs, which audit --ci now also reaches. (Deferred: pre-existing registry client behaviour.)
Test Coverage Expert
- [recommended]
install --mcp --registrypolicy preflight had no test. (Folded: lifecycle step intests/integration/test_mcp_transport_policy_lifecycle.py.) - [recommended] No multi-remote or every-adapter
selected_remoteparity test. (Folded:TestOwnerProjection.) - [recommended] Snapshot test hardcoded the same URL on both sides. (Folded: parametrized over default and per-dep registry with real URL derivation.)
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.
There was a problem hiding this comment.
🟡 Changes recommended
Registry recovery can leave apm.yml modified before an HTTP-only policy rejection and can abort installation for warn-only violations instead of preserving warning behavior.
2 open issues
4 resolved since last review
Review effort: Balanced
…allback Delta panel folds for #3788 (stacked on #3789): - When the registry could not be read during the policy check, policy judges the declared transport and records it; install now re-projects the overlaid info it would write and refuses, before any write in the group, when the result differs (unverified_policy_fallbacks). - server_write_transports takes the adapters' remote selector from the caller, so the owner module no longer imports the adapter layer; the owner record lists the policy symbols and the guard pins the definition site and the install refusal. - Tests: flaky-registry fallback refusal, multi-remote projection, every-adapter remote parity, snapshot reuse on a per-dependency registry, and `install --mcp --registry` resolving policy against the flag's registry (lifecycle). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
b1ca0a4 to
43b2f19
Compare
Copilot review folds for #3788: the declared-transport fallback let `install --mcp --transport ...` write apm.yml before the later refusal fired, and the install-side refusal bypassed enforcement: warn. A registry server is now always judged on the registry data install writes from; when the registry cannot resolve it the transport is unknown, which the shared enforcement path blocks (block) or warns about (warn) before any write. Self-defined servers still resolve offline. The install-side refusal is removed. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Takeover folds for #3788: the warn-mode regression now asserts the `effective transport unknown` violation is recorded with severity warn (not only that preflight returns), and the check-9 resolver docstring states that every registry server is looked up, declared or not. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Delta panel folds (test-coverage-expert) for #3788: - Unit: a server offering sse and streamable-http remotes is judged on the sse remote install writes when undeclared, and `transport: http` (or `streamable-http`) picks the allowed remote. Replaces an alias test that passed whether or not the alias narrowed anything. - Lifecycle: `apm audit --ci` with an unreachable registry reports a registry server that declares `transport:` as unknown, and `enforcement: warn` downgrades that check to a reported warning. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Supply Chain Security Expert | 0 | 1 | 0 | Delta closes the declared-transport fallback bypass. Failing closed on unresolvable registry servers is the right default. One warn-mode gap: the transport install writes is never judged. |
| Test Coverage Expert | 0 | 3 | 0 | Delta's main reversions are trapped; the alias test now passes vacuously, and audit --ci with a declared transport plus warn downgrade lack CLI-tier traps. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 2 follow-ups
- [Supply Chain Security Expert] File a follow-up issue for this case: under
enforcement: warn, when a registry server was unknown at the gate and allow is set, the transport install writes is never judged. The install should project the overlaid info and emit a warn-severity violation naming the transport it wrote (mcp_integrator_install.py:366). -- Users on warn mode currently see only a generic 'effective transport unknown' warning, never 'wrote sse'. Block mode is safe. The fix needs the policy object passed into install's registry group so it goes through shared enforcement rather than bringing back the install-side check removed in 43b2f19. - [Test Coverage Expert] When the warn-mode follow-up lands, add a CLI-tier lifecycle test asserting that
installunderenforcement: warnnames the transport it actually wrote. -- The warn downgrade is now pinned foraudit --ci, but not for the install write path the follow-up will change.
Recommendation
Mark the PR ready and merge at 0fa0ca7 once CI is green. The delta closes a real bypass, defaults to failing closed, and all three test gaps are pinned in real-binary tests, one of them confirmed by a mutation run. Before merge, open the follow-up issue for the enforcement: warn install-write gap, linked to #3764 and milestoned for the next release, so the deferral is on record rather than silent.
Full per-persona findings
Supply Chain Security Expert
- [recommended] Under enforcement: warn, a registry server whose transport was unknown at the gate gets a fresh registry fetch at install, and that written transport is never checked against mcp.transport.allow. at
src/apm_cli/integration/mcp_integrator_install.py:366
The memo stores the UnresolvedTransport result, so policy_checked_registry_info returns None. _install_registry_group then fills known from registry_server_cache or operations.batch_fetch_server_info, overlays it and writes it. If the gate lookup failed briefly but the install fetch succeeds, APM writes, for example, an SSE remote that policy never judged. The only signal the user gets is the earlier generic 'effective transport unknown' warning, not 'wrote sse, which is not in allowed [..]'. Block mode is safe because it refuses at the gate. In warn mode, though, the audit trail shows that a transport was unknown, not which transport was written.
Suggested: When policy_checked_registry_info returns None and mcp.transport.allow is set, run write_transports() on the freshly overlaid server_info_cache[name] before writing, and send a warn-severity logger.policy_violation naming the transport actually written if it is outside the allow list. Add a unit test: the gate lookup raises and the install fetch returns an SSE-only server under warn; assert the warning names 'sse'.
Test Coverage Expert
- [recommended] test_declared_http_alias_matches_registry_remote passes vacuously, so nothing pins the new 'pick one with transport:' remedy (declared http narrowing to streamable-http) at
tests/unit/integration/test_mcp_transport_resolution.py:177
The replacement uses HTTP_SERVER, which offers only a streamable-http remote, so the effective transport is streamable-http whether or not 'http' maps to streamable-http in MCPIntegrator._apply_overlay. The docs and release note now make 'pick an allowed transport with transport: when the server offers several' the main remedy for registry servers; no test asserts the remedy narrows a server offering both sse and streamable-http remotes.
Suggested: Add a server with sse and streamable-http remotes, parametrize declared over http and streamable-http, assert the effective transport is streamable-http, and add a negative control where the undeclared server fails on 'sse'.
Proof (missing at):tests/unit/integration/test_mcp_transport_resolution.py::TestDeclaredTransport::test_declared_alias_narrows_multi_remote_server-- proves: If my org allows http and a registry server offers both sse and http, declaring transport: http in apm.yml lets it install. [governed-by-policy,devx]
assert resolution.resolve_effective_mcp_transports([dep]) == {MULTI_REMOTE['name']: frozenset({'streamable-http'})}
Status: folded at 0fa0ca7. - [recommended] No real-CLI trap that audit --ci now fails a registry server with a declared transport: when the registry is unreachable at
tests/integration/test_mcp_transport_policy_lifecycle.py:228
The release note announces this as new behavior, but the only trap is a unit test with a hand-built MCPDependency. The lifecycle audit step uses a bare string with no transport:, so it would still pass if audit kept judging declared registry servers offline.
Suggested: Widen write_manifest to accept dicts, write {'name': _SSE_NAME, 'transport': 'http'}, run audit and assert the mcp-transport check fails with 'effective transport unknown'.
Proof (missing at):tests/integration/test_mcp_transport_policy_lifecycle.py::test_unreachable_registry_blocks_with_remedy-- proves: apm audit --ci in CI cannot pass a registry MCP server on its declared transport alone while the registry is down. [governed-by-policy,secure-by-default]
assert 'effective transport unknown' in checks['mcp-transport']['details'][0]
Status: folded at 0fa0ca7. - [recommended] The enforcement: warn downgrade of 'effective transport unknown' is proven only by a unit test with discovery and logger patched at
tests/integration/test_mcp_transport_policy_lifecycle.py
No real-CLI test drives audit --ci under an enforcement: warn policy with an unresolvable registry server and checks that the outcome is a warning, not a failure. _POLICY in the lifecycle test hardcodes enforcement: block.
Suggested: Reuse the unreachable-registry setup, switch the org policy to enforcement: warn, and assert the mcp-transport check is reported as a warning.
Proof (passed):tests/unit/install/test_mcp_preflight_policy.py::TestTransportUnknownUnderWarn::test_unresolvable_registry_server_only_warns-- proves: Under enforcement: warn, a registry server whose transport cannot be resolved produces a warning instead of blocking install. [governed-by-policy,devx]
assert all(c.kwargs.get("severity") == "warn" for c in unknown)
Status: folded at 0fa0ca7.
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.
Delta panel fold (cli-logging-expert) for #3788: the `effective transport unknown` detail now says what to do (check the server name and registry URL, or make the MCP registry reachable, then retry) before the short reason a declared 'transport:' cannot stand in, in short sentences and with the check's single-quote style. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Org policy mcp.transport.allow compared only the transport declared in apm.yml, so a registry server with no declared transport (for example an SSE remote) was never checked, and `http` did not match `streamable-http`. - mcp_transport.py (owner) gains the policy projection: canonical_transport_name(s), POLICY_TRANSPORTS, UnresolvedTransport and server_write_transports (package = stdio, the adapter-selected remote = its canonical transport, both for dual servers). - The parser canonicalizes mcp.transport.allow once; inheritance intersects canonical names; unknown names warn. - run_dependency_policy_checks resolves effective transports through integration/mcp_transport_resolution.py, which reuses install's _registry_group_key and _overlaid_server_infos: registry servers are looked up in the registry install uses and judged on the overlaid info (a declared transport narrows only when offered; it is the offline fallback when the registry cannot resolve the server). Self-defined servers resolve offline. Deps dedupe first-wins as install does. The lookup runs only when mcp.transport.allow is set; unresolvable servers fail with an actionable reason. - Install writes the registry snapshot policy judged (policy_checked_registry_info); `apm install --mcp` runs its preflight against the --registry endpoint before apm.yml is written; audit --ci checks production and dev MCP servers like the install gate. - Guard install-deployment-policy-mcp-transport-projection (owner record and MutationCase) bans raw transport reads under policy/ and pins the routing. Fixes #3764 apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…allback Delta panel folds for #3788 (stacked on #3789): - When the registry could not be read during the policy check, policy judges the declared transport and records it; install now re-projects the overlaid info it would write and refuses, before any write in the group, when the result differs (unverified_policy_fallbacks). - server_write_transports takes the adapters' remote selector from the caller, so the owner module no longer imports the adapter layer; the owner record lists the policy symbols and the guard pins the definition site and the install refusal. - Tests: flaky-registry fallback refusal, multi-remote projection, every-adapter remote parity, snapshot reuse on a per-dependency registry, and `install --mcp --registry` resolving policy against the flag's registry (lifecycle). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot review folds for #3788: the declared-transport fallback let `install --mcp --transport ...` write apm.yml before the later refusal fired, and the install-side refusal bypassed enforcement: warn. A registry server is now always judged on the registry data install writes from; when the registry cannot resolve it the transport is unknown, which the shared enforcement path blocks (block) or warns about (warn) before any write. Self-defined servers still resolve offline. The install-side refusal is removed. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Takeover folds for #3788: the warn-mode regression now asserts the `effective transport unknown` violation is recorded with severity warn (not only that preflight returns), and the check-9 resolver docstring states that every registry server is looked up, declared or not. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Delta panel folds (test-coverage-expert) for #3788: - Unit: a server offering sse and streamable-http remotes is judged on the sse remote install writes when undeclared, and `transport: http` (or `streamable-http`) picks the allowed remote. Replaces an alias test that passed whether or not the alias narrowed anything. - Lifecycle: `apm audit --ci` with an unreachable registry reports a registry server that declares `transport:` as unknown, and `enforcement: warn` downgrades that check to a reported warning. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Captain fold for #3788: the `effective transport unknown` violation now explains that a declared `transport:` is not enough for a registry server, because install writes the transport the registry serves and `transport:` only picks among the ones it offers. Unit and lifecycle tests pin the wording. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Delta panel fold (cli-logging-expert) for #3788: the `effective transport unknown` detail now says what to do (check the server name and registry URL, or make the MCP registry reachable, then retry) before the short reason a declared 'transport:' cannot stand in, in short sentences and with the check's single-quote style. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…) pair main's commands/install.py sits at the 2100-line CI cap; the two new keyword arguments for the --mcp policy preflight pushed it to 2102. run_mcp_policy_preflight now takes the (url, source) pair _resolve_registry_url returns. No behavior change. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
e6fb915 to
42ec6fd
Compare
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Lane L: main merged for landing
This comment was generated by an AI agent (Lane L landing desk) on behalf of Daniel Meppiel (@danielmeppiel). |
… SSE heal test (#3877) * test(mcp): assert the 0.37 effective-transport policy in the registry SSE heal test (#3876) #3788 made mcp.transport.allow judge the effective registry transport, so an SSE remote outside the allow list is now blocked before any MCP write. The heal lifecycle test still asserted the 0.36.1 declared-only contract. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(changelog): note the heal transport test update (#3877) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…idance (#3903) * docs(changelog): enforce one-line entries in agent and contributor guidance Make the changelog rule concrete in its single source (.apm/instructions/changelog.instructions.md): one line, user-visible effect first, 25 words or fewer, ending with (#PR); breaking changes in "Breaking changes and upgrade notes" with a one-line migration; never a second line for the same change; no entry for internal-only PRs; two good and two bad examples from the current changelog. cut-release now re-sanitizes the whole [Unreleased] block at release time (dedupe, condense, Highlights, upgrade notes, ref/credit check). The delivery and merge autopilot workers, pr-description-skill, CONTRIBUTING.md, the PR template and the development guide point at the rule. Generated .github/ and .agents/ copies and apm.lock.yaml hashes are re-synced with apm install. Clean the current [Unreleased] block into that shape: drop the long duplicates of #3765/#3818, #3769, #3788, #3865, #3867, #3873, #3875, #3882 and the spec lines, fold their user-relevant caveats into the short lines, and drop test-only #3877. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(changelog): scope delivery-worker CHANGELOG edits to one task; shorten sanitizer example Address review: only the task whose files_hint owns CHANGELOG.md edits it (wave gate forbids shared-file edits across task branches), and the worked example now fits rule 2 while keeping its caveat and four refs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>


Description
TL;DR. Org policy
mcp.transport.allownow checks the transport APM will actually write, not only thetransport:inapm.yml. Registry servers without a declared transport (for example an SSE remote) are looked up and checked, andhttpnow equalsstreamable-httpon both sides.apm install,apm install --mcp,apm updateandapm audit --ciagree, and a blocked server is rejected before any MCP config orapm.ymlwrite.Important
Release note: this can newly block installs of registry MCP servers whose transport is not allowed, or that cannot be resolved. The remedy is to declare
transport:for the server inapm.ymlor to update the policy.Note
Builds on #3789 (merged): the policy projection extends that owner module (
mcp_transport.py) and reuses install's fetch-then-overlay step.Problem (WHY)
policy/policy_checks.pycompared onlymcp.transportfrom the manifest:if mcp.transport and mcp.transport not in allowed_transports. A registry server has no declared transport, so its SSE remote was never checked (finding F28).allow: [stdio, http]did not match a declaredstreamable-http, and vice versa.apm install --mcp io.example/sse-serverunderallow: [stdio, http]wrote the SSE server to Copilot config (reproduced by the new lifecycle test on the old code).Approach (WHAT)
mcp_transport.pyaddscanonical_transport_name(s)(http->streamable-http) andserver_write_transports(server_info).mcp.transport.allowis canonicalized once inpolicy/parser.py; unknown names warn;extends:intersects canonical names.transport:narrows only when the server offers it), package =stdio, remote = its transport (adapterselected_remote), both reported when both exist. Unresolvable registry servers are unknown even when declared. Self-defined servers: declared, offline.effective transport unknown (<reason>)naming unreachable / not found;enforcement: warndowngrades through the shared enforcement path, before any write.mcp.transport.allowis set; per-process memo so gate + pre-write preflight query once. Tests stay off the public registry via an autouse fixture on the resolver's_registry_clientseam.Implementation (HOW)
src/apm_cli/mcp_transport.pycanonical_transport_name(s),POLICY_TRANSPORTS,UnresolvedTransport,server_write_transports(remote chosen byMCPClientAdapter.selected_remote).src/apm_cli/integration/mcp_transport_resolution.pyresolve_effective_mcp_transports(mcp_deps): first-wins dedupe, groups by install's_registry_group_key, overlays through install's_overlaid_server_infos, memoizes lookups;policy_checked_registry_infohands install the judged snapshot.src/apm_cli/policy/policy_checks.pysrc/apm_cli/policy/parser.py,schema.pysrc/apm_cli/install/mcp/command.py,commands/install.py--mcppreflight runs insideregistry_env_override, so it resolves against the--registryendpoint beforeapm.ymlis written.scripts/architecture_linter/checks/install_policy_mcp_transport.py+ owner recordinstall-deployment-policy-mcp-transport-projection: no raw.transport/transport_type/"transport"key reads underpolicy/(parser excepted for the schema key); required routing needles. MutationCase added.enterprise/policy-reference.md(effective-transport rules, both-sides check,transport:remedy),reference/policy-schema.md, apm-usagegovernance.md, CHANGELOG.Diagram
Every policy caller reaches the transport check through the same seam, which resolves canonical values from the owner before judging them.
flowchart LR A["install / install --mcp / update / audit --ci"] --> B["run_dependency_policy_checks"] B -->|"mcp.transport.allow set"| C["resolve_effective_mcp_transports"] C -->|"declared transport"| D["canonical name, offline"] C -->|"registry, undeclared"| E["registry lookup + overlay"] E --> F["server_write_transports (owner)"] D --> G["_check_mcp_transport vs canonical allow"] F --> G G -->|"blocked"| H["no MCP config or apm.yml write"]Trade-offs
transport:narrows it.MCPIntegrator._apply_overlaynarrows remotes only when the server offers the declared transport, otherwise install writes the registry remote (an SSE-only server declaringtransport: httpgets its SSE remote). So a registry server is always judged on registry data:transport: stdioon a remote-only server is judged on the remote, and an unresolvable registry server stays unknown even with a declaration. The violation says so:<name>: effective transport unknown (<reason>); cannot check it against allowed [..]. Check the server name and registry URL, or make the MCP registry reachable, then retry. A declared 'transport:' cannot stand in: install writes the transport the registry serves. Cost:audit --ciwithmcp.transport.allowneeds the MCP registry for registry servers.apm.lock.yaml, avoiding a lockfile schema change.run_dependency_policy_checksguarantees parity across all callers at the cost of a policy -> integration import (precedent:policy/ci_checks.py).Follow-ups
enforcement: warn, name the transport install actually writes for a registry server whose transport was unknown at the policy gate (deferred from the delta panel; block mode already refuses at the gate).Benefits
allow: [stdio, streamable-http](previously allowed).http/streamable-httpcompare equal in policy and manifest.--mcpleavesapm.ymlbyte-identical.mcp.transport.allow.Issue and approved scope
Issue: Fixes #3764
Human scope-approval comment: #3764 (comment)
Does this PR complete the issue, or what remains? It delivers the record's Done-when in full. Follow-up #3822 tracks a warn-mode reporting improvement outside the Done-when.
Type of change
Testing
Scenario evidence
allow: [stdio, http]byinstall --mcp(apm.yml unchanged) andinstall(no MCP config), andaudit --cifailsmcp-transporttests/integration/test_mcp_transport_policy_lifecycle.py::test_registry_sse_remote_blocked_before_any_writetests/integration/test_mcp_transport_policy_lifecycle.py::test_registry_streamable_http_remote_passestransport: httppicks the allowed remote of a server offering sse and streamable-http; a declared transport narrows a dual server but cannot mask a remote-only one; self-defined resolves offlinetests/unit/integration/test_mcp_transport_resolution.py::TestDeclaredTransporttransport:) fails with its reason ininstall --mcp(before anyapm.ymlwrite) andaudit --ci;enforcement: warndowngrades it to a warningtests/integration/test_mcp_transport_policy_lifecycle.py::test_unreachable_registry_blocks_with_remedy,tests/unit/integration/test_mcp_transport_resolution.py::TestUnresolvedTransport,tests/unit/install/test_mcp_preflight_policy.py::TestTransportUnknownUnderWarntests/unit/policy/test_parser.py::TestMcpTransportAllowCanonicalizationtests/integration/test_architecture_owner_rule_mutations.py(install-deployment-policy-mcp-transport-projection)Regression traps: scenario 1 and
test_registry_sse_remote_blockedfail on the pre-fixpolicy_checks.py(verified by reverting it locally). Scenario 4 fails when the declared-transport offline fallback is restored in the resolver (mutation run).Validation commands and results (head 42ec6fd, rebased on main 733a4ac)
uvx ruff@0.15.12 check/format --check(src, tests, architecture linter, symlink probe) -- passedpython -m pylint --disable=all --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 ...-- 10.00/10bash scripts/lint-auth-signals.sh-- cleanbash scripts/lint-architecture-boundaries.sh-- exit 0; YAML I/O, 2100-line andrelative_toguards -- cleanpytest -p no:xdist tests/unit/policy tests/unit/install/test_mcp_preflight_policy.py tests/unit/install/test_transitive_mcp_policy.py tests/integration/test_wave7_policy_registry_coverage.py-- 1715 passed, 1 xfailedpytest -p no:xdist tests/unit/integration/test_mcp_transport_resolution.py-- 27 passed;tests/unit/test_install_command.py-- 134 passed;tests/unit/test_mcp_integrator_install_hermetic.py tests/unit/integration/test_mcp_per_dep_registry.py-- 29 passedpytest -p no:xdist tests/integration/test_architecture_owner_rule_mutations.py -k mcp_transport-- 3 passedAPM_E2E_TESTS=1 APM_BINARY_PATH=.venv/bin/apm pytest -p no:xdist tests/integration/test_mcp_transport_policy_lifecycle.py tests/integration/test_mcp_endpoint_alias_passthrough_lifecycle.py tests/integration/test_target_policy_gate_parity_lifecycle.py-- 31 passedHow to test
APM_E2E_TESTS=1 APM_BINARY_PATH=$PWD/.venv/bin/apm uv run --extra dev pytest tests/integration/test_mcp_transport_policy_lifecycle.py -p no:xdist -quv run --extra dev pytest tests/unit/integration/test_mcp_transport_resolution.py tests/unit/policy/test_parser.py -p no:xdist -qbash scripts/lint-architecture-boundaries.shSpec conformance (OpenAPM v0.1)
CONFORMANCE.{md,json}regeneratedCo-authored-by: Copilot 223556219+Copilot@users.noreply.github.com