Skip to content

fix(mcp): audit accepts MCP that install leaves out under the executables gate or without transitive trust - #3893

Merged
Daniel Meppiel (danielmeppiel) merged 11 commits into
mainfrom
danielmeppiel-fix-3720-mcp-omission-audit
Nov 19, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 11 commits into
mainfrom
danielmeppiel-fix-3720-mcp-omission-audit

Conversation

@danielmeppiel

Copy link
Copy Markdown
Collaborator

Description

apm install and apm update sometimes leave a package's MCP server out of the native config on purpose. That happens when the executables gate has not approved the declaring package, or when a transitive self-defined server is installed without --trust-transitive-mcp, including when a run without the flag removes a server an earlier run trusted. In both cases the lockfile had no omission evidence, so apm audit --ci failed config-consistency ("MCP selection is unknown", "in manifest but not in lockfile") even though install did what it promised.

Root cause, in the one omission-evidence owner (CurrentMcpConfigView):

  • The executables filter ran after omission evidence was computed, so a parked server got no evidence. Its config also stayed in the current view. CurrentMcpConfigView.with_unapproved_executables now parks exactly the gated servers the filter left out. It records {"declaration": <fingerprint>, "reason": "unapproved-executables"} and drops them from the install-side view and lock baseline.
  • Evidence was filtered against the pre-run lock, so a server retired in this run still counted as admitted. PreparedMcpIntegration.omissions(lockfile) now evaluates evidence against the lock this run produced. A kept baseline (--only apm, a native conflict, or a failed retirement) still overrides the evidence, and the previous baseline is preserved.
  • Audit replay (with_recorded_omissions) accepts unapproved-executables only for package-declared self-defined servers, the same predicate the gate uses (is_executable_gated_mcp). Missing, damaged or stale evidence still fails.

The existing architecture rule mutation_writes.mcp_omission_evidence now also guards the new routes. Docs: lockfile spec mcp_omissions reasons, the baseline-checks config-consistency contract, and the packaged apm-usage guide.

Issue and approved scope

Issue: Fixes #3720

Human scope-approval comment: #3720 (comment)

Does this PR complete the issue, or what remains? Yes, it completes it: both reproduction sequences are covered by an installed-CLI lifecycle test. Deferred and outside the approved scope: apm install --frozen runs its own MCP comparison (InstallService._frozen_mcp_reasons), which still ignores the executables gate. A frozen install of a gate-parked server fails on main for the same reason, and that will be reported separately.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally
  • All existing tests pass
  • Added tests for new functionality (if applicable)

Validation evidence (local, HEAD merged with main 6683116):

  • Reproduced on main f8ef817 with .venv/bin/apm: gate sequence and install --trust-transitive-mcp then update --yes both ended with audit rc 1 and failed config-consistency. With the fix, both give rc 0 and pass.
  • APM_BINARY_PATH=.venv/bin/apm pytest -p no:xdist tests/integration/test_mcp_deliberate_omission_audit_lifecycle.py: 4 passed. Against unfixed src/: 3 failed, 1 passed. The failed-retirement baseline guard passes both ways.
  • APM_BINARY_PATH=.venv/bin/apm pytest -p no:xdist tests/integration/test_architecture_mcp_omissions.py tests/unit/install/test_frozen_service_boundary.py tests/unit/install/test_mcp_integration_extraction.py tests/spec_conformance/test_mcp_omission_inventory.py tests/unit/security/test_executables.py tests/integration/test_mcp_omission_lifecycle.py tests/integration/test_package_mcp_executables_gate_lifecycle.py tests/integration/test_update_transitive_mcp_trust_lifecycle.py tests/integration/test_executables_gate_integration.py tests/integration/test_mcp_deliberate_omission_audit_lifecycle.py: 255 passed
  • pytest -p no:xdist tests/unit/integration/test_mcp_config_view.py tests/integration/test_architecture_mcp_omissions.py: 87 passed
  • pytest -p no:xdist tests/integration/test_architecture_owner_rule_mutations.py -k omission: 3 passed. tests/unit/scripts/test_architecture_runner.py: 72 passed
  • uvx ruff@0.15.12 check and format --check on src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ scripts/windows_native_symlink_probe_entry.py: passed
  • python -m pylint --disable=all --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 src/apm_cli/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/: 10.00/10
  • bash scripts/lint-auth-signals.sh: clean. bash scripts/lint-architecture-boundaries.sh: exit 0

