[bug] apm install integrates files in .github/instructions/ that are not produced by an installed plugin

[danielmeppiel]

Summary

When a file is dropped directly into .github/instructions/ (not produced by any installed plugin), apm install appears to integrate it as if it were a managed primitive. The subsequent unmanaged-files policy check then reports zero unmanaged files, because everything in the monitored directory is treated as managed.

Repro

Starting from a project with installed plugins:

cat > .github/instructions/hand-rolled.instructions.md <<'INSTR'
---
applyTo: "**"
description: "Hand-rolled, not from any plugin"
---
hello
INSTR
apm install

Install logs include a line like instructions/: ..., hand-rolled.instructions.md. The file is now treated as integrated.

Then:

apm audit --ci --policy <some-policy-with-unmanaged_files-deny>

unmanaged-files reports clean. The hand-rolled file evades the governance check that the policy is meant to enforce.

Expected

apm install should only deploy files that originate from declared plugin manifests. Files that pre-exist in monitored governance directories without provenance should be:

• left untouched (not "integrated" into the managed set), and
• visible to unmanaged-files audit when the policy declares action: deny.

Workaround

For the demo we used in this report we routed the unmanaged file to .github/hooks/ instead, which apm install does NOT touch. That correctly trips the audit, but it also reveals the asymmetry: the same content rule applies to all three monitored directories per policy spec, but only one of them is actually enforceable today.

Impact

A consumer can side-step org policy unmanaged_files: action: deny by simply placing instruction files at the right path before installing — apm install will adopt them silently and policy will treat them as managed.

Related

Filed alongside #1198 (extends: silently downgrades unmanaged_files).

[github-actions]

Triage decision

accept

Proposed labels

theme/security
area/content-security
area/audit-policy
type/bug
status/accepted
priority/high

Milestone

0.12.5 (recommended; unable to apply programmatically -- milestone number not resolvable without authenticated CLI)

Suggested next action

Change the install flow to derive the "managed file" set exclusively from plugin manifest declarations rather than from directory listing, so pre-existing files in governance directories are not silently adopted.

Suggested issue comment

Thanks for the clear repro and the impact analysis -- this is a confirmed security bypass in the install + audit interaction.

The root cause is that `apm install` currently scans the target governance directories and treats all found files as managed, rather than tracking only what it deployed from plugin manifests. The lockfile's `deployed_file_hashes` already records what was deployed by APM; the audit flow should treat anything in a monitored directory that is NOT in `deployed_file_hashes` as unmanaged -- regardless of when or how it got there.

**Accepted.** The fix requires changing the install flow so the "managed set" is manifest-derived (not directory-derived), and ensuring the audit's unmanaged-file check uses `deployed_file_hashes` as the authoritative source of truth.

This is related to #1198 (policy inheritance downgrade), which removes a second layer of governance defense. Both should ideally land together.

Target: 0.12.5 patch. A regression test that places a hand-rolled file before `apm install` and asserts it appears in the unmanaged-file audit result would be a strong addition.

For context on the governance threat model: (microsoft.github.io/redacted)

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user expectation is unambiguous: apm install deploys what plugin manifests declare, and apm audit catches everything else. The bug inverts this: a pre-placed file gets "adopted" as managed by install, removing it from the unmanaged-file check. The asymmetry noted in the report (.github/hooks/ is not touched by install and correctly trips the audit; .github/instructions/ is touched and incorrectly passes) is a concrete surface-level symptom that makes the design gap visible.

Supply Chain Security Expert -- Risk-Surface Reviewer

This is a direct supply chain governance bypass. An attacker or misconfigured automation can place arbitrary content in .github/instructions/ before running apm install, and the governance check will treat it as managed. The affected surface is area/content-security (unauthorized instruction files) and area/audit-policy (audit produces a false clean result). theme/security is required -- this is not a UX rough edge but a structural hole in the supply chain defense.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- danielmeppiel is a COLLABORATOR with extensive prior interactions; tone adjustment is not needed.

Python Architect -- Architecture Reviewer

The fix requires a clear architectural decision: the install flow must produce a manifest-derived file set (what it deployed) and persist it to the lockfile; the audit flow must use that record as the managed-file oracle, not a live directory scan. The deployed_file_hashes field already exists in apm.lock.yaml and serves this purpose. The cross-cutting impact is: install (writer), audit/unmanaged-files check (reader), and any command that currently derives "managed" from directory contents. Narrowly scoped; status/accepted is appropriate since the design is clear.

Doc Writer -- Documentation Reviewer

Not activated -- this is a bug fix in internal install/audit logic. No new user-facing CLI surface or governance concept is introduced. Existing policy reference documentation already describes the intended behavior.

APM CEO -- Triage Arbiter

A supply chain governance bypass that can be triggered without elevated access is priority/high by definition. The fix path is clear and aligns with existing lockfile architecture (deployed_file_hashes). Accepting at priority/high for the 0.12.5 patch. This issue and #1198 together represent two layers of the same governance defense failing; they should land in the same release cycle, ideally the same PR or back-to-back PRs.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/security",
  "areas": ["area/content-security", "area/audit-policy"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": "0.12.5",
  "next_action": "Change install to derive the managed-file set from plugin manifest declarations only; have the audit unmanaged-file check use deployed_file_hashes as its oracle.",
  "comment_markdown": "Thanks for the clear repro and the impact analysis -- this is a confirmed security bypass in the install + audit interaction.\n\nThe root cause is that `apm install` currently scans the target governance directories and treats all found files as managed, rather than tracking only what it deployed from plugin manifests. The lockfile's `deployed_file_hashes` already records what was deployed by APM; the audit flow should treat anything in a monitored directory that is NOT in `deployed_file_hashes` as unmanaged -- regardless of when or how it got there.\n\n**Accepted.** The fix requires changing the install flow so the \"managed set\" is manifest-derived (not directory-derived), and ensuring the audit's unmanaged-file check uses `deployed_file_hashes` as the authoritative source of truth.\n\nThis is related to #1198 (policy inheritance downgrade), which removes a second layer of governance defense. Both should ideally land together.\n\nTarget: 0.12.5 patch. A regression test that places a hand-rolled file before `apm install` and asserts it appears in the unmanaged-file audit result would be a strong addition.\n\nFor context on the governance threat model: (microsoft.github.io/redacted)
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Note

🔒 Integrity filter blocked 12 items

The following items were blocked because they don't meet the GitHub integrity level.

• #1120 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1122 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1130 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1138 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1156 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1157 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1195 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1203 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1209 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1210 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1220 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1222 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Triage Panel · ● 1.1M · ◷