diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 4baac602..6736f4c4 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -69,6 +69,7 @@ export default defineConfig({ { label: 'Pack & Distribute', slug: 'guides/pack-distribute' }, { label: 'Private Packages', slug: 'guides/private-packages' }, { label: 'Org-Wide Packages', slug: 'guides/org-packages' }, + { label: 'CI Policy Enforcement', slug: 'guides/ci-policy-setup' }, { label: 'Agent Workflows (Experimental)', slug: 'guides/agent-workflows' }, ], }, @@ -77,6 +78,7 @@ export default defineConfig({ items: [ { label: 'APM for Teams', slug: 'enterprise/teams' }, { label: 'Governance & Compliance', slug: 'enterprise/governance' }, + { label: 'Policy Reference', slug: 'enterprise/policy-reference' }, { label: 'Security Model', slug: 'enterprise/security' }, { label: 'Adoption Playbook', slug: 'enterprise/adoption-playbook' }, { label: 'Making the Case', slug: 'enterprise/making-the-case' }, diff --git a/docs/src/content/docs/enterprise/policy-reference.md b/docs/src/content/docs/enterprise/policy-reference.md index 0ce4e641..3c5b13c5 100644 --- a/docs/src/content/docs/enterprise/policy-reference.md +++ b/docs/src/content/docs/enterprise/policy-reference.md @@ -499,3 +499,9 @@ dependencies: - "contoso/agent-standards" max_depth: 5 # Tightens from 10 to 5 ``` + +## Related + +- [Governance & Compliance](../../enterprise/governance/) -- conceptual overview of APM's governance model +- [CI Policy Enforcement](../../guides/ci-policy-setup/) -- step-by-step CI setup tutorial +- [GitHub Rulesets](../../integrations/github-rulesets/) -- enforce policy as a required status check diff --git a/docs/src/content/docs/guides/agent-workflows.md b/docs/src/content/docs/guides/agent-workflows.md index 08ee8b01..3fec72d9 100644 --- a/docs/src/content/docs/guides/agent-workflows.md +++ b/docs/src/content/docs/guides/agent-workflows.md @@ -2,7 +2,7 @@ title: "Agent Workflows (Experimental)" description: "Run agentic workflows locally using APM scripts and AI runtimes." sidebar: - order: 8 + order: 9 --- :::caution[Experimental Feature] diff --git a/docs/src/content/docs/guides/ci-policy-setup.md b/docs/src/content/docs/guides/ci-policy-setup.md index b7abe0ff..361f7f65 100644 --- a/docs/src/content/docs/guides/ci-policy-setup.md +++ b/docs/src/content/docs/guides/ci-policy-setup.md @@ -1,7 +1,7 @@ --- title: CI Policy Enforcement sidebar: - order: 5 + order: 8 --- :::caution[Experimental Feature] @@ -212,3 +212,9 @@ apm-policy: | SARIF | `-f sarif` | GitHub Code Scanning, VS Code | Combine with `-o ` to write to a file. + +## Related + +- [Governance & Compliance](../../enterprise/governance/) -- conceptual overview of APM's governance model +- [Policy Reference](../../enterprise/policy-reference/) -- full `apm-policy.yml` schema reference +- [GitHub Rulesets](../../integrations/github-rulesets/) -- enforce policy as a required status check diff --git a/docs/src/content/docs/integrations/github-rulesets.md b/docs/src/content/docs/integrations/github-rulesets.md index 5fc8a71a..5374b416 100644 --- a/docs/src/content/docs/integrations/github-rulesets.md +++ b/docs/src/content/docs/integrations/github-rulesets.md @@ -58,36 +58,53 @@ Once configured, any PR that introduces content issues detected by `apm audit` w ## What It Catches -`apm audit` detects the following content issues: +`apm audit` operates in three modes, each adding more checks: -- **Hidden Unicode characters** — tag characters, bidi overrides, and variation selectors embedded in prompt files. -- **Zero-width and invisible characters** — characters that could alter agent behavior without visible changes. +**Content scanning** (`apm audit`): +- **Critical: Hidden Unicode characters** -- tag characters (U+E0001-E007F), bidi overrides (U+202A-202E, U+2066-2069), and SMP variation selectors. Exit code **1**. +- **Warning: Zero-width and invisible characters** -- zero-width spaces/joiners, mid-file BOM, soft hyphens. Exit code **2**. These are suspicious but not attack vectors. -When issues are detected, the command exits with a non-zero status code (1 = critical, 2 = warnings) and the check fails. +**CI baseline checks** (`apm audit --ci`) -- adds lockfile verification on top of content scanning: +- **Lockfile exists** -- validates `apm.lock.yaml` is present when dependencies are declared +- **Ref consistency** -- every dependency's manifest ref matches the lockfile +- **Deployed files present** -- all files listed in lockfile exist on disk +- **No orphaned packages** -- no packages in lockfile are absent from manifest +- **Config consistency** -- MCP server configs match lockfile baseline +- **Content integrity** -- fails on **critical** Unicode only (warnings are not CI-blocking) -## Governance Levels +In `--ci` mode, exit codes are binary: **0** = pass, **1** = fail. Warning-level characters do not fail CI. + +**Policy enforcement** (`apm audit --ci --policy org`) -- adds organizational rules: +- **Approved/denied sources** -- restrict which repositories packages can come from +- **MCP transport controls** -- allow/deny transport types, trust settings for transitive MCP +- **Manifest requirements** -- enforce required fields, content types, scripts +- **Compilation rules** -- target and strategy constraints +- **Unmanaged file detection** -- flag files in integration directories not tracked by the lockfile -APM's integration with GitHub governance is evolving: +For full setup instructions, see the [CI Policy Enforcement](../../guides/ci-policy-setup/) guide. For the complete policy schema, see the [Policy Reference](../../enterprise/policy-reference/). + +## Governance Levels | Level | Description | Status | |-------|-------------|--------| -| 1 | `apm audit` as a required status check (content scanning via exit codes) | Available now | -| 1+ | `apm audit --ci` with lockfile consistency checking | Planned | -| 2 | GitHub recommends apm-action for agent governance | Future | -| 3 | Native Rulesets UI for agent configuration policy | Future | +| 1 | `apm audit` as a required status check (content scanning: critical=exit 1, warning=exit 2) | Available | +| 2 | `apm audit --ci` with lockfile verification (binary pass/fail, warnings do not block) | Available | +| 3 | `apm audit --ci --policy org` with organization policy enforcement | Available | +| 4 | GitHub recommends apm-action for agent governance | Future | +| 5 | Native Rulesets UI for agent configuration policy | Future | -Level 1 is fully functional today using `apm audit` exit codes. Level 1+ (lockfile consistency) and Levels 2–3 represent deeper integration that would reduce setup friction. +Levels 1-3 are fully functional today. See the [CI Policy Enforcement](../../guides/ci-policy-setup/) guide for step-by-step setup. Levels 4-5 represent deeper GitHub platform integration that would reduce setup friction. ## Combining with Other Checks -APM audit complements your existing CI checks — it does not replace them. A typical PR pipeline might include: +APM audit complements your existing CI checks -- it does not replace them. A typical PR pipeline might include: -- **Linting and formatting** — code style enforcement -- **Unit and integration tests** — functional correctness -- **Security scanning** — vulnerability detection -- **APM audit** — hidden Unicode scanning with CI reporting +- **Linting and formatting** -- code style enforcement +- **Unit and integration tests** -- functional correctness +- **Security scanning** -- vulnerability detection +- **APM audit** -- content scanning, lockfile verification, and policy enforcement -Each check has a distinct purpose. APM audit focuses on detecting hidden Unicode characters that could embed invisible instructions in prompt files. +Each check has a distinct purpose. APM audit focuses on AI agent configuration integrity -- from hidden Unicode detection to organizational policy compliance. ## Customizing the Workflow @@ -150,5 +167,8 @@ The status check name must match the **job name** in your workflow file (e.g., ` ## Related -- [CI/CD Pipelines](../ci-cd/) — full CI integration guide -- [Manifest Schema](../../reference/manifest-schema/) — manifest and lock file reference +- [CI Policy Enforcement](../../guides/ci-policy-setup/) -- step-by-step CI setup for policy enforcement +- [Governance & Compliance](../../enterprise/governance/) -- conceptual overview of APM's governance model +- [Policy Reference](../../enterprise/policy-reference/) -- full `apm-policy.yml` schema reference +- [CI/CD Pipelines](../ci-cd/) -- general CI integration guide +- [Manifest Schema](../../reference/manifest-schema/) -- manifest and lock file reference