Spec conformance (OpenAPM v0.1)

  • Spec edit: docs/src/content/docs/specs/openapm-v0.1.md updated
    (new/changed <a id="req-XXX"></a> anchor + prose + Appendix C
    row).
  • Manifest edit: docs/src/content/docs/specs/manifests/openapm-v0.1.requirements.yml
    updated.
  • Test edit: a @pytest.mark.req("req-XXX") test under
    tests/spec_conformance/ added or extended.
  • CONFORMANCE.{md,json} regenerated via
    uv run --extra dev python -m tests.spec_conformance.gen_statement
    and committed.
  • N/A -- this PR does not change OpenAPM-observable behaviour. OpenAPM v0.1 does not list mcp_omissions reasons; the commit carries an apm-spec-waiver.

…s for audit

apm install parked a package self-defined MCP server under the executables
gate without omission evidence, and install/update without
--trust-transitive-mcp retired a previously trusted transitive server while
filtering evidence against the pre-run lock. apm audit --ci then failed
config-consistency although install did what it promised.

CurrentMcpConfigView now parks servers the executables filter left out with
an 'unapproved-executables' reason bound to the declaration fingerprint,
and install evaluates omission evidence against the lock it produced, so a
kept (or failed-retirement) baseline still supersedes evidence. Audit replay
accepts the new reason only for gated package servers.

apm-spec-waiver: mcp_omissions reasons are APM lockfile detail not enumerated by OpenAPM v0.1

Refs #3720

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 19, 2026 05:27
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI 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.

🟢 Approval recommended

No active review issues block the changes aligning MCP omission evidence across install, update, and audit.

No open issues 🎉

What changed in this PR

Fixes #3720 by aligning MCP omission evidence between install, update, and audit, so intentionally excluded package servers do not cause false config-consistency failures.

Changes:

  • Records executables-gate omissions and validates them against the declaring package.
  • Evaluates omission evidence against the resulting lockfile, preserving retained baselines when retirement fails.
  • Adds regression tests, extends architecture guards, and documents the omission contract. Frozen-install comparison remains outside this PR’s scope.
File Description
tests/​unit/​integration/​test_mcp_config_view.py Tests gated omission evidence and audit replay.
tests/​unit/​install/​test_frozen_service_boundary.py Adapts assertions to lock-aware omission evaluation.
tests/​integration/​test_mcp_deliberate_omission_audit_lifecycle.py Covers gate omissions, transitive retirement, and failed cleanup.
tests/​integration/​test_architecture_mcp_omissions.py Tests rejection of omission-owner bypasses.
src/​apm_cli/​security/​executables.py Extracts the shared MCP gating predicate.
src/​apm_cli/​integration/​mcp_config_view.py Records and validates executables-gate omission evidence.
src/​apm_cli/​install/​mcp/​integration.py Computes omissions against the resulting lockfile.
scripts/​architecture_linter/​checks/​mutation_mcp_target_and_scope.py Guards the new omission-owner routes.
packages/​apm-guide/​.apm/​skills/​apm-usage/​commands.md Updates packaged audit guidance.
docs/​src/​content/​docs/​reference/​lockfile-spec.md Documents the new omission reason.
docs/​src/​content/​docs/​reference/​baseline-checks.md Clarifies intentional omissions and failed-retirement behavior.
CHANGELOG.md Records the audit-consistency fix.

Review effort: Balanced

Folds panel follow-ups on #3893. prepare_mcp_integration now decides
whether to resolve the executables allow map with is_executable_gated_mcp
instead of an inline copy, and the architecture rule rejects inline copies
of that predicate outside security/executables.py (architect F1). The
lifecycle test also revokes approval after deploy and expects the server
retired with unapproved-executables evidence (supply-chain F1). A kept
admitted baseline is asserted to record no omission, proven by mutation
(test-coverage F2). The lockfile spec now states omission evidence is
declaration-bound, not authenticated, and audit does not re-check
executables approval or org policy (supply-chain F2).

apm-spec-waiver: mcp_omissions reasons are APM lockfile detail not enumerated by OpenAPM v0.1

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

APM Review Panel: ship_with_followups

