From cf26034617ef39feee32941df2ec7712911d8e03 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Thu, 19 Nov 2026 20:18:49 +0100 Subject: [PATCH 1/6] docs: reground pages freed by #3918 and leftover 0.37 drift Refs #3948. Wave 2 of the 0.37 docs sweep (docs-corpus-audit): the pages #3918 owned (concepts, install-packages, enterprise policy and security, mcp-as-primitive, reference update/manifest-schema, apm-usage dependencies/governance) plus reference/cli/deps.md (#3916 refusal). Pages owned by in-flight #3290 are not touched. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/src/content/docs/concepts/glossary.md | 6 +- docs/src/content/docs/concepts/lifecycle.md | 4 +- .../docs/concepts/primitives-and-targets.md | 4 +- .../content/docs/consumer/install-packages.md | 11 ++- .../src/content/docs/enterprise/apm-policy.md | 12 +-- .../docs/enterprise/governance-guide.md | 27 ++++--- .../docs/enterprise/policy-reference.md | 25 +++--- docs/src/content/docs/enterprise/security.md | 11 +-- .../author-primitives/mcp-as-primitive.md | 6 +- docs/src/content/docs/reference/cli/deps.md | 2 + docs/src/content/docs/reference/cli/update.md | 4 +- .../content/docs/reference/manifest-schema.md | 6 +- .../.apm/skills/apm-usage/dependencies.md | 20 +++-- .../.apm/skills/apm-usage/governance.md | 76 +++++++++++-------- 14 files changed, 122 insertions(+), 92 deletions(-) diff --git a/docs/src/content/docs/concepts/glossary.md b/docs/src/content/docs/concepts/glossary.md index d36acdad54..75df9c901b 100644 --- a/docs/src/content/docs/concepts/glossary.md +++ b/docs/src/content/docs/concepts/glossary.md @@ -22,7 +22,7 @@ Source: `src/apm_cli/deps/lockfile.py`. ### apm.yml The package manifest. A YAML file at the package root that declares -`name`, `version`, `dependencies`, `scripts`, `targets` / `target`, and metadata. Both +`name`, `version`, `dependencies`, `scripts`, `targets` (singular `target` is deprecated), and metadata. Both the unit of authoring and the unit of consumption -- a directory becomes an APM package the moment it has an `apm.yml`. @@ -253,10 +253,10 @@ Source: `src/apm_cli/models/apm_package.py`, ### target -The `targets:` field in `apm.yml` (or legacy `target:`). Names which harnesses the package +The `targets:` field in `apm.yml` (singular `target:` is deprecated). Names which harnesses the package compiles for (`copilot`, `claude`, `grok-build`, `cursor`, `codex`, `gemini`, `antigravity`, `opencode`, `windsurf`, `kiro`, `hermes`, `grok-bot`, or -`agent-skills`). `all` is a CLI `--target` value only. Drives which integrator runs and +`agent-skills`; `vscode` is a deprecated alias of `copilot`). `all` is a CLI `--target` value only. Drives which integrator runs and which directories receive output during `apm install` and `apm compile`. NOT the harness itself. Target is the declaration; the harness is the diff --git a/docs/src/content/docs/concepts/lifecycle.md b/docs/src/content/docs/concepts/lifecycle.md index 39017819cc..0d0323098c 100644 --- a/docs/src/content/docs/concepts/lifecycle.md +++ b/docs/src/content/docs/concepts/lifecycle.md @@ -40,8 +40,8 @@ targets](../primitives-and-targets/) for what each target receives. **Common surprises** -- Re-running `apm init` in a directory that already has `apm.yml` warns and asks before overwriting it; `-y` overwrites without asking. -- `targets:` must contain at least one target. Omit the field (or leave legacy `target:` blank) when you want auto-detection at compile time. +- Re-running `apm init` in a directory that already has `apm.yml` warns and asks before overwriting it; `-y` overwrites without asking. Existing targets carry over, with deprecated singular `target:` rewritten to `targets:`. +- `targets:` must contain at least one target. Omit the field when you want auto-detection at compile time. **Read more:** [`apm init` reference](/apm/reference/cli/init/), [package anatomy](/apm/concepts/package-anatomy/). diff --git a/docs/src/content/docs/concepts/primitives-and-targets.md b/docs/src/content/docs/concepts/primitives-and-targets.md index 85db4bb131..e3664ef0ae 100644 --- a/docs/src/content/docs/concepts/primitives-and-targets.md +++ b/docs/src/content/docs/concepts/primitives-and-targets.md @@ -78,7 +78,7 @@ GitHub Copilot CLI canvas extensions: a directory bundle whose entry file is `ex ## Target catalogue -Each target is identified by a slug used in `apm.yml`'s `targets:` field or on the `--target` flag. `apm.yml` accepts the canonical targets (`copilot`, `claude`, `grok-build`, `cursor`, `opencode`, `codex`, `gemini`, `antigravity`, `windsurf`, `kiro`, `agent-skills`, `hermes`, `grok-bot`). `agent-skills`, `antigravity`, `hermes`, and `grok-bot` can be selected explicitly or listed in `apm.yml`, but they are not auto-detected or included in `all`. The output directory is where APM writes deployed primitives; at project scope, skills for `copilot`, `cursor`, `codex`, `gemini`, `opencode`, and `windsurf` land in the shared `.agents/skills/`. +Each target is identified by a slug used in `apm.yml`'s `targets:` field or on the `--target` flag. `apm.yml` accepts the canonical targets (`copilot`, `claude`, `grok-build`, `cursor`, `opencode`, `codex`, `gemini`, `antigravity`, `windsurf`, `kiro`, `agent-skills`, `hermes`, `grok-bot`). `vscode` is a deprecated alias of `copilot`. `intellij` is never recorded in `apm.yml`; use `copilot` for GitHub Copilot in JetBrains IDEs. `agent-skills`, `antigravity`, `hermes`, and `grok-bot` can be selected explicitly or listed in `apm.yml`, but they are not auto-detected or included in `all`. The output directory is where APM writes deployed primitives; at project scope, skills for `copilot`, `cursor`, `codex`, `gemini`, `opencode`, and `windsurf` land in the shared `.agents/skills/`. | Slug | Output directory | Compile family | |---|---|---| @@ -97,7 +97,7 @@ Each target is identified by a slug used in `apm.yml`'s `targets:` field or on t Notes per target: -- **copilot** -- GitHub Copilot (CLI + IDE). User scope: instructions, prompts, agents, and hooks deploy under `~/.copilot/` (instructions as `~/.copilot/instructions/**/*.instructions.md`, mirroring the project-scope layout); skills go to `~/.agents/skills/`; a dependency canvas deploys to `~/.copilot/extensions/`. +- **copilot** -- GitHub Copilot (CLI + IDE). Project MCP servers go to root `.mcp.json`, shared with Claude Code (which ignores Copilot's `tools` allow-list). User scope: instructions, prompts, agents, and hooks deploy under `~/.copilot/` (instructions as `~/.copilot/instructions/**/*.instructions.md`, mirroring the project-scope layout); skills go to `~/.agents/skills/`; a dependency canvas deploys to `~/.copilot/extensions/`. - **claude** -- Claude Code. Full user-scope support. Hooks merge into `.claude/settings.json` rather than living as separate files. - **grok-build** -- Grok Build. Rules, agents, commands, and skills use `.grok/`; compiled instructions also produce `AGENTS.md`. - **cursor** -- Cursor IDE. Rules use the `.mdc` extension. Full user-scope support; instructions deploy to `~/.cursor/rules/*.mdc`, which local Cursor 2.1+ clients include in context (see [Cursor user scope](../../reference/targets-matrix/#cursor)). diff --git a/docs/src/content/docs/consumer/install-packages.md b/docs/src/content/docs/consumer/install-packages.md index 94882e4bf8..7b3dbfea2a 100644 --- a/docs/src/content/docs/consumer/install-packages.md +++ b/docs/src/content/docs/consumer/install-packages.md @@ -61,7 +61,8 @@ apm install ``` Supported reference forms: `owner/repo` shorthand (with optional -`#ref` for a tag, branch, or commit), full HTTPS or SSH git URLs, +`#ref` for a tag, branch, or commit; resolved against `default_host:` when +`apm.yml` sets one), full HTTPS or SSH git URLs, virtual subdirectory paths into a monorepo, single-file references, and local paths starting with `./`, `../`, or `/`. For private hosts and tokens, see [Authentication](../authentication/). @@ -177,12 +178,14 @@ same bytes. Commit the lockfile. :::note[Lockfile replay] Plain `apm install` and `apm install --frozen` replay locked commits for -unchanged dependencies, including transitive packages, and reuse matching +unchanged dependencies, including transitive packages and marketplace entries +(without contacting the marketplace), and reuse matching [cached package content](../../reference/cli/cache/) when available. This keeps mutable branches and tags pinned to their recorded commits. Run [`apm update`](../../reference/cli/update/) or `apm install --refresh` to -establish current upstream mutable refs. `apm outdated` checks the same current +establish current upstream mutable refs; both revalidate marketplaces and fail +rather than use stale cached data. `apm outdated` checks the same current state without changing the lockfile. See the [lockfile specification](../../reference/lockfile-spec/) for the replay contract. @@ -281,6 +284,8 @@ and the full flag reference, or run `apm install --help`. - **Drift between `apm_modules/` and the lockfile.** Run `apm audit --ci` locally to reproduce the CI gate; see [Update and refresh](../update-and-refresh/) to recover. +- **Lockfile written by a newer APM.** APM refuses to change or replay it, + naming both versions. Upgrade APM; there is no override. - **Skipped symlinked agent source.** `apm install` warns and skips agent files or directories that are symlinks (for example `.apm/agents -> ../agents`). Fix by shipping real files and directories in diff --git a/docs/src/content/docs/enterprise/apm-policy.md b/docs/src/content/docs/enterprise/apm-policy.md index 1215d42a54..3c9349a7d4 100644 --- a/docs/src/content/docs/enterprise/apm-policy.md +++ b/docs/src/content/docs/enterprise/apm-policy.md @@ -136,10 +136,10 @@ dependencies: mcp: transport: - allow: [http, stdio] # explicit allow list: blocks sse and streamable-http + allow: [http, stdio] # http = streamable-http; blocks sse ``` -Three rules: only contoso and microsoft packages are allowed, untrusted-org is blocked outright, and MCP transports are restricted to `http` and `stdio`. With no `mcp.transport.allow` set, all transports are permitted by default; the example above shows how to restrict. +Three rules: only contoso and microsoft packages are allowed, untrusted-org is blocked outright, and MCP transports are restricted to `http` and `stdio`, judged on the transport install writes (see [`transport.allow`](../policy-reference/#transportallow)). With no `mcp.transport.allow` set, all transports are permitted by default; the example above shows how to restrict. > **Note on transitive MCPs:** the `mcp.trust_transitive` policy field is currently parsed but not enforced -- consent is a pinned [`apm approve`](../../reference/cli/approve/#pinned-approvals) grant in `apm.yml`, or the one-run `--trust-transitive-mcp` flag (defaults to deny). See [Governance Guide section 5a](../governance-guide/#5a-what-does-not-enforce-policy) for the full list of parsed-but-not-enforced fields. @@ -186,7 +186,7 @@ For setup, see [Enforce in CI](../enforce-in-ci/). ## Tighten-only inheritance -A repo can have its own `apm-policy.yml` that **extends** the org policy. Children can only **tighten** rules, never relax them. This means a repo can be more restrictive than the org, but cannot widen what the org has allowed. +A repo can have its own `apm-policy.yml` that **extends** the org policy (discovery finds only the org policy; pass a repo file to `apm audit --ci --policy`). Children can only **tighten** rules, never relax them. This means a repo can be more restrictive than the org, but cannot widen what the org has allowed. The merge rules in plain English: @@ -222,8 +222,8 @@ dependencies: `apm install` halts before any file is written. The CLI emits a single-line violation followed by a remediation hint: ``` -[x] Policy violation: untrusted-org/random-skills -- denied by pattern: untrusted-org/** - Run `apm audit --ci --policy org` for the full report. +[x] Policy violation: github.com/untrusted-org/random-skills -- denied by pattern: untrusted-org/** + Blocked by org policy at org:/.github-private (dependency-denylist) -- remove `github.com/untrusted-org/random-skills` from apm.yml, contact admin to update policy, or use `--no-policy` for one-off bypass ``` Exit code is non-zero so CI fails. Run `apm audit --ci --policy org` (in CI or locally) for the full SARIF report including which policy file in the inheritance chain produced the rule. @@ -276,7 +276,7 @@ apm policy status --policy-source contoso/governance # any owner/repo apm audit --ci --policy ./apm-policy.yml ``` -`apm install` has no `--policy` flag — discovery runs automatically from your git remote. Use `--no-cache` to force a fresh fetch. +`apm install` has no `--policy` flag -- discovery runs automatically from your git remote. Add `--no-cache` to `apm policy status` or `apm audit` to force a fresh fetch. ### 3. The schema in one screen diff --git a/docs/src/content/docs/enterprise/governance-guide.md b/docs/src/content/docs/enterprise/governance-guide.md index a92689dac5..699c37eaea 100644 --- a/docs/src/content/docs/enterprise/governance-guide.md +++ b/docs/src/content/docs/enterprise/governance-guide.md @@ -78,7 +78,7 @@ The scope matrix below is the contract. Every row maps a security or operational | Registry source policy | `registry_source.require`, `.allow_non_registry` | `registry-source` | Yes | Yes | | MCP server allowlist | `mcp.allow` | `mcp-allowlist` | Yes (direct + transitive) | Yes | | MCP server denylist | `mcp.deny` | `mcp-denylist` | Yes (direct + transitive) | Yes | -| MCP transport allowlist | `mcp.transport.allow` | `mcp-transport` | Yes | Yes | +| MCP transport allowlist | `mcp.transport.allow` | `mcp-transport` | Yes (transport install writes; also `apm update`) | Yes | | Self-defined MCP control | `mcp.self_defined` | `mcp-self-defined` | Yes | Yes | | Compilation target allowlist | `compilation.target.allow` / `.enforce` | `compilation-target` | Yes (post-targets phase, effective selection) | Yes (targets declared in `apm.yml`) | | Compilation strategy | `compilation.strategy.enforce` | `compilation-strategy` | `[i] audit-only` | Yes | @@ -183,7 +183,7 @@ Policies can extend other policies up to 5 levels deep (`MAX_CHAIN_DEPTH = 5`, e ```mermaid graph TD - Hub["enterprise-hub-org/.github/
apm-policy.yml
broad allow lists,
enforcement: warn"] --> Org["contoso/.github/
apm-policy.yml
extends: enterprise-hub-org
adds deny + tightens
enforcement: block"] + Hub["enterprise-hub-org/.github/
apm-policy.yml
broad allow lists,
enforcement: warn"] --> Org["contoso/.github/
apm-policy.yml
extends: enterprise-hub-org/.github
adds deny + tightens
enforcement: block"] Org --> Repo["contoso/web-app/
apm.yml policy stanza
policy.hash pin,
fetch_failure_default: block"] Hub --> Merge["[*] merge_policies()
tighten-only:
allow=intersect, deny=union,
enforcement=max(...),
max_depth=min(...),
require_pinned_constraint=OR"] Org --> Merge @@ -222,7 +222,7 @@ mcp: ```yaml name: "Contoso engineering" version: "1.0.0" -extends: "enterprise-hub-org" +extends: "enterprise-hub-org/.github" enforcement: block dependencies: deny: @@ -236,9 +236,9 @@ mcp: **Repo** -- `contoso/web-app/apm.yml`: ```yaml -packages: - - name: contoso/web-standards - version: "^1.0" +dependencies: + apm: + - contoso/web-standards#v1.0.0 policy: hash: "sha256:abc123..." # pin the fetched org policy fetch_failure_default: block # fail-closed if discovery fails @@ -255,11 +255,11 @@ policy: | `mcp.transport.allow` | `stdio` | Org narrowed `[stdio, http]` to `[stdio]`. Intersect rule. | | `mcp.self_defined` | `deny` | Org escalated. | -**Counter-example: a child cannot relax a parent.** If `contoso/web-app/apm.yml` tried to override the org's `block` back down to `warn`: +**Counter-example: a child cannot relax a parent.** If a team policy that extends the org policy tried to set the org's `block` back down to `warn`: ```yaml -policy: - enforcement: warn # rejected: org policy is block; child cannot relax +extends: "contoso/.github" +enforcement: warn # dropped: org policy is block; child cannot relax ``` The merge rule for `enforcement` is `max(parent, child)` ordered `warn < block`, so the org's `block` wins. The child's `warn` is silently dropped from the effective policy. The same applies to allow-list widening (intersect rule) and deny-list removal (union rule): tightening flows down, relaxation does not. @@ -306,7 +306,7 @@ When `apm install` returns exit code 0 and the effective org policy is in `enfor - Every APM dependency declared in `apm.yml` matches `dependencies.allow` and is not matched by `dependencies.deny`. - Every package in `dependencies.require` is present and at the required version (with one nuance: `require_resolution: project-wins` downgrades version mismatches to warnings, by design). -- Every direct MCP server matches `mcp.allow`, is not matched by `mcp.deny`, uses an allowed transport, and respects the `mcp.self_defined` rule. +- Every direct MCP server matches `mcp.allow`, is not matched by `mcp.deny`, uses an allowed transport (the one install writes; a registry server APM cannot resolve fails), and respects the `mcp.self_defined` rule. - Every transitive MCP server discovered from APM packages was re-checked against the same `mcp.*` rules in a second pass. - The effective target selection (`--target`, `apm.yml`, `apm config target`, or auto-detection) includes `compilation.target.enforce` when it is set; otherwise every selected target is in `compilation.target.allow`. `enforce` takes precedence, so `allow` is not checked when both are set. Targets compare after aliases resolve (`vscode` is `copilot`). - The fetched policy file matched any `policy.hash` pin in `apm.yml`. If the hash did not match, install failed closed regardless of `fetch_failure_default` -- hash-mismatch is unconditionally fail-closed in non-dry-run install paths. (`apm install --dry-run` logs the mismatch but does not exit non-zero -- see section 14 gap.) @@ -354,7 +354,7 @@ Workarounds when the network is unreliable: | Network failure (`cache_miss_fetch_fail`) | Fail-OPEN, log warning, install proceeds with no policy | `policy.fetch_failure_default: block` in `apm.yml` | [policy-reference#95-network-failure-semantics](../policy-reference/#95-network-failure-semantics) | | Cached stale (past effective `cache.ttl`, within the 7-day ceiling; refresh failed) | Warn and proceed with cached policy | `fetch_failure: block` set in the cached org policy itself | [policy-reference#95-network-failure-semantics](../policy-reference/#95-network-failure-semantics) | | Malformed YAML (`malformed`) (org policy file) | Fail-OPEN by default | `policy.fetch_failure_default: block` | `policy/parser.py` | -| **No policy resolved (`no_git_remote` / `absent` / `empty`)** | **Fail-OPEN, log warning** | `policy.fetch_failure_default: block` in `apm.yml` -- applies to BOTH `apm install` and `apm audit --ci` | [policy-reference#951-no-policy-outcomes](../policy-reference/#951-no-policy-outcomes-no_git_remote--absent--empty) | +| **No policy resolved (`no_git_remote` / `absent` / `empty`)** | **Fail-OPEN**; `apm audit --ci` warns, `apm install` warns on `empty` and shows the others only with `--verbose` | `policy.fetch_failure_default: block` in `apm.yml` -- applies to BOTH `apm install` and `apm audit --ci` | [policy-reference#951-no-policy-outcomes](../policy-reference/#951-no-policy-outcomes-no_git_remote--absent--empty) | | Hash-mismatch (project pin vs fetched) | **Always fail-CLOSED** | n/a (cannot be relaxed) | [policy-reference#95-network-failure-semantics](../policy-reference/#95-network-failure-semantics) | | Garbage response | Fail-OPEN by default | `policy.fetch_failure_default: block` | [policy-reference#95-network-failure-semantics](../policy-reference/#95-network-failure-semantics) | | **Explicit `apm audit --ci --policy ` cannot be loaded** (missing file, unreachable, malformed, garbage, not found) | **Always fail-CLOSED** (`[x]`, exit 1) | n/a -- `policy.fetch_failure_default` does not apply; `--policy org` keeps discovery semantics | [policy-reference#95-network-failure-semantics](../policy-reference/#95-network-failure-semantics) | @@ -413,7 +413,7 @@ jobs: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: { python-version: "3.12" } - - run: pip install apm-cli==X.Y.Z # REPLACE: pin to current version, see /installation + - run: pip install apm-cli==X.Y.Z # REPLACE: pin to current version, see /installation; audit refuses a lockfile from a newer APM - run: apm install - run: apm audit --ci -f sarif --output apm-audit.sarif - uses: github/codeql-action/upload-sarif@v3 @@ -574,7 +574,6 @@ mcp: compilation: target: allow: ["copilot", "claude"] - enforce: true ``` **Hub + org + repo (100+ repos)** -- enterprise hub with broad allows, org extending and tightening, repos pinning the hash: @@ -588,7 +587,7 @@ dependencies: allow: ["microsoft/*", "contoso/*", "partner-corp/*"] # contoso/.github-private/apm-policy.yml -extends: "enterprise-hub-org" +extends: "enterprise-hub-org/.github-private" enforcement: block dependencies: deny: ["untrusted-org/*"] diff --git a/docs/src/content/docs/enterprise/policy-reference.md b/docs/src/content/docs/enterprise/policy-reference.md index 09b286d1c7..2a551c84f3 100644 --- a/docs/src/content/docs/enterprise/policy-reference.md +++ b/docs/src/content/docs/enterprise/policy-reference.md @@ -190,7 +190,7 @@ dependencies: ### `require_pinned_constraint` -Default: `false`. When `true`, every direct APM dependency declared in `apm.yml` must use a bounded constraint -- a semver range with an upper bound, a literal version tag (`v1.5.3`, or `pkg-a-v1.5.3` / `pkg-a--v1.5.3` for a package named `pkg-a`), an exact package release tag (`shadcn@4.12.0`, `@upstash/context7-mcp@4.4.4`), or a 40-char commit SHA. Empty refs, bare branch names, wildcards (`*`, `1.x`), and open-upper ranges (`>=1.0.0`, `>1.0.0`) all fail the `dependency-pinned-constraint` check. +Default: `false`. When `true`, every direct APM dependency declared in `apm.yml` must use a bounded constraint -- a semver range with an upper bound, a literal version tag (`v1.5.3`, or `pkg-a-v1.5.3` / `pkg-a--v1.5.3` for a package named `pkg-a`), an exact package release tag (`shadcn@4.12.0`, `@upstash/context7-mcp@4.4.4`), or a 40-char commit SHA. Empty refs, bare branch names, wildcards (`*`, `1.x`), and open-upper ranges (`>=1.0.0`, `>1.0.0`) all fail the `dependency-pinned-constraint` check. Versions with leading zeros or non-ASCII digits (`v01.2.3`, `v1.2.3-01`) are not SemVer and fail as bare branches. The check judges the constraint as declared in `apm.yml`, not the tag a range resolves to; fresh installs, locked reinstalls, updates, and `apm audit` agree. A dependency redirected by a [`replace:` rule](../../consumer/manage-dependencies/#replace-a-source-candidate) is judged by the ref the rule selects. @@ -330,7 +330,7 @@ Whether the `scripts` section is allowed in `apm.yml`: ### `content_types.allow` -Parsed allow-list for package content types. This field is not enforced in APM 0.16.0: +Parsed allow-list for package content types. This field is not enforced yet: ```yaml manifest: @@ -459,7 +459,7 @@ Deny patterns are evaluated first. If a reference matches any deny pattern, it f | `deployed-files-present` | All files listed in lockfile `deployed_files` exist on disk | | `no-orphaned-packages` | No lockfile packages are absent from the manifest | | `skill-subset-consistency` | `skills:` selections in `apm.yml` match `skill_subset` in the lockfile | -| `config-consistency` | MCP server configs match lockfile baseline | +| `config-consistency` | MCP server configs match lockfile baseline; servers the executables gate left out pass, and a server the lockfile admits but `apm.yml` does not approve fails | | `content-integrity` | Deployed files contain no critical hidden Unicode characters and their SHA-256 hashes match the lockfile | | `includes-consent` | Advisory check that `includes:` selections in the manifest match what was deployed | @@ -539,6 +539,7 @@ A child policy can only tighten constraints — never relax them: | Field | Merge rule | |-------|-----------| | `enforcement` | Escalates: `off` < `warn` < `block` | +| `fetch_failure` | Escalates: `warn` < `block` | | `cache.ttl` | `min(parent, child)` | | Allow lists | Intersection — child narrows parent's allowed set | | Deny lists | Union — child adds to parent's denied set | @@ -672,8 +673,8 @@ to the project's own subgroup (the nearest one is the `policy.hash` leaf); a flat `/` remote probes only `/apm-policy`. Set `GITLAB_HOST` or `APM_GITLAB_HOSTS` to recognize a self-managed host, and use `APM_GITLAB_POLICY_REPO` to select another project name. Plain git remotes -fall through with no policy applied. Repositories with no detectable git remote -emit an explicit "could not determine org" line and skip discovery. +fall through with no policy applied. With `--verbose`, repositories with no detectable git remote +print a "could not determine org" line and skip discovery. The `--policy ` flag is **audit-only today** — it works on `apm audit --ci` but is not yet wired through `apm install`. Use the escape hatches in section 8 if you need to bypass install-time enforcement for a single invocation. @@ -856,7 +857,7 @@ $ echo $? ### 9. Cache and offline behaviour -Resolved effective policy is cached under the platform user cache at `apm/policy_v1//`. Default TTL is `cache.ttl` from the policy itself (`3600` seconds). Beyond TTL, APM will serve a stale cache on refresh failure with a loud warning, up to a hard ceiling of 7 days (`MAX_STALE_TTL`). `--no-cache` forces a fresh fetch and ignores any cached entry. Cache writes are atomic (temp file + rename) to survive concurrent installs. +Resolved effective policy is cached under the platform user cache at `apm/policy_v1//`. Default TTL is `cache.ttl` from the policy itself (`3600` seconds). Beyond TTL, APM will serve a stale cache on refresh failure with a loud warning, up to a hard ceiling of 7 days (`MAX_STALE_TTL`). `--no-cache` on `apm audit` and `apm policy status` forces a fresh fetch and ignores any cached entry. Cache writes are atomic (temp file + rename) to survive concurrent installs. ### 9.5. Network failure semantics @@ -877,7 +878,7 @@ Three additional outcomes describe "discovery succeeded but produced no enforcea These outcomes honour the same knob as fetch failures on both `apm install` and `apm audit --ci`: -- **`warn` (default):** `[!]` warning on stderr explaining the cause; install / audit proceeds. +- **`warn` (default):** `apm audit --ci` prints a `[!]` warning on stderr explaining the cause; `apm install` warns on `empty` and shows `absent` / `no_git_remote` only with `--verbose`. Both proceed. - **`block`:** `[x]` error on stderr; install raises `PolicyViolationError`, `apm audit --ci` exits 1. `--policy org` falls through these three outcomes. Any other explicit `--policy ` fails closed when it yields no policy (see above); a valid but `empty` policy loads and passes. @@ -996,13 +997,13 @@ Each row maps a `PolicyFetchResult.outcome` to its exit impact, severity, the me | `found` | `0` (or `1` if checks fail under `block`) | info / block | `Policy: (cached, fetched Nm ago) -- enforcement=` | None; enforcement applied. Under `block`, fix violations or use `--no-policy` for one-off bypass. | | `absent` | `0` | info (`--verbose` only) | `No org policy found for ` | None required. To publish one, see section 11. If your org keeps policy in a private `.github-private`, grant the credential `Contents: read` on it: GitHub answers 404 for a repository it cannot read. On github.com, `*.ghe.com` and the `GITHUB_HOST` host, `--verbose`, `apm policy status` and the `fetch_failure_default: block` error show this as a hint. | | `cached_stale` | `0` (enforcement still applies) | warn | `Policy: (cached, fetched Nm ago) -- enforcement=` plus refresh-error warning | Restore network reachability or run with `--no-cache` once connectivity returns. | -| `cache_miss_fetch_fail` | `0` | warn | `Could not fetch org policy () -- policy enforcement skipped for this invocation` | Retry, check VPN/firewall/`gh auth status`/`GITHUB_APM_PAT`. Fail-open by design (CEO-ratified); CI will still fail for the same violation. | -| `garbage_response` | `0` | warn | `Could not fetch org policy (invalid YAML body from ) -- policy enforcement skipped for this invocation` | Likely a captive portal or auth wall returning HTML. Restore direct connectivity, then re-run. | -| `malformed` | `0` (no enforcement) | warn | `Policy at is malformed -- contact your org admin to fix the policy file` | Contact org admin to fix the YAML. Validate locally with `apm audit --ci --policy `. | +| `cache_miss_fetch_fail` | `0` | warn | `Could not fetch org policy from (); proceeding without policy enforcement.` | Retry, check VPN/firewall/`gh auth status`/`GITHUB_APM_PAT`. Fail-open by design (CEO-ratified); CI will still fail for the same violation. | +| `garbage_response` | `0` | warn | `Policy response from is not valid YAML (); proceeding without policy enforcement.` | Likely a captive portal or auth wall returning HTML. Restore direct connectivity, then re-run. | +| `malformed` | `0` (no enforcement) | warn | `Policy at is malformed: . Contact your org admin to fix the policy file.` | Contact org admin to fix the YAML. Validate locally with `apm audit --ci --policy `. | | `manifest-parse` | `1` (always) | error | `Cannot parse apm.yml: ` | Fix the YAML syntax error in `apm.yml`. This is a local audit check (not a fetch outcome) -- malformed manifests always fail the audit unconditionally. | | `disabled` | `0` | warn | `Policy enforcement disabled by --no-policy for this invocation. This does NOT bypass apm audit --ci. CI will still fail the PR for the same policy violation.` | Single-invocation only. Drop the flag / env var to re-enable. | -| `no_git_remote` | `0` | warn | `Could not determine org from git remote; policy auto-discovery skipped` | Run inside a checkout with a GitHub remote, or set the remote with `git remote add origin `. | -| `empty` | `0` | warn | `Org policy is present but empty; no enforcement applied` | Org admin should populate the policy file (see section 11) or remove it. | +| `no_git_remote` | `0` | info (`--verbose` only) | `Could not determine org from git remote; policy auto-discovery skipped` | Run inside a checkout with a GitHub remote, or set the remote with `git remote add origin `. | +| `empty` | `0` | warn | `Org policy at is present but empty; no enforcement applied` | Org admin should populate the policy file (see section 11) or remove it. | | `hash_mismatch` | `1` (always) | error | `Policy hash mismatch: pinned hash does not match fetched policy. Update apm.yml policy.hash or contact your org admin.` | Inspect the diff between expected and actual digest in the error output. If the org legitimately rotated the policy, recompute and update `policy.hash` in `apm.yml`. Otherwise, treat as a potential supply-chain compromise and contact your org admin. | #### Violation classes diff --git a/docs/src/content/docs/enterprise/security.md b/docs/src/content/docs/enterprise/security.md index e6fb5aed4e..1ec9d33dac 100644 --- a/docs/src/content/docs/enterprise/security.md +++ b/docs/src/content/docs/enterprise/security.md @@ -320,7 +320,7 @@ On every cache hit, APM reads the cached checkout's `.git/HEAD` directly (not vi **Lockfile cleanup authority.** A committed `apm.lock.yaml` is reviewed input: `apm install`, `apm update`, `apm prune` and `apm uninstall` delete a deployed file it lists only when the file's recorded `deployed_file_hashes` entry still matches the bytes on disk. Files without a recorded hash, or with a mismatch, are kept with a warning. A lockfile row whose recorded hash matches the bytes on disk still authorizes deletion, even for a file APM never deployed, so review lockfile changes in pull requests like code. -**Marketplace entries replay their lock row.** A `{name, marketplace}` dependency names no repository in `apm.yml`; once locked, install takes its `repo_url`, `host` and `resolved_commit` from `apm.lock.yaml` without asking the catalog. A lock diff can therefore change where it comes from while `apm.yml` stays unchanged, so review those rows too. Org policy still checks the replayed source, and `apm update` resolves the catalog again. +**Marketplace entries replay their lock row.** A `{name, marketplace}` dependency names no repository in `apm.yml`; once locked, install takes its `repo_url`, `host` and `resolved_commit` from `apm.lock.yaml` without asking the catalog. A lock diff can therefore change where it comes from while `apm.yml` stays unchanged, so review those rows too. Org policy still checks the replayed source, and `apm update` resolves the catalog again. The lock row also records the marketplace's Git origin, so `apm update` fails, naming both, if the marketplace alias now points somewhere else. See the [Lock File Specification](../../reference/lockfile-spec/#drift-and-integrity) for field details. @@ -632,6 +632,7 @@ See [Azure DevOps Services AAD bearer tokens](#azure-devops-services-aad-bearer- | Version substitution | Malicious version replaces legitimate one | Lock file pins exact commit SHA; content hash detects post-download tampering | | Post-install scripts | Arbitrary code runs after install | Dependency packages cannot run install scripts; only [lifecycle scripts](../lifecycle-scripts/) from policy, user, or explicitly trusted project sources run | | Typosquatting | Similar package names on registry | Dependencies are full git URLs | +| Dependency confusion | Same name resolves from an unintended host | The same `owner/repo` from two hosts fails before download, naming both; `*.ghe.com` marketplaces refuse bare cross-repo sources | | Build-time injection | Malicious build steps execute | No build step — files are copied | | Hidden content injection | Not applicable (binary packages) | Pre-deploy scan blocks critical hidden Unicode; `apm audit` for on-demand checks | | Compromised policy intermediary | Not applicable (no policy layer) | A malicious mirror or MITM returns valid YAML with relaxed rules. Mitigated by [`policy.hash` consumer-side pin](../policy-reference/#96-hash-pin-policyhash-consumer-side-verification) which verifies raw bytes against a project-pinned digest. | @@ -647,10 +648,10 @@ For an org standardizing on APM: - Route dep traffic through an enterprise proxy with audit logging. See [Registry Proxy & Air-gapped](../registry-proxy/). - Treat insecure transport as a separate CI control. `apm-policy.yml` has no dedicated `allow_insecure` field: `dependencies.allow` and - `dependencies.deny` match scheme-blind, host-blind canonical package identities - (for example `owner/repo`, not `github.com/owner/repo`). Policy patterns cannot - restrict host identity and cannot distinguish `http://` from `https://` for the - same package path. Reject committed + `dependencies.deny` can name a host (see + [Host-qualified patterns](../policy-reference/#host-qualified-patterns)) but + match scheme-blind, so they cannot distinguish `http://` from `https://` for + the same package. Reject committed `allow_insecure: true` entries and prohibit `--allow-insecure` and `--allow-insecure-host` in standard CI; review both explicit gates for any air-gapped exception. `registry_source.allow_non_registry` is a separate diff --git a/docs/src/content/docs/producer/author-primitives/mcp-as-primitive.md b/docs/src/content/docs/producer/author-primitives/mcp-as-primitive.md index 652b9d1ec5..c9a2857b1d 100644 --- a/docs/src/content/docs/producer/author-primitives/mcp-as-primitive.md +++ b/docs/src/content/docs/producer/author-primitives/mcp-as-primitive.md @@ -50,7 +50,7 @@ either a bare string or a mapping. Fields, from | `url` | self-defined `http`/`sse`/`streamable-http` | `http://` or `https://` only. | | `env` | optional, stdio | Map of env vars passed to the child process. | | `headers` | optional, remote | Map of HTTP headers. CR/LF rejected. | -| `tools` | optional | Allowlist of tool names. Default `["*"]`. | +| `tools` | optional | Allowlist of tool names. Default `["*"]`. Claude Code ignores it in the project `.mcp.json` it shares with Copilot. | | `version` | optional | Pin a registry server version. | | `registry` | optional | `false` = self-defined; URL = custom registry. | | `package` | optional | `npm`, `pypi`, or `oci` for registry-resolved servers. | @@ -115,8 +115,8 @@ shipped. Do not embed tokens. Two patterns work: ``` Headers and env values are never shell-expanded by APM. For harnesses -that support runtime env placeholders (for example VS Code, Kiro, and -Claude Code's project `.mcp.json`), APM preserves the placeholder so the +that support runtime env placeholders (for example Copilot, Kiro, and the +project `.mcp.json` shared by Copilot and Claude Code), APM preserves the placeholder so the harness resolves it when the server starts or the request is made. For harnesses that require literal values (for example Codex user scope, or a Codex project `env` value not written as `KEY: ${KEY}`) and for Claude diff --git a/docs/src/content/docs/reference/cli/deps.md b/docs/src/content/docs/reference/cli/deps.md index 8467c4971f..aa046ef21c 100644 --- a/docs/src/content/docs/reference/cli/deps.md +++ b/docs/src/content/docs/reference/cli/deps.md @@ -151,6 +151,8 @@ apm deps update [PACKAGES...] [OPTIONS] `apm deps update` runs the install pipeline and is gated by org `apm-policy.yml`. There is no `--no-policy` flag; the only escape hatch is `APM_POLICY_DISABLE=1` for the shell session. +Like `apm update`, it refuses an `apm.lock.yaml` written by a newer APM before changing anything, naming both versions and how to upgrade; see [Lockfile written by a newer APM](../../../troubleshooting/install-failures/#lockfile-written-by-a-newer-apm). + ### `apm deps clean` Remove the entire project `apm_modules/` directory. Does not touch `apm.yml` or `apm.lock.yaml`. diff --git a/docs/src/content/docs/reference/cli/update.md b/docs/src/content/docs/reference/cli/update.md index f6060f2f95..f26ff877b9 100644 --- a/docs/src/content/docs/reference/cli/update.md +++ b/docs/src/content/docs/reference/cli/update.md @@ -109,7 +109,9 @@ apm update restoration is also denied, preserve the reported backups and follow [recovery guidance](../../../troubleshooting/install-failures/#windows-file-locks-and-incomplete-recovery) before rerunning `apm update`; the prior package may not be active. -- **Marketplace catalogs are revalidated.** Each catalog behind a `name` + `marketplace` dependency is fetched once per run instead of trusting the cached copy. If it cannot be verified, the update fails with no changes. `plugin@marketplace` selects that dependency. +- **Marketplace catalogs are revalidated.** Each catalog behind a `name` + `marketplace` dependency is fetched once per run instead of trusting the cached copy. If it cannot be verified, the update fails with no changes. `plugin@marketplace` selects that dependency. If a marketplace name now points at a different origin than `apm.lock.yaml` recorded (`source_url`), the update fails naming both origins and changes nothing. +- **Newer lockfiles are refused.** If `apm.lock.yaml` was written by a newer APM, `apm update` exits 1 before changing anything, naming both versions and how to upgrade; see [Lockfile written by a newer APM](../../../troubleshooting/install-failures/#lockfile-written-by-a-newer-apm). +- **Registry-only proxies.** Under `PROXY_REGISTRY_ONLY=1`, `apm update` re-resolves dependencies locked to direct VCS sources through the registry; a targeted update still requires the entries it keeps to be registry-routed. - **Mutable refs require upstream freshness.** APM resolves mutable Git refs through the authenticated upstream. If upstream resolution fails, the update fails instead of silently substituting a ref from the local bare Git cache. Content already cached for the freshly resolved SHA may still be reused. - **Registry deps.** Updates stay within the manifest constraint and use the configured registry. An exact `1.7.0` or `=1.7.0` pin remains **unchanged** even when `apm outdated` reports `Latest` as `1.8.0`. To take an outside-constraint release, [select it explicitly](../outdated/#registry-reporting). Unlike read-only `outdated`, `update` can write the manifest, lockfile, modules, and deployed files. - **Structured plan.** Output is grouped into four sections: diff --git a/docs/src/content/docs/reference/manifest-schema.md b/docs/src/content/docs/reference/manifest-schema.md index f8b21a83c2..e4e5ed14dc 100644 --- a/docs/src/content/docs/reference/manifest-schema.md +++ b/docs/src/content/docs/reference/manifest-schema.md @@ -73,7 +73,7 @@ lifecycle: # OPTIONAL; lifecycle scripts x-[a-z][a-z0-9-]*: # OPTIONAL vendor extensions ``` -Two fields are REQUIRED at parse time: `name` and `version`. All other fields are OPTIONAL. A top-level key MUST NOT appear twice; the CLI refuses such a manifest (for example two `dependencies:` blocks left by a merge) before changing any file, naming the key and both lines. Unknown top-level keys MUST be preserved by writers. The CLI keeps keys matching `x-[a-z][a-z0-9-]*` and warns, without failing, on any other unknown top-level key. See [Extension keys](#312-extension-keys). +Two fields are REQUIRED at parse time: `name` and `version`. All other fields are OPTIONAL. A top-level key MUST NOT appear twice; the CLI refuses such a manifest (for example two `dependencies:` blocks left by a merge) before changing any file, naming the key and both lines. YAML anchors and aliases (`&name`, `*name`) are refused the same way, naming the file and line ([req-mf-020](../../specs/openapm-v01/#req-mf-020)). Unknown top-level keys MUST be preserved by writers. The CLI keeps keys matching `x-[a-z][a-z0-9-]*` and warns, without failing, on any other unknown top-level key. See [Extension keys](#312-extension-keys). The standard `$schema` key selects the manifest contract; omission selects APM's current working draft. The corrected OpenAPM v0.1 candidate uses @@ -629,7 +629,7 @@ Remote dependency (git URL plus sub-path): `ref:` accepts either a literal git ref (`main`, `v2.0`, a 40-char commit SHA) or a **semver range** (`^1.2.0`, `~1.4`, `>=2.0 <3`, `1.5.x`). When `ref:` is a semver range, APM resolves it against the remote's tags at install time, matching against `v{version}`, `{name}--v{version}` and `{name}-v{version}` patterns (with `{version}` as a bare-tag fallback) and selecting the highest tag that satisfies the range. -The lockfile records the original `constraint`, the `resolved_tag`, the resolved `version`, the `resolved_commit`, and a `resolved_at` timestamp so subsequent installs replay the same tag deterministically -- only `apm install --update` or a manifest change re-resolves. When no remote tag satisfies the range, APM surfaces `NoMatchingTagError` with the inspected patterns. +The lockfile records the original `constraint`, the `resolved_tag`, the resolved `version`, the `resolved_commit`, and a `resolved_at` timestamp so subsequent installs replay the same tag deterministically -- only `apm update` or a manifest change re-resolves. When no remote tag satisfies the range, APM surfaces `NoMatchingTagError` with the inspected patterns. Local path dependency (development only): @@ -698,7 +698,7 @@ pattern makes `apm marketplace add` or `apm marketplace update` reject the entire marketplace, so consumers never resolve against a partially accepted catalog. -Resolution failures stop the install instead of silently skipping the dependency. The lockfile records the **resolved** coordinates and pinned commit, not the marketplace placeholder. Unresolved marketplace dependencies cannot compute install paths or serialize back to `apm.yml`. +Resolution failures stop the install instead of silently skipping the dependency. The lockfile records the **resolved** coordinates and pinned commit, not the marketplace placeholder. Later installs, including `--frozen`, replay those coordinates without contacting the marketplace while `name`, `marketplace` and `version` are unchanged; `apm update` resolves again. Unresolved marketplace dependencies cannot compute install paths or serialize back to `apm.yml`. Registry dependency (whole package or virtual sub-path): diff --git a/packages/apm-guide/.apm/skills/apm-usage/dependencies.md b/packages/apm-guide/.apm/skills/apm-usage/dependencies.md index 1d8db2a631..4c4adc02e2 100644 --- a/packages/apm-guide/.apm/skills/apm-usage/dependencies.md +++ b/packages/apm-guide/.apm/skills/apm-usage/dependencies.md @@ -388,7 +388,9 @@ Once the lockfile records an entry, `apm install` and `apm install --frozen` replay its locked commit without reading the catalog or needing the marketplace registration; catalog edits do not move it. New entries, entries whose `name`, `marketplace` or `version` changed, and `apm update` resolve -through the catalog, and `--frozen` fails for an unlocked entry. Exceptions +through the catalog, and `--frozen` fails for an unlocked entry. +`apm install --refresh`, `apm update` and `apm marketplace update` revalidate +the marketplace and fail rather than use stale cached data. Exceptions until 0.38 (#2903): registry-routed catalog entries still resolve through the catalog (the lockfile has no registry binding), and the lockfile does not record catalog-inline MCP/LSP servers, so a package with locked servers and no @@ -401,6 +403,8 @@ The `marketplace` value names a marketplace registered with list (`$APM_HOME/apm.yml`, default `~/.apm/apm.yml`, reconciled by `apm install -g`). Dependencies and project manifests cannot declare `marketplaces:`. +`apm uninstall name@marketplace` removes an object-form entry offline, with +its lock row and deployed files. For object-form declarations, `apm audit --ci` uses recorded `discovered_via` + `marketplace_plugin_name` to find one locked coordinate. @@ -638,7 +642,9 @@ lives in `docs/src/content/docs/reference/manifest-schema.md` section When your `apm.yml` and one or more parent packages declare the same dependency, APM installs it once with the sorted union of every declaration's -`skills:` and of every declaration's `targets:`. A declaration that omits the +`skills:` and of every declaration's `targets:`, but each skill deploys only to +the targets of the declaration that selected it (`subset_pairings`, see the +object-form section). A declaration that omits the field selects everything. Declaration order does not matter. `apm uninstall` of one parent narrows the union to the remaining declarations, and `apm audit --ci` checks the lockfile against that union. If the declarations @@ -973,12 +979,13 @@ enterprise security guide for the threat model. ## What the lockfile pins `apm.lock.yaml` records the exact commit SHA for every dependency, regardless -of the ref format in apm.yml. Running `apm install` without `--update` reuses +of the ref format in apm.yml. Plain `apm install` reuses the locked SHA when the dependency identity, declared ref and effective host provider match. An unseeded mutable ref resolves upstream even when another package or sibling path has a lock entry. -`apm install --update`, `apm install --refresh`, `apm update` (including -`--force`), `apm lock --update`, and `apm outdated` establish mutable refs from +`apm update` (including `--force`), `apm install --refresh`, +`apm lock --update`, `apm outdated`, and the deprecated `apm install --update` +(use `apm update`) establish mutable refs from upstream instead of using a persistent bare-cache ref as current-state evidence. `--frozen` checks declared refs, full commit pins, host providers and HTTP/HTTPS @@ -986,6 +993,9 @@ transport against the lock, including transport changes under an unchanged semver range. It does not check whether an upstream branch moved. Review an intentional declaration change and run `apm update` to refresh the lock. +APM refuses to change, replay, audit or pack a lockfile written by a newer +APM, naming both versions; upgrade APM (there is no override). + For local `.agent.md`, `.instructions.md`, and `.prompt.md` dependencies, the locked content hash covers the ordinary materialized package, including its generated manifest. `--frozen` reconstructs that image from the declared source diff --git a/packages/apm-guide/.apm/skills/apm-usage/governance.md b/packages/apm-guide/.apm/skills/apm-usage/governance.md index 0c06f2c6f0..f05697d70d 100644 --- a/packages/apm-guide/.apm/skills/apm-usage/governance.md +++ b/packages/apm-guide/.apm/skills/apm-usage/governance.md @@ -7,7 +7,8 @@ CHANGELOG when using policy features. ## Policy file location - **Org-level:** hosted in a repo, fetched via `--policy org` or `--policy URL` -- **Repo-level:** `apm-policy.yml` in the repository root +- **Repo-level:** not auto-discovered; a repo `apm-policy.yml` applies only + when passed to `apm audit --ci --policy` - **Local override:** `--policy ./path/to/apm-policy.yml` Org policy governs project installs only: discovery starts from the project's @@ -46,7 +47,7 @@ cache: ttl: 3600 # policy cache in seconds dependencies: - allow: [] # allowed patterns + allow: null # allowed patterns (null = no opinion; [] = allow nothing) deny: [] # denied patterns (takes precedence) require: [] # required packages require_resolution: project-wins # project-wins | policy-wins | block @@ -54,12 +55,12 @@ dependencies: require_pinned_constraint: false # when true, direct deps must declare a bounded ref (bans NO_REF, '*', bare branch, '>=X' without upper bound) mcp: - allow: [] # allowed server patterns + allow: null # allowed server patterns deny: [] # denied patterns transport: - allow: [] # stdio | streamable-http | sse (http = streamable-http); checks the effective transport, registry servers included + allow: null # stdio | streamable-http | sse (http = streamable-http); checks the effective transport, registry servers included self_defined: warn # deny | warn | allow - trust_transitive: false # trust MCP from transitive deps + trust_transitive: false # parsed but not enforced; consent is `apm approve` compilation: target: @@ -73,7 +74,7 @@ manifest: required_fields: [] # fields that must exist in apm.yml scripts: allow # allow | deny content_types: - allow: [] # instructions | skill | hybrid | prompts + allow: null # instructions | skill | hybrid | prompts require_explicit_includes: false # mandate explicit `includes:` list in apm.yml (rejects `auto` and undeclared) unmanaged_files: @@ -141,7 +142,7 @@ registry_source: | `allow_non_registry` | `true` | When `false`, every dep MUST be routed through a configured registry; git-shorthand and `- git:` deps are blocked at install time. | The same registry-source rule applies to `apm install`, -`apm install `, `apm deps update`, and `apm audit --ci`. +`apm install `, `apm update`, and `apm audit --ci`. ## Integrity and drift enforcement @@ -445,7 +446,8 @@ Chain limit: 5 levels max. Cycles are detected and rejected. | `*/approved` | `any-org/approved` | | `exact/match` | Only `exact/match` | -Deny is evaluated first. Empty allow list permits all (except denied). +Deny is evaluated first. A `null` allow list permits all (except denied); an +empty `[]` allow list permits nothing. Identity casing compares GitHub and registry owner/repository prefixes case-insensitively and keeps other identity boundaries case-sensitive. See [Identity casing](https://microsoft.github.io/apm/reference/policy-schema/#identity-casing) for recursive-glob behavior, upgrade risk, and workaround removal. @@ -459,7 +461,7 @@ These checks run without a policy file: - `deployed-files-present` -- all deployed files exist - `no-orphaned-packages` -- no packages in lockfile absent from manifest - `skill-subset-consistency` -- selected skill subsets match the lockfile -- `config-consistency` -- MCP configs match lockfile +- `config-consistency` -- MCP configs match lockfile; servers the executables gate left out pass, and a server the lock admits but `apm.yml` does not approve fails - `content-integrity` -- no critical Unicode in deployed files, and no SHA-256 drift between on-disk content and the hash recorded at install time (line endings are normalized, so CRLF/LF platform differences never false-positive) - `includes-consent` -- advisory notice when local content lacks an explicit `includes:` declaration @@ -474,10 +476,12 @@ modify the manifest, lockfile, or deployment. Additional checks when a policy is provided: -- **Dependencies:** allowlist, denylist, required packages, transitive depth +- **Dependencies:** allowlist, denylist, required packages (present, deployed, + version, executables trusted), transitive depth, pinned constraints, registry source +- **Integrity:** dependency content hashes - **MCP:** allowlist, denylist, transport, self-defined servers - **Compilation:** target, strategy, source attribution -- **Manifest:** required fields, scripts policy +- **Manifest:** required fields, explicit includes, scripts policy - **Unmanaged:** unmanaged file detection ## CLI usage @@ -530,7 +534,7 @@ token read access to every ancestor `apm-policy`. Configure a self-managed host with `GITLAB_HOST` or `APM_GITLAB_HOSTS`, and use `APM_GITLAB_POLICY_REPO` to select another project name. Repositories with no detectable git remote (unpacked -bundles, temp dirs) emit an explicit "could not determine org" line and skip +bundles, temp dirs) print a "could not determine org" line with `--verbose` and skip discovery. The `--policy ` flag is **audit-only today** -- it works on @@ -550,11 +554,16 @@ relax an ancestor that requires an explicit `includes:` list. ### 4. What gets enforced -- **Dependencies:** allow, deny, require (presence + optional version pin), max_depth -- **MCP:** allow, deny, transport.allow, self_defined, trust_transitive +- **Dependencies:** allow, deny, require (presence + optional version pin), max_depth, require_pinned_constraint +- **Registry source:** require, allow_non_registry +- **MCP:** allow, deny, transport.allow, self_defined (`trust_transitive` is parsed but not enforced) - **Compilation:** target.allow / target.enforce (target-aware). `target:`, `targets:`, and CSV forms are one declaration; aliases resolve before comparison (`vscode`/`agents` are `copilot`); `all` in `allow` allows everything. Install judges its effective selection; audit judges the targets `apm.yml` declares. -- **Manifest:** required_fields, scripts, content_types.allow -- **Unmanaged files:** action against configured directories +- **Manifest:** require_explicit_includes +- **Integrity:** security.integrity.require_hashes + +`manifest.required_fields`, `manifest.scripts`, `compilation.strategy`, +`compilation.source_attribution` and `unmanaged_files` are checked only by +`apm audit --ci`; `manifest.content_types` is not enforced. ### 5. When enforcement runs @@ -563,7 +572,7 @@ relax an ancestor that requires an explicit `includes:` list. | `apm install` | NEW -- gate runs after resolve, before integration / target writes | | `apm install ` | NEW -- snapshot apm.yml, run gate, rollback on block | | `apm install --mcp` | NEW -- dedicated MCP preflight | -| `apm deps update` | NEW -- runs the install pipeline, so the same gate applies | +| `apm update` | NEW -- runs the install pipeline, so the same gate applies | | `apm install --dry-run` | NEW -- read-only preflight; renders "would be blocked" | | `apm audit --ci` | Existing -- same checks against on-disk manifest + lockfile | @@ -588,7 +597,7 @@ Successful install (verbose) under `enforcement: block`: ```shell $ apm install --verbose [i] Resolving dependencies... -[i] Policy: org:contoso/.github (cached, fetched 12m ago) -- enforcement=block +[!] Policy: org:contoso/.github (cached, fetched 12m ago) -- enforcement=block [+] Installed 4 APM dependencies, 2 MCP servers in 1.2s ``` @@ -600,7 +609,7 @@ $ apm install [!] Policy: org:contoso/.github -- enforcement=block [x] Policy violation: github.com/acme/evil-pkg -- denied by pattern: acme/evil-pkg Blocked by org policy at org:contoso/.github (dependency-denylist) -- remove `github.com/acme/evil-pkg` from apm.yml, contact admin to update policy, or use `--no-policy` for one-off bypass -[x] Install aborted: 1 policy check failed +[x] Install blocked by org policy -- see violations above ``` Warn: same dep, `enforcement: warn` -- install succeeds, violation flows to summary: @@ -628,9 +637,9 @@ $ apm install --no-policy ```shell $ apm install --dry-run [i] Resolving dependencies... -[i] Policy: org:contoso/.github -- enforcement=block -[!] Would be blocked by policy: acme/evil-pkg -- denylist match: acme/evil-pkg -[!] Would be blocked by policy: acme/banned -- denylist match: acme/banned +[!] Policy: org:contoso/.github -- enforcement=block +[!] Would be blocked by policy: github.com/acme/evil-pkg -- denied by pattern: acme/* +[!] Would be blocked by policy: github.com/acme/banned -- denied by pattern: acme/* [!] ... and 4 more would be blocked by policy. Run `apm audit` for full report. [i] Dry-run: no files written ``` @@ -644,7 +653,7 @@ $ apm install acme/evil-pkg [x] Policy violation: github.com/acme/evil-pkg -- denied by pattern: acme/evil-pkg Blocked by org policy at org:contoso/.github (dependency-denylist) -- remove `github.com/acme/evil-pkg` from apm.yml, contact admin to update policy, or use `--no-policy` for one-off bypass [i] apm.yml restored to its previous state. -[x] Install aborted: 1 policy check failed +[x] Install blocked by org policy -- see violations above ``` One violation line per offending dependency or MCP server; the hint names what to change in apm.yml (for a transitive MCP server, the dependency that brings it in) and cites the check in parentheses. @@ -656,7 +665,7 @@ $ apm install [i] Resolving dependencies... [!] Policy: org:contoso/.github -- enforcement=block [+] Installed 4 APM dependencies in 0.8s -[x] Transitive MCP server(s) blocked by org policy. APM packages remain installed; MCP configs were NOT written. +[x] MCP server(s) blocked by org policy. APM packages remain installed; MCP configs were NOT written. ``` ### 8. Escape hatches @@ -667,7 +676,7 @@ fail the PR for the same policy violation. | Hatch | Scope | |-------|-------| -| `--no-policy` | On `apm install`, `apm install `, `apm install `, `apm install --mcp`. Skips install-time discovery + enforcement for one invocation; loud warning. Not on `apm deps update`. | +| `--no-policy` | On `apm install`, `apm install `, `apm install `, `apm install --mcp`. Skips install-time discovery + enforcement for one invocation; loud warning. Not on `apm update`; use `APM_POLICY_DISABLE=1` there. | | `APM_POLICY_DISABLE=1` | Env var equivalent. Same loud warning. | `APM_POLICY` is reserved for a future override env var and is **not** @@ -679,7 +688,8 @@ Resolved effective policy is cached under the platform user cache at `apm/policy_v1//`. Default TTL comes from the policy's `cache.ttl` (`3600` seconds). Beyond TTL, APM serves the stale cache on refresh failure with a loud warning, up to a hard ceiling -of 7 days (`MAX_STALE_TTL`). `--no-cache` forces a fresh fetch. Writes are +of 7 days (`MAX_STALE_TTL`). `--no-cache` on `apm audit` and `apm policy status` +forces a fresh fetch. Writes are atomic (temp file + rename). ### 9.5. Network failure semantics @@ -691,9 +701,9 @@ atomic (temp file + rename). - **Garbage response** (HTTP 200 with non-YAML body, e.g. captive portal): same posture as fetch failure -- warn loudly, cache fallback if present. - **No policy resolved (`no_git_remote` / `absent` / `empty`):** since - #1159, these emit a `[!]` warning to stderr and honour - `policy.fetch_failure_default: block` for parity with fetch failures. - Pre-fix they were silently fail-open even with `block` set. + #1159, these honour `policy.fetch_failure_default: block` for parity with + fetch failures. `apm audit --ci` warns on all three; `apm install` warns + on `empty` and shows `absent` / `no_git_remote` only with `--verbose`. Opt in to fail-closed semantics with the `policy.fetch_failure: warn|block` knob on `apm-policy.yml` (applies when a cached policy is available) or @@ -738,8 +748,8 @@ emit a `[!]` warning to stderr by default and exit 1 with `[x]` when the project sets `policy.fetch_failure_default: block` -- pre-fix they silently exited 0, leaving CI green with no enforcement applied. JSON and SARIF output on stdout stays clean (all diagnostics on stderr). -Explicit `--policy ` keeps the legacy fall-through (no warning) -so opt-in pointers at minimal baseline files do not regress. +`--policy org` keeps the legacy fall-through (no warning); any other +explicit `--policy` that yields no policy fails closed (see CLI usage). ### 10. Errors and exit codes @@ -767,10 +777,10 @@ Violation classes: | `denylist` | `dependencies.deny` match | Remove dep from `apm.yml`, request org-policy update, or `--no-policy` for one-off bypass | | `allowlist` | Dep not in non-empty `dependencies.allow` | Add to org allowlist or switch to an approved package | | `required` | Missing `dependencies.require` entry, or version-pin mismatch | Add the dep (and pin) to `apm.yml`. Pin mismatches downgrade to warn under `require_resolution: project-wins`; missing required deps still block | -| `pinned-constraint` | `dependencies.require_pinned_constraint: true` + a direct dep with no ref, a wildcard, a bare branch, or a bare `>=X.Y` | Pin the dep to an exact version (`1.2.3` or npm/cargo-style `=1.2.3`; pip-style `==1.2.3` is not supported), caret/tilde/bounded semver range, literal tag (`vX.Y.Z`, or `{name}-vX.Y.Z` / `{name}--vX.Y.Z` for the dep's own package name), an exact package release tag (`name@X.Y.Z` / `@scope/name@X.Y.Z`), or a full SHA. The check judges declared release intent, not immutability (a tag can move; `apm install --frozen` replays the locked commit). The constraint is judged as declared in `apm.yml` (a `replace:` rule by the ref it selects), not the tag a range resolved to. Roll out enforcement with `warn` before `block`. | +| `pinned-constraint` | `dependencies.require_pinned_constraint: true` + a direct dep with no ref, a wildcard, a bare branch, or a bare `>=X.Y` | Pin the dep to an exact version (`1.2.3` or npm/cargo-style `=1.2.3`; pip-style `==1.2.3` is not supported), caret/tilde/bounded semver range, literal tag (`vX.Y.Z`, or `{name}-vX.Y.Z` / `{name}--vX.Y.Z` for the dep's own package name), an exact package release tag (`name@X.Y.Z` / `@scope/name@X.Y.Z`), or a full SHA. Leading zeros or non-ASCII digits (`v01.2.3`) are not SemVer and fail as bare branches. The check judges declared release intent, not immutability (a tag can move; `apm install --frozen` replays the locked commit). The constraint is judged as declared in `apm.yml` (a `replace:` rule by the ref it selects), not the tag a range resolved to. Roll out enforcement with `warn` before `block`. | | `transport` | Effective MCP transport (the registry remote, package = stdio, or a self-defined server's declared transport) not in `mcp.transport.allow`, or the registry cannot resolve the server | Switch transport, pick one with `transport:` in apm.yml when the server offers several, check registry reachability, or request `mcp.transport.allow` update | | `target` | Resolved target not in `compilation.target.allow` (or violates `target.enforce`) | Re-run with `--target `, or adjust `targets:` in `apm.yml` | -| `transitive_mcp` | MCP server pulled in by a transitive dep, blocked by `mcp.deny` / `transport` / `self_defined` | Remove offending dep, request policy update, or set `mcp.trust_transitive: true` | +| `transitive_mcp` | MCP server pulled in by a transitive dep, blocked by `mcp.deny` / `transport` / `self_defined` | Remove the dep that brings it in, or request a policy update. `--trust-transitive-mcp` does not bypass policy, and `mcp.trust_transitive` is parsed but not enforced | Full message text per outcome and per class lives in `docs/src/content/docs/enterprise/policy-reference.md` section10. Violation messages From 15d003aae9850787621267307b20a2f2b43befb3 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Thu, 19 Nov 2026 20:30:54 +0100 Subject: [PATCH 2/6] docs(security): scope dependency-confusion and rebound claims to code The new threat-model row credited #3895 with general dependency-confusion protection, but it only catches one install graph declaring the same owner/repo from two hosts; bare shorthand still resolves to the default host. The rebound sentence also omitted lock rows without a recorded origin, local marketplaces and in-repo moves, which the check skips. Addresses supply-chain-security-expert panel findings and Copilot inline on docs/src/content/docs/enterprise/security.md:323. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/content/docs/enterprise/security.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/enterprise/security.md b/docs/src/content/docs/enterprise/security.md index 1ec9d33dac..76ea598707 100644 --- a/docs/src/content/docs/enterprise/security.md +++ b/docs/src/content/docs/enterprise/security.md @@ -320,7 +320,7 @@ On every cache hit, APM reads the cached checkout's `.git/HEAD` directly (not vi **Lockfile cleanup authority.** A committed `apm.lock.yaml` is reviewed input: `apm install`, `apm update`, `apm prune` and `apm uninstall` delete a deployed file it lists only when the file's recorded `deployed_file_hashes` entry still matches the bytes on disk. Files without a recorded hash, or with a mismatch, are kept with a warning. A lockfile row whose recorded hash matches the bytes on disk still authorizes deletion, even for a file APM never deployed, so review lockfile changes in pull requests like code. -**Marketplace entries replay their lock row.** A `{name, marketplace}` dependency names no repository in `apm.yml`; once locked, install takes its `repo_url`, `host` and `resolved_commit` from `apm.lock.yaml` without asking the catalog. A lock diff can therefore change where it comes from while `apm.yml` stays unchanged, so review those rows too. Org policy still checks the replayed source, and `apm update` resolves the catalog again. The lock row also records the marketplace's Git origin, so `apm update` fails, naming both, if the marketplace alias now points somewhere else. +**Marketplace entries replay their lock row.** A `{name, marketplace}` dependency names no repository in `apm.yml`; once locked, install takes its `repo_url`, `host` and `resolved_commit` from `apm.lock.yaml` without asking the catalog. A lock diff can therefore change where it comes from while `apm.yml` stays unchanged, so review those rows too. Org policy still checks the replayed source, and `apm update` resolves the catalog again. The lock row also records the marketplace's origin (its repository or `marketplace.json` URL), so `apm update` fails, naming both, if the alias now points at a different origin. Rows written before origins were recorded, local marketplaces, and a move to another path in the same repository are not checked. See the [Lock File Specification](../../reference/lockfile-spec/#drift-and-integrity) for field details. @@ -632,7 +632,7 @@ See [Azure DevOps Services AAD bearer tokens](#azure-devops-services-aad-bearer- | Version substitution | Malicious version replaces legitimate one | Lock file pins exact commit SHA; content hash detects post-download tampering | | Post-install scripts | Arbitrary code runs after install | Dependency packages cannot run install scripts; only [lifecycle scripts](../lifecycle-scripts/) from policy, user, or explicitly trusted project sources run | | Typosquatting | Similar package names on registry | Dependencies are full git URLs | -| Dependency confusion | Same name resolves from an unintended host | The same `owner/repo` from two hosts fails before download, naming both; `*.ghe.com` marketplaces refuse bare cross-repo sources | +| Dependency confusion | Bare `owner/repo` resolves on an unintended host | Bare shorthand always uses the default host (`default_host`, else `GITHUB_HOST`, else `github.com`); write `host/owner/repo` for other hosts and use [host-qualified](../policy-reference/#host-qualified-patterns) allow patterns. The same `owner/repo` from two hosts in one install fails before download, naming both; `*.ghe.com` marketplaces refuse bare cross-repo sources | | Build-time injection | Malicious build steps execute | No build step — files are copied | | Hidden content injection | Not applicable (binary packages) | Pre-deploy scan blocks critical hidden Unicode; `apm audit` for on-demand checks | | Compromised policy intermediary | Not applicable (no policy layer) | A malicious mirror or MITM returns valid YAML with relaxed rules. Mitigated by [`policy.hash` consumer-side pin](../policy-reference/#96-hash-pin-policyhash-consumer-side-verification) which verifies raw bytes against a project-pinned digest. | From 4fc029536065c0a4de46664ebe1018618d3e132e Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Thu, 19 Nov 2026 20:30:54 +0100 Subject: [PATCH 3/6] docs(policy): fix skill CLI samples and allow-list wording The apm-usage governance CLI samples used header and footer lines the CLI never prints and a dry-run overflow that cannot follow two lines (the preview limit is 5); align them with policy-reference. Section 3 still described a repo override in the discovered chain, and the allowlist rows said 'non-empty', contradicting null vs [] semantics. Addresses doc-writer and supply-chain-security-expert panel findings. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/enterprise/policy-reference.md | 4 +- .../.apm/skills/apm-usage/governance.md | 38 ++++++++++--------- 2 files changed, 23 insertions(+), 19 deletions(-) diff --git a/docs/src/content/docs/enterprise/policy-reference.md b/docs/src/content/docs/enterprise/policy-reference.md index 2a551c84f3..39818df017 100644 --- a/docs/src/content/docs/enterprise/policy-reference.md +++ b/docs/src/content/docs/enterprise/policy-reference.md @@ -132,7 +132,7 @@ Controls which packages repositories can depend on. ### `allow` -List of allowed dependency patterns. If non-empty, only matching dependencies are permitted. +List of allowed dependency patterns. If set (not `null`), only matching dependencies are permitted; `[]` permits none. ```yaml dependencies: @@ -1015,7 +1015,7 @@ Install prints one `Policy violation: -- ` line per offending | Class | Origin | Primary message | Remediation | |-------|--------|-----------------|-------------| | `denylist` | `dependencies.deny` match | `Policy violation: -- denied by pattern: ` | Remove the dep from `apm.yml`, request an org-policy update, or `--no-policy` for one-off local debugging. | -| `allowlist` | Dep not in non-empty `dependencies.allow` | `Policy violation: -- not in allowed sources` | Add the dep to the org allowlist or switch to an approved package. | +| `allowlist` | Dep not in a set `dependencies.allow` (`[]` allows nothing) | `Policy violation: -- not in allowed sources` | Add the dep to the org allowlist or switch to an approved package. | | `required` | Missing `dependencies.require` entry, or pin mismatch | `Policy violation: -- required by org policy but not declared` (pin mismatch: `Policy violation: -- expected ref '', got ''`) | Add the required dep to `apm.yml` (and pin the required version). Pin mismatches downgrade to warn under `require_resolution: project-wins`; missing required deps still block. | | `transport` | MCP transport not in `mcp.transport.allow` | `Policy violation: -- transport '' not in allowed []` (or ` -- effective transport unknown (); ...`) | Switch the server to an allowed transport, pick one with `transport:` in `apm.yml` when the server offers several, make sure the MCP registry is reachable, or request `mcp.transport.allow` updates. | | `target` | Resolved target not in `compilation.target.allow` (or violates `target.enforce`) | `Policy violation: compilation-target -- Target(s) [''] not in allowed list ['']: ...` (or `Enforced target '' not present in [...]: ...`) | Re-run with `--target `, or update `targets:` in `apm.yml`. Evaluated post-`targets` phase, so CLI overrides are honoured. | diff --git a/packages/apm-guide/.apm/skills/apm-usage/governance.md b/packages/apm-guide/.apm/skills/apm-usage/governance.md index f05697d70d..86abec4714 100644 --- a/packages/apm-guide/.apm/skills/apm-usage/governance.md +++ b/packages/apm-guide/.apm/skills/apm-usage/governance.md @@ -542,7 +542,9 @@ The `--policy ` flag is **audit-only today** -- it works on ### 3. Inheritance and composition -Policy resolves through the chain: enterprise hub -> org -> repo override. +Policy resolves through the chain: enterprise hub -> org. A repo `apm-policy.yml` +is not part of the discovered chain; it applies only when passed to +`apm audit --ci --policy`. The merge follows "Inheritance rules" above (tighten-only; a child cannot remove inherited entries). **Multi-level extends:** install-time enforcement and `apm audit --ci` both @@ -590,22 +592,22 @@ relax an ancestor that requires an explicit `includes:` list. ### 7. CLI examples -Symbol legend: `[+]` success, `[!]` warning, `[x]` error, `[i]` info. +Symbol legend: `[>]` progress, `[+]` success, `[!]` warning, `[x]` error, `[i]` info, `[*]` summary. Successful install (verbose) under `enforcement: block`: ```shell $ apm install --verbose -[i] Resolving dependencies... +[>] Installing dependencies from apm.yml... [!] Policy: org:contoso/.github (cached, fetched 12m ago) -- enforcement=block -[+] Installed 4 APM dependencies, 2 MCP servers in 1.2s +[*] Installed 4 APM dependencies, 2 MCP servers in 1.2s. ``` Block: denied dependency aborts the install before integration: ```shell $ apm install -[i] Resolving dependencies... +[>] Installing dependencies from apm.yml... [!] Policy: org:contoso/.github -- enforcement=block [x] Policy violation: github.com/acme/evil-pkg -- denied by pattern: acme/evil-pkg Blocked by org policy at org:contoso/.github (dependency-denylist) -- remove `github.com/acme/evil-pkg` from apm.yml, contact admin to update policy, or use `--no-policy` for one-off bypass @@ -616,39 +618,42 @@ Warn: same dep, `enforcement: warn` -- install succeeds, violation flows to summ ```shell $ apm install -[i] Resolving dependencies... -[+] Installed 4 APM dependencies, 2 MCP servers in 1.2s - +[>] Installing dependencies from apm.yml... [!] 1 policy warning +- [dependency-denylist] 1 dependency(ies) match deny list: acme/evil-pkg: denied by pattern: acme/evil-pkg +[*] Installed 4 APM dependencies, 2 MCP servers in 1.2s. ``` Escape hatches (`--no-policy` flag and `APM_POLICY_DISABLE=1` env var) emit the same loud warning every invocation: ```shell $ apm install --no-policy +[>] Installing dependencies from apm.yml... [!] Policy enforcement disabled by --no-policy for this invocation. This does NOT bypass apm audit --ci. CI will still fail the PR for the same policy violation. -[i] Resolving dependencies... -[+] Installed 4 APM dependencies, 2 MCP servers in 1.2s +[*] Installed 4 APM dependencies, 2 MCP servers in 1.2s. ``` `--dry-run` previews violations (capped at five per severity bucket; overflow collapses): ```shell $ apm install --dry-run -[i] Resolving dependencies... +[>] Installing dependencies from apm.yml... [!] Policy: org:contoso/.github -- enforcement=block [!] Would be blocked by policy: github.com/acme/evil-pkg -- denied by pattern: acme/* [!] Would be blocked by policy: github.com/acme/banned -- denied by pattern: acme/* -[!] ... and 4 more would be blocked by policy. Run `apm audit` for full report. -[i] Dry-run: no files written +[!] Would be blocked by policy: github.com/acme/old -- denied by pattern: acme/* +[!] Would be blocked by policy: github.com/acme/legacy -- denied by pattern: acme/* +[!] Would be blocked by policy: github.com/acme/tools -- denied by pattern: acme/* +[!] ... and 2 more would be blocked by policy. Run `apm audit` for full report. +[i] Dry run mode - showing what would change: ``` `apm install ` blocked -- manifest restored: ```shell $ apm install acme/evil-pkg -[i] Resolving dependencies... +[*] Updated apm.yml with 1 new package(s) +[>] Installing 1 new package... [!] Policy: org:contoso/.github -- enforcement=block [x] Policy violation: github.com/acme/evil-pkg -- denied by pattern: acme/evil-pkg Blocked by org policy at org:contoso/.github (dependency-denylist) -- remove `github.com/acme/evil-pkg` from apm.yml, contact admin to update policy, or use `--no-policy` for one-off bypass @@ -662,9 +667,8 @@ Transitive MCP server blocked -- APM packages stay installed, MCP configs are no ```shell $ apm install -[i] Resolving dependencies... +[>] Installing dependencies from apm.yml... [!] Policy: org:contoso/.github -- enforcement=block -[+] Installed 4 APM dependencies in 0.8s [x] MCP server(s) blocked by org policy. APM packages remain installed; MCP configs were NOT written. ``` @@ -775,7 +779,7 @@ Violation classes: | Class | Triggers | Remediation | |-------|----------|-------------| | `denylist` | `dependencies.deny` match | Remove dep from `apm.yml`, request org-policy update, or `--no-policy` for one-off bypass | -| `allowlist` | Dep not in non-empty `dependencies.allow` | Add to org allowlist or switch to an approved package | +| `allowlist` | Dep not in a set `dependencies.allow` (`[]` allows nothing) | Add to org allowlist or switch to an approved package | | `required` | Missing `dependencies.require` entry, or version-pin mismatch | Add the dep (and pin) to `apm.yml`. Pin mismatches downgrade to warn under `require_resolution: project-wins`; missing required deps still block | | `pinned-constraint` | `dependencies.require_pinned_constraint: true` + a direct dep with no ref, a wildcard, a bare branch, or a bare `>=X.Y` | Pin the dep to an exact version (`1.2.3` or npm/cargo-style `=1.2.3`; pip-style `==1.2.3` is not supported), caret/tilde/bounded semver range, literal tag (`vX.Y.Z`, or `{name}-vX.Y.Z` / `{name}--vX.Y.Z` for the dep's own package name), an exact package release tag (`name@X.Y.Z` / `@scope/name@X.Y.Z`), or a full SHA. Leading zeros or non-ASCII digits (`v01.2.3`) are not SemVer and fail as bare branches. The check judges declared release intent, not immutability (a tag can move; `apm install --frozen` replays the locked commit). The constraint is judged as declared in `apm.yml` (a `replace:` rule by the ref it selects), not the tag a range resolved to. Roll out enforcement with `warn` before `block`. | | `transport` | Effective MCP transport (the registry remote, package = stdio, or a self-defined server's declared transport) not in `mcp.transport.allow`, or the registry cannot resolve the server | Switch transport, pick one with `transport:` in apm.yml when the server offers several, check registry reachability, or request `mcp.transport.allow` update | From 0dd1ac2601af7421c3fa59e432d32e9c1233af19 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Thu, 19 Nov 2026 20:30:55 +0100 Subject: [PATCH 4/6] docs(install): qualify marketplace replay and default_host wording Locked marketplace entries replay offline except for a package whose locked MCP or LSP servers have no apm_modules copy; that case reads the marketplace even under --frozen (drift.py catalog-metadata). Also tie default_host to the shorthand rather than #ref and link the newer lockfile troubleshooting section. Addresses Copilot inline on reference/manifest-schema.md:701 and doc-writer panel nit on consumer/install-packages.md:64. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/content/docs/consumer/install-packages.md | 12 +++++++----- docs/src/content/docs/reference/manifest-schema.md | 2 +- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/src/content/docs/consumer/install-packages.md b/docs/src/content/docs/consumer/install-packages.md index 7b3dbfea2a..0b09d27339 100644 --- a/docs/src/content/docs/consumer/install-packages.md +++ b/docs/src/content/docs/consumer/install-packages.md @@ -60,9 +60,9 @@ devDependencies: apm install ``` -Supported reference forms: `owner/repo` shorthand (with optional -`#ref` for a tag, branch, or commit; resolved against `default_host:` when -`apm.yml` sets one), full HTTPS or SSH git URLs, +Supported reference forms: `owner/repo` shorthand (on the manifest's +[`default_host`](../../reference/manifest-schema/#315-default_host) when set, +with optional `#ref` for a tag, branch, or commit), full HTTPS or SSH git URLs, virtual subdirectory paths into a monorepo, single-file references, and local paths starting with `./`, `../`, or `/`. For private hosts and tokens, see [Authentication](../authentication/). @@ -179,7 +179,8 @@ same bytes. Commit the lockfile. :::note[Lockfile replay] Plain `apm install` and `apm install --frozen` replay locked commits for unchanged dependencies, including transitive packages and marketplace entries -(without contacting the marketplace), and reuse matching +(without contacting the marketplace, except for a package whose locked MCP or +LSP servers have no `apm_modules/` copy), and reuse matching [cached package content](../../reference/cli/cache/) when available. This keeps mutable branches and tags pinned to their recorded commits. @@ -285,7 +286,8 @@ and the full flag reference, or run `apm install --help`. `apm audit --ci` locally to reproduce the CI gate; see [Update and refresh](../update-and-refresh/) to recover. - **Lockfile written by a newer APM.** APM refuses to change or replay it, - naming both versions. Upgrade APM; there is no override. + naming both versions. Upgrade APM; there is no override. See + [Lockfile written by a newer APM](../../troubleshooting/install-failures/#lockfile-written-by-a-newer-apm). - **Skipped symlinked agent source.** `apm install` warns and skips agent files or directories that are symlinks (for example `.apm/agents -> ../agents`). Fix by shipping real files and directories in diff --git a/docs/src/content/docs/reference/manifest-schema.md b/docs/src/content/docs/reference/manifest-schema.md index e4e5ed14dc..6dce8ffd1e 100644 --- a/docs/src/content/docs/reference/manifest-schema.md +++ b/docs/src/content/docs/reference/manifest-schema.md @@ -698,7 +698,7 @@ pattern makes `apm marketplace add` or `apm marketplace update` reject the entire marketplace, so consumers never resolve against a partially accepted catalog. -Resolution failures stop the install instead of silently skipping the dependency. The lockfile records the **resolved** coordinates and pinned commit, not the marketplace placeholder. Later installs, including `--frozen`, replay those coordinates without contacting the marketplace while `name`, `marketplace` and `version` are unchanged; `apm update` resolves again. Unresolved marketplace dependencies cannot compute install paths or serialize back to `apm.yml`. +Resolution failures stop the install instead of silently skipping the dependency. The lockfile records the **resolved** coordinates and pinned commit, not the marketplace placeholder. Later installs, including `--frozen`, replay those coordinates without contacting the marketplace while `name`, `marketplace` and `version` are unchanged; `apm update` resolves again. The exception is a package whose MCP or LSP servers the lock records but which has no `apm_modules/` copy: install reads the marketplace for it, because only the marketplace holds those inline server definitions. Unresolved marketplace dependencies cannot compute install paths or serialize back to `apm.yml`. Registry dependency (whole package or virtual sub-path): From f4854f33573a383c41989977c2d2adc4ed35d120 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Thu, 19 Nov 2026 20:41:02 +0100 Subject: [PATCH 5/6] test(docs): track host-qualified policy wording in security.md security.md no longer says policy patterns are host-blind or cannot restrict host identity: dependencies.allow/deny accept host-qualified patterns (policy-reference). The docs-contract test still pinned the old wording and failed Build & Test Shard 1. Keep its intent (no transport-aware policy claim) and assert the scheme-blind sentence and the host-qualified link instead. Addresses CI failure in tests/unit/test_tls_docs_scope.py:127. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- tests/unit/test_tls_docs_scope.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/unit/test_tls_docs_scope.py b/tests/unit/test_tls_docs_scope.py index c35624ffc2..1f3e01005f 100644 --- a/tests/unit/test_tls_docs_scope.py +++ b/tests/unit/test_tls_docs_scope.py @@ -124,10 +124,10 @@ def test_enterprise_security_docs_do_not_claim_transport_aware_policy(): normalized = " ".join(security.replace("**", "").split()) assert "no dedicated `allow_insecure` field" in normalized - assert "scheme-blind, host-blind canonical package identities" in normalized - assert "owner/repo`, not `github.com/owner/repo" in normalized + assert "match scheme-blind, so they cannot distinguish `http://` from `https://`" in normalized + assert "(../policy-reference/#host-qualified-patterns)" in normalized assert "non-default hosts are retained" not in normalized - assert "cannot restrict host identity" in normalized + assert "cannot restrict host identity" not in normalized assert "does not enforce HTTPS" in normalized assert "`registry_source.allow_non_registry`" in normalized assert "Forbid `allow_insecure: true` via the policy allow list" not in normalized From 43a76be2da590e4cc96f730a581e6fc90e8bfbc1 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Thu, 19 Nov 2026 20:52:11 +0100 Subject: [PATCH 6/6] docs(security): name the manifest whose default_host applies Each parsed manifest, transitive ones included, resolves its own bare owner/repo dependencies against its own default_host, so a root default_host does not pin the whole graph. Say so in the dependency-confusion row and point at host-qualified allow patterns as the control. Addresses supply-chain-security-expert delta panel finding on docs/src/content/docs/enterprise/security.md:635. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/content/docs/enterprise/security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/enterprise/security.md b/docs/src/content/docs/enterprise/security.md index 76ea598707..62aa5ac54d 100644 --- a/docs/src/content/docs/enterprise/security.md +++ b/docs/src/content/docs/enterprise/security.md @@ -632,7 +632,7 @@ See [Azure DevOps Services AAD bearer tokens](#azure-devops-services-aad-bearer- | Version substitution | Malicious version replaces legitimate one | Lock file pins exact commit SHA; content hash detects post-download tampering | | Post-install scripts | Arbitrary code runs after install | Dependency packages cannot run install scripts; only [lifecycle scripts](../lifecycle-scripts/) from policy, user, or explicitly trusted project sources run | | Typosquatting | Similar package names on registry | Dependencies are full git URLs | -| Dependency confusion | Bare `owner/repo` resolves on an unintended host | Bare shorthand always uses the default host (`default_host`, else `GITHUB_HOST`, else `github.com`); write `host/owner/repo` for other hosts and use [host-qualified](../policy-reference/#host-qualified-patterns) allow patterns. The same `owner/repo` from two hosts in one install fails before download, naming both; `*.ghe.com` marketplaces refuse bare cross-repo sources | +| Dependency confusion | Bare `owner/repo` resolves on an unintended host | Bare shorthand uses the declaring manifest's default host (its `default_host`, else `GITHUB_HOST`, else `github.com`), so a dependency's `apm.yml` decides where its own bare deps resolve; write `host/owner/repo` for other hosts and enforce hosts with [host-qualified](../policy-reference/#host-qualified-patterns) allow patterns. The same `owner/repo` from two hosts in one install fails before download, naming both; `*.ghe.com` marketplaces refuse bare cross-repo sources | | Build-time injection | Malicious build steps execute | No build step — files are copied | | Hidden content injection | Not applicable (binary packages) | Pre-deploy scan blocks critical hidden Unicode; `apm audit` for on-demand checks | | Compromised policy intermediary | Not applicable (no policy layer) | A malicious mirror or MITM returns valid YAML with relaxed rules. Mitigated by [`policy.hash` consumer-side pin](../policy-reference/#96-hash-pin-policyhash-consumer-side-verification) which verifies raw bytes against a project-pinned digest. |