Fixes #3720: deliberate MCP omissions (executables gate, retired transitive trust) now leave declaration-bound evidence, so audit --ci passes, and damaged or stale evidence still fails.

panel-mode=lean; personas=python-architect,supply-chain-security-expert,test-coverage-expert,apm-ceo

cc Daniel Meppiel (@danielmeppiel) Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

This PR turns a false-positive governance failure into a reliable signal. Before the fix, two legitimate install outcomes made apm audit --ci fail config-consistency: the executables gate parking a dependency's self-defined server, and update retiring a transitive server after a trusted install. Users had a choice between a red CI and turning audit off. Now both sequences record mcp_omissions evidence through the existing CurrentMcpConfigView owner. The evidence is evaluated against the post-integration lock. Audit accepts the new unapproved-executables reason only where it is structurally eligible. All three specialists agree that owner discipline holds and the change fails closed. Supply-chain confirms that the change cannot hide admitted, root, registry, or changed-declaration servers, and that the new reason is a strict subset of the existing only-apm surface. Test-coverage ran both #3720 sequences at the installed-CLI tier and they pass.

No panelist raised a blocking-severity finding. Four in-scope gaps were folded into this PR (listed below). One of them matters in particular: reverting the post-write evaluation used to leave every functional suite green, with only a string check catching it. It is now guarded by an executed lifecycle assertion with mutation proof. The two remaining findings cross the approved scope and are deferred. Re-checking approval inside audit is explicitly excluded by the scope record, and that behavior is now documented. The frozen-path gate divergence already exists on main.

Dissent. None of the panelists disagree on severity; all findings are recommended-tier. Test-coverage findings carry missing-test evidence on governed-by-policy surfaces and are weighted higher.

Aligned with: Secure by default: the new reason only narrows the existing only-apm surface, and the revoke-path fold covers the direction where a regression could fail open. Governed by policy: audit stops punishing deliberate, policy-driven omissions while still failing damaged or stale evidence. Portable by manifest: the evidence is bound to the declaration in the lock, with no new flags. Pragmatic as npm: this removes a false-positive CI failure that pushed users to disable audit.

Panel summary

Persona B R N Takeaway
Python Architect 0 2 0 Owner discipline holds and post-lock evaluation is correct; inline gate check (folded) and caller-owned park step (frozen path, deferred).
Supply Chain Security Expert 0 2 0 No way to hide admitted, root, registry or changed-declaration servers; fail-closed holds. Revoke-path test and doc caveat (both folded).
Test Coverage Expert 0 2 0 Both #3720 sequences pass at the installed-CLI tier. Approval-without-reinstall window (deferred) and post-write evaluation guard (folded).

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 4 follow-ups

  1. [Test Coverage Expert] Decide the audit contract for executables granted in apm.yml but not yet reinstalled. Either audit replay resolves the effective allow map, or this stays accepted by design (now documented in lockfile-spec). -- Installed-CLI probe shows audit passes in this window while the server is undeployed. It is outside the current scope, and it is the remaining policy-drift gap.
  2. [Python Architect] Make InstallService._frozen_mcp_reasons reuse prepare_mcp_integration or a shared gated-view helper, and extend the boundary check over CurrentMcpConfigView.derive call sites in install/. -- --frozen and audit can still disagree about a parked server (pre-existing on main).
  3. [Python Architect] Move the derive, filter, and park steps for the gate into the CurrentMcpConfigView owner so callers cannot skip with_unapproved_executables. -- This structural fix closes the gap for future consumers too.
  4. [Supply Chain Security Expert] Assess whether omission evidence should carry an install-time attestation instead of a fingerprint over public lock data. -- Anyone who edits the lock can recompute the evidence; an authenticated mark would let audit prove that install made the omission.

Recommendation

Land #3893 now that the four in-PR folds are pushed (gate-predicate routing, revoke lifecycle, lockfile-spec caveat, and the kept-baseline assertion with mutation proof) and CI is green on the new head. Track the approval-without-reinstall audit contract (highest signal) and the frozen-path gate divergence separately.

Folded in this run

  • (panel) Route the allow-map check through is_executable_gated_mcp; the architecture rule now rejects inline copies of the predicate outside security/executables.py, with a bypass mutation case -- resolved in 83464e3.
  • (panel) Lifecycle test now revokes approval after deploy and expects the server retired from native config and lock, with unapproved-executables evidence and audit passing -- resolved in 83464e3.
  • (panel) Lockfile spec states omission evidence is declaration-bound, not authenticated, and that audit does not re-check executables approval or org policy -- resolved in 83464e3.
  • (panel) A kept admitted baseline (install --only apm after a trusted install) is asserted to record no omission evidence -- resolved in 83464e3.

Copilot signals reviewed

  • Review 5969794700 (overview, no inline comments) -- NOT-LEGIT as a fold item: approval recommended, nothing actionable. Round 2 found no new items.

Deferred (out-of-scope follow-ups)

  • (panel) Audit re-checking executables approval between apm approve and reinstall -- scope boundary: the approved scope record excludes re-evaluating executables approvals or org policy inside audit; now documented.
  • (panel) apm install --frozen derives its MCP view without the executables gate -- scope boundary: separate frozen-replay contract, pre-existing on main, outside the audit-scoped record.

Regression-trap evidence (mutation-break gate)

  • test_mcp_deliberate_omission_audit_lifecycle.py::test_executables_gate_parks_server_with_audit_evidence and test_architecture_mcp_omissions.py::test_mcp_omission_owner_routes_are_intact -- deleted current_view = current_view.with_unapproved_executables(approved); both FAILED as expected; guard restored.
  • test_mcp_omission_lifecycle.py::test_skills_only_preserves_admitted_baseline_and_real_drift[False,True] -- replaced prepared.omissions(lockfile) with the unfiltered view omissions; both FAILED as expected; guard restored.
  • New lifecycle file against unfixed src/: 3 of 4 failed (the failed-retirement baseline guard passes both ways).

Lint contract

ruff check and ruff format --check (ruff 0.15.12, CI paths) both silent; pylint R0801 10.00/10; scripts/lint-auth-signals.sh clean; scripts/lint-architecture-boundaries.sh exit 0.

CI

CI, Merge Gate, Spec conformance, CodeQL, NOTICE Drift and Deploy Docs succeeded on 1249756 (31 pass, 3 skipping). (after 0 CI fix iteration(s); one unrelated flaky rerun on the earlier head)

Mergeability status

PR head SHA CEO stance iters folds defers Copilot rounds CI mergeable mergeStateStatus notes
#3893 1249756 ship_with_followups 1 4 2 2 green MERGEABLE BLOCKED pending required review
Full per-persona findings

Python Architect

  • [recommended] prepare_mcp_integration still checked for the gate inline instead of calling is_executable_gated_mcp, at src/apm_cli/install/mcp/integration.py:82
    A parallel copy of the gate predicate could skip the allow map if the predicate changes, and newly gated servers would deploy silently.
    Suggested: route through the predicate and add a forbidden-pattern guard (folded).
  • [recommended] The derive, filter, and park steps live in the caller, so the deferred frozen path can still diverge, at src/apm_cli/install/mcp/integration.py:90
    Every new consumer must copy the two-step recipe.
    Suggested: reuse prepare_mcp_integration or a shared gated-view helper in the frozen path.

Supply Chain Security Expert

  • [recommended] No test covered revoking approval for a server that is already deployed, at tests/integration/test_mcp_deliberate_omission_audit_lifecycle.py:53
    A regression on revoke could fail open, or retire only the lock entry.
    Suggested: extend the lifecycle with approve, deploy, revoke, retire (folded).
  • [recommended] Omission reasons are bound to their declaration only by structure and are not authenticated, at src/apm_cli/integration/mcp_config_view.py:200
    Audit does not prove that install decided the omission, and does not re-check approval.
    Suggested: document it in lockfile-spec (folded).

Test Coverage Expert

  • [recommended] audit --ci passes when apm.yml approves a gate-parked package but no reinstall has run
    Silent-drift window in a governance gate; not a regression.
    Proof (missing at): tests/integration/test_mcp_deliberate_omission_audit_lifecycle.py::test_executables_gate_parks_server_with_audit_evidence -- proves: after approval, audit would flag the undeployed server until reinstall [governed-by-policy,secure-by-default]
  • [recommended] No executed test caught reverting omission evidence to the pre-write view
    Only the static architecture string check failed under that mutation.
    Proof (missing at): tests/integration/test_mcp_deliberate_omission_audit_lifecycle.py::test_failed_retirement_keeps_prior_baseline -- proves: a kept baseline never also records an omission (folded via the kept-baseline assertion)

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-merge-worker. This comment is AI-generated and may contain errors.

…NGELOG bullet

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

Lane L: main merged for landing

  • Pre-merge head: df774c66efa2dda0e0f30583281031adf73abedf
  • Merged origin/main fec774db97cca8a26a79dd013a6941aaaec8f825 (clean merge; GitHub reported DIRTY only on CHANGELOG.md, which this repo merges with merge=union).
  • New head: 1daa0d77c070bc857514acd3a54bee2181cb25d6
  • CHANGELOG: slotted, so queued PRs no longer collide at the section head while landing serially.
  • Lint: ruff check + ruff format --check silent at the new head; CI green at the new head.
  • Owner-touch report regenerated at the new head; every recorded functional test was re-run at that exact head and passed (one process at a time, no xdist).
  • Push: `` (plain push, no force).

This comment was generated by an AI agent (Lane L landing desk) on behalf of Daniel Meppiel (@danielmeppiel).

@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit f823cd0 into main Nov 19, 2026
51 of 54 checks passed
@danielmeppiel
Daniel Meppiel (danielmeppiel) deleted the danielmeppiel-fix-3720-mcp-omission-audit branch November 19, 2026 08:23
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 19, 2026
…utables

Approvals in apm.yml executables.allow can pin each hook file and MCP
server to a full SHA-256 of what runs. One owner, security/trust.py
admit(), decides every dependency-declared executable item for install,
update, install --frozen, apm audit --ci, apm approve and the install
prompt; security/trust_fingerprint.py is the only hasher. The lockfile
stays evidence only (mcp_omissions reasons definition-changed, denied).

- apm approve lists what each package runs and records pins; a changed
  definition is parked with a re-approve message.
- --trust-transitive-mcp stays a one-off and says it does not persist.
- install --frozen applies the executables gate like install (#3893).
- audit --ci fails servers the lock admits but apm.yml does not approve.
- Native plugin hooks are admitted per hook file from the install dir.
- Legacy true approvals still deploy and warn.
- Guards: executable-item-admission, trust-fingerprint, mcp-admission.

Spec: OpenAPM v0.1 amendment 0.1.64 adds req-sc-016 and extends req-sc-011
to frozen install.

Refs #3902

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 19, 2026
…utables

Approvals in apm.yml executables.allow can pin each hook file and MCP
server to a full SHA-256 of what runs. One owner, security/trust.py
admit(), decides every dependency-declared executable item for install,
update, install --frozen, apm audit --ci, apm approve and the install
prompt; security/trust_fingerprint.py is the only hasher. The lockfile
stays evidence only (mcp_omissions reasons definition-changed, denied).

- apm approve lists what each package runs and records pins; a changed
  definition is parked with a re-approve message.
- --trust-transitive-mcp stays a one-off and says it does not persist.
- install --frozen applies the executables gate like install (#3893).
- audit --ci fails servers the lock admits but apm.yml does not approve.
- Native plugin hooks are admitted per hook file from the install dir.
- Legacy true approvals still deploy and warn.
- Guards: executable-item-admission, trust-fingerprint, mcp-admission.

Spec: OpenAPM v0.1 amendment 0.1.64 adds req-sc-016 and extends req-sc-011
to frozen install.

Refs #3902

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 19, 2026
…utables

Approvals in apm.yml executables.allow can pin each hook file and MCP
server to a full SHA-256 of what runs. One owner, security/trust.py
admit(), decides every dependency-declared executable item for install,
update, install --frozen, apm audit --ci, apm approve and the install
prompt; security/trust_fingerprint.py is the only hasher. The lockfile
stays evidence only (mcp_omissions reasons definition-changed, denied).

- apm approve lists what each package runs and records pins; a changed
  definition is parked with a re-approve message.
- --trust-transitive-mcp stays a one-off and says it does not persist.
- install --frozen applies the executables gate like install (#3893).
- audit --ci fails servers the lock admits but apm.yml does not approve.
- Native plugin hooks are admitted per hook file from the install dir.
- Legacy true approvals still deploy and warn.
- Guards: executable-item-admission, trust-fingerprint, mcp-admission.

Spec: OpenAPM v0.1 amendment 0.1.64 adds req-sc-016 and extends req-sc-011
to frozen install.

Refs #3902

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 19, 2026
…utables

Approvals in apm.yml executables.allow can pin each hook file and MCP
server to a full SHA-256 of what runs. One owner, security/trust.py
admit(), decides every dependency-declared executable item for install,
update, install --frozen, apm audit --ci, apm approve and the install
prompt; security/trust_fingerprint.py is the only hasher. The lockfile
stays evidence only (mcp_omissions reasons definition-changed, denied).

- apm approve lists what each package runs and records pins; a changed
  definition is parked with a re-approve message.
- --trust-transitive-mcp stays a one-off and says it does not persist.
- install --frozen applies the executables gate like install (#3893).
- audit --ci fails servers the lock admits but apm.yml does not approve.
- Native plugin hooks are admitted per hook file from the install dir.
- Legacy true approvals still deploy and warn.
- Guards: executable-item-admission, trust-fingerprint, mcp-admission.

Spec: OpenAPM v0.1 amendment 0.1.64 adds req-sc-016 and extends req-sc-011
to frozen install.

Refs #3902

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 19, 2026
…utables

Approvals in apm.yml executables.allow can pin each hook file and MCP
server to a full SHA-256 of what runs. One owner, security/trust.py
admit(), decides every dependency-declared executable item for install,
update, install --frozen, apm audit --ci, apm approve and the install
prompt; security/trust_fingerprint.py is the only hasher. The lockfile
stays evidence only (mcp_omissions reasons definition-changed, denied).

- apm approve lists what each package runs and records pins; a changed
  definition is parked with a re-approve message.
- --trust-transitive-mcp stays a one-off and says it does not persist.
- install --frozen applies the executables gate like install (#3893).
- audit --ci fails servers the lock admits but apm.yml does not approve.
- Native plugin hooks are admitted per hook file from the install dir.
- Legacy true approvals still deploy and warn.
- Guards: executable-item-admission, trust-fingerprint, mcp-admission.

Spec: OpenAPM v0.1 amendment 0.1.64 adds req-sc-016 and extends req-sc-011
to frozen install.

Refs #3902

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 19, 2026
…utables (#3902) (#3918)

* feat(security): portable, content-pinned approval for dependency executables

Approvals in apm.yml executables.allow can pin each hook file and MCP
server to a full SHA-256 of what runs. One owner, security/trust.py
admit(), decides every dependency-declared executable item for install,
update, install --frozen, apm audit --ci, apm approve and the install
prompt; security/trust_fingerprint.py is the only hasher. The lockfile
stays evidence only (mcp_omissions reasons definition-changed, denied).

- apm approve lists what each package runs and records pins; a changed
  definition is parked with a re-approve message.
- --trust-transitive-mcp stays a one-off and says it does not persist.
- install --frozen applies the executables gate like install (#3893).
- audit --ci fails servers the lock admits but apm.yml does not approve.
- Native plugin hooks are admitted per hook file from the install dir.
- Legacy true approvals still deploy and warn.
- Guards: executable-item-admission, trust-fingerprint, mcp-admission.

Spec: OpenAPM v0.1 amendment 0.1.64 adds req-sc-016 and extends req-sc-011
to frozen install.

Refs #3902

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs(changelog): number the #3902 entries (#3918)

apm-spec-waiver: changelog-only follow-up to the req-sc-016 amendment commit

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(security): fold panel review of #3918 into the trust owner

- Native plugins: an org/project deny wins before any hook file is read,
  and per-file pins only narrow the package verdict (no empty-pin bypass).
- One per-type verdict reader, trust.package_type_verdicts, now backs
  apm policy explain, approve --list/--pending, doctor, lockfile
  exec_status and native status; G1 forbids pin-blind resolvers outside
  security/.
- One MCP enumerator feeds install, status and pins, so a changed pinned
  registry overlay reads as not deployed everywhere.
- --trust-transitive-mcp never re-approves a changed self-defined server.
- apm audit --ci discovers org policy like install (honoring --no-policy)
  and names an unavailable policy instead of passing silently.
- apm approve prints success after the write, exits 1 on a refused pin or
  declined prompt, and hints the APM 0.37 requirement on the first pin.
- Stale integration tests moved to the pinned shape; new lifecycle traps
  for --user vs audit, refusal exit code and uninstall survivors.

Refs #3902 (req-sc-016, req-sc-011)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* feat(security): approve native plugins with one whole-root pin

A natively loaded plugin is approved as ONE item,
executables.allow.<pkg>.plugin: sha256:<64 hex>, over the native plugin
file set (path, exec bit, bytes; APM's root apm.yml and .apm/ excluded).
Any byte or mode change parks the plugin with the re-approve hint.
Per-file hook pins and the stray-file refusal leave the native path;
split installs keep per-hook-file pins (D3).

Seam for #3290: security.trust.admit_native_plugin(allow_executables,
package_keys, plugin_root) -> Admission, and
security.trust_fingerprint.native_plugin_fingerprint, delegating to
utils.content_hash.compute_native_plugin_hash.

Refs req-sc-016 (unchanged; MCP-only text).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* test: assert every stored hook pin is a full fingerprint

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(security): honour native plugin pins only on the native path

Fold the supply-chain review of the whole-root plugin pin:
- a plugin pin admits only a native install (admitted Copilot Agent
  Plugin or Codex bundle); a split install reads item pins, which
  apm approve now records beside the plugin pin;
- with a pin, deny and the content hash are checked even when no
  executable type is detected; the native type set is one owner
  (native_root_exec_types);
- decision A: an executable surface that references root .apm/ or
  apm.yml parks the plugin (apm-owned-reference) with one diagnostic
  naming the reference;
- the dev-dependency lifecycle persists consent with apm approve
  before audit --ci (D6).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs(spec): fold the apm-spec-guardian panel into req-sc-016 (0.1.64)

- define the definition fingerprint: full sha256, never by prefix,
  from installed source, covering every launch-affecting field plus the
  resolved registry entry; unrecognized means not matching
- (b) also admits a per-user req-sc-010 pin (manifest decides); a
  dependency's own manifest never grants
- a stale pin is withheld even under the opt-in; trust.admit no longer
  lets --trust-transitive-mcp override a changed overlay pin
- define the scope terms, (a) semantics, org denial over every path,
  the req-sc-010 relation and the MCP-only scope; disclose that the
  grant key and byte construction are implementation-defined
- lifecycle: a lockfile depth edit cannot make a transitive server direct

Refs req-sc-016, req-sc-011.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(install): route #3938's select factory through the trust owner

CurrentMcpConfigView.select now takes McpAdmission instead of an
approve callable plus trust_transitive_self_defined; install, both
--frozen checks and audit admit through security/trust.py. Audit passes
exact=False (structural evidence) and still re-checks consent. The
omission-evidence rule pins the new routing; org deny-all records
reason 'denied'. Drop the duplicated frozen CHANGELOG line (#3938 owns
it).

Refs req-sc-011, req-sc-016.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(security): fold Copilot review of #3918 into the trust owner

- an existing MCP pin is checked even when the new declaration would
  not need approval (self-defined -> registry no longer bypasses it);
  the pin probe is policy-free, so no extra org policy discovery
- the admission subject fingerprints the authored declaration, as
  apm approve pins it
- apm approve --list/--pending report a transitive server that a
  legacy mcp: true leaves parked, matching install (D2)

Refs req-sc-016.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(security): fold the delta panel into the native trust owner

- every native install (pinned or not) is decided once by
  admit_native_plugin, over one type set (IR and manifest types passed
  as extra_types); the caller-side hook overrides are gone
- root .apm/ content that is not a byte copy of a pinned plugin file, or
  a symlink, parks the plugin (apm-owned-reference); approve refuses it
  with exit 1 and --pending says it cannot be approved
- a transitive native plugin with MCP needs the plugin pin (D2);
  admit_native_plugin gains keyword-only transitive and extra_types
- a malformed pin store falls back to the full context, which reports it
- denied items point at apm policy explain, not apm approve; the native
  listing says which split-install item pins it also records
- lifecycle: registry rewrite of a pinned server parks, legacy mcp: true
  shows in --pending, real per-file pins never register a native plugin

Refs req-sc-016.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(security): a bare grant map keeps the native gate on

admit_native_plugin read a plain allowExecutables mapping without a
routed trust context as gate-off and admitted an unapproved Codex
bundle; build a gate-on context from the map so it fails closed
(req-sc-009, test_codex_consumer_denies_unapproved_manifest_referenced_mcp).

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants