APM 企业治理完整指南用apm-policy.yml控制全组织的AI智能体来源与权限【免费下载链接】apmAgent Package Manager项目地址: https://gitcode.com/gh_mirrors/apm10/apmAPMAgent Package Manager是一个开源的 AI 智能体依赖管理器类似package.json之于前端、requirements.txt之于 Python。而apm-policy.yml正是 APM 的企业治理核心一个 YAML 文件就能让安全团队统一声明哪些智能体依赖、MCP 服务器、编译目标是全组织唯一被允许的之后每一次apm install都会自动执行它。本指南带你从零部署组织级 APM 策略掌握权限管控、三级继承与 CI 强制门禁。为什么 AI 智能体需要企业级治理AI 编码智能体Copilot、Claude Code、Cursor、Codex、Gemini 等的上下文本质上就是可执行程序——一段提示词会直接影响模型的行为。如果组织内每个仓库都能随意安装来源不明的技能包Skills、插件或 MCP 服务器就等于给供应链攻击敞开了大门。APM 的治理理念是三个关键词可移植一个apm.yml清单描述所有智能体配置一条命令在任何机器复现默认安全安装时扫描隐藏 Unicode 攻击、锁文件固定内容哈希️策略治理apm-policy.yml决定组织允许安装什么在文件落盘之前就拦截违规 简单理解清单apm.yml回答我要什么策略apm-policy.yml回答组织允许什么。两者叠加才是完整的企业治理。5 分钟快速上手部署你的第一个 apm-policy.ymlAPM 自带了一份起步模板 apm-policy-starter.yml专为 1~10 个仓库的小型组织设计。完整上手只需 4 步第 1 步放置到组织策略仓库APM 会自动从项目 git 远程推断组织并按优先级查找策略文件.github-private→.github→.apm→_apmGitLab 使用顶级分组下的apm-policy项目。推荐优先使用.github-private因为策略通常包含内部治理规则不宜公开。第 2 步从 warn 模式开始先用只警告、不阻断的模式观察一段时间避免第一天就打断开发者的工作流name: Acme baseline policy version: 1.0.0 enforcement: warn # warn | block | off dependencies: deny: - untrusted-org/** # 先拦截一个不信任的包家族第 3 步预览策略再提交提交前可以先对任意策略源做干跑测试确认规则按预期生效apm audit --ci --policy ./apm-policy.yml第 4 步翻牌到 block 模式观察期结束、告警清零后把enforcement改为block违规的安装和 CI 审计将直接失败。这就是 APM 官方推荐的先告警、后阻断渐进式推广路径Rollout Playbook。核心机制allowlist、denylist 与 require 三件套策略文件的核心是三个列表语义清晰且相互独立配置项含义典型用法dependencies.allow白名单只允许匹配的依赖来源contoso/**表示只允许本组织所有仓库dependencies.deny黑名单优先于白名单命中即拒绝untrusted-org/**、*/deprecated-*dependencies.require必选包每个仓库都必须声明contoso/agent-standards可带版本 pin⚠️一个关键语义白名单为null表示不表态放行所有未被 deny 的来源白名单为空列表[]表示什么都不允许。写策略时千万不要混淆这两者。模式匹配遵循通配符规则contoso/*只匹配一级路径contoso/**匹配任意深度。deny 永远先于 allow 求值——命中任何 deny 模式即失败与白名单无关。三级继承只能收紧不能放松Tighten-only大型组织通常希望企业 → 部门 → 仓库层层约束。APM 用extends字段实现最多 5 层的策略继承链例如Enterprise hub企业基线 → Org policy部门策略 → Repo override仓库覆盖继承遵循只收紧、不放松的合并规则用大白话说allow 列表取交集子策略只能进一步收窄父策略的允许范围deny 列表取并集子策略可以在父策略基础上追加黑名单max_depth 取最小值依赖深度约束只会更严enforcement 只升不降offwarnblock子策略可以把 warn 升级为 block但反过来不行trust_transitive 取 AND父子双方都允许才信任传递性 MCP 服务器这套机制保证了一件重要的事任何仓库都不可能绕过组织的底线约束只能在其上变得更严格。循环引用A extends B 且 B extends A会被自动检测并拒绝。两个强制检查点安装门禁 CI 门禁策略在两个时点被评估使用同一份策略文件与同一套合并语义1️⃣ 安装时门禁apm installapm install会先解析依赖、再执行策略预检、最后才写文件。一旦触发block级违规安装会在任何文件落盘之前中止退出码非零[x] Policy violation: acme/evil-pkg -- Blocked by org policy [x] Install aborted: 1 policy check failed这意味着恶意包根本进不了门智能体永远不会读到它。2️⃣ CI 时门禁apm audit --ci --policy org开发者本地可以用--no-policy或环境变量绕过检查但 CI 绕不过。把apm audit --ci --policy org配置为 PR 的必过检查后它会执行21 项策略检查 8 项基线锁文件检查包括依赖类白/黑名单、必选包、依赖深度、版本 pin 约束完整性内容哈希比对防止文件被篡改MCP 类服务器名白/黑名单、传输协议限制stdio/sse/http/streamable-http编译类目标运行时限制、策略、来源标注清单类apm.yml必备字段、scripts 节管控未托管文件治理目录下出现未被 APM 追踪的手动文件时告警审计支持 SARIF 输出可以直接接入代码扫描平台违规行会内联标注在 PR diff 上——违规 PR 在策略被正式修订前无法合并。完整的 CI 接入配方含最小化 workflow 示例见 enforce-in-ci.md配套模板 policy-ci-workflow.yml 可直接参考。常用策略字段速查表不必一次记住所有字段下面是最常用的配置项区块关键字段作用dependenciesallow/deny/require依赖来源白/黑名单与必选包max_depth限制传递依赖深度默认 50设为 3 即直接两层传递require_pinned_constraint禁止无上限的版本范围要求固定 tag 或 SHAmcptransport.allow只允许指定 MCP 传输协议self_defined管控仓库内联定义的 MCP 服务器allow/warn/denycompilation.targetallow/enforce限制可编译的智能体运行时copilot、claude、cursor、codex 等manifestrequired_fields/scripts强制apm.yml必备字段、禁止 scripts 节unmanaged_filesaction/directories检测治理目录下的野文件ignore/warn/denysecurity.integrityrequire_hashes要求所有非本地依赖必须带内容哈希 注意策略只管安装时门禁。它不扫描代码语义、不是杀毒软件也不管运行时权限——运行时由你的智能体运行框架harness负责。两个平面互不重叠各司其职。完整字段参考见 policy-reference.md策略文件的完整心智模型见 apm-policy.md。常见问题 FAQQ1策略放哪里才能被自动发现组织级策略放在.github-private推荐或.github仓库根目录GitLab 放在顶级分组下的apm-policy项目。apm install和apm audit --ci都会根据项目 git 远程自动发现默认缓存 1 小时。Q2开发者本地能绕过策略吗能。apm install --no-policy可跳过单次本地门禁。所以必须把apm audit --ci --policy org配成 CI 必过检查——本地绕得掉CI 绕不掉这就是纵深防御。Q3策略文件本身如何防止被篡改建议策略仓库启用 CODEOWNERS把策略文件划归安全团队评审配合分支保护规则GitHub Rulesets任何策略变更都必须走组织的变更管理流程。Q4策略拉取失败会怎样由fetch_failure字段控制默认warn响亮警告后继续安装可设为block实现拉不到策略就拒绝安装的 fail-closed 姿态。参考资源起步模板apm-policy-starter.yml策略文件详解docs/src/content/docs/enterprise/apm-policy.md完整策略字段参考docs/src/content/docs/enterprise/policy-reference.mdCI 强制接入指南docs/src/content/docs/enterprise/enforce-in-ci.md策略引擎源码发现、继承、检查src/apm_cli/policy/安装脚本install.sh、install.ps1✅ 总结一个apm-policy.yml三道防线——安装时拦截、CI 审计、只收紧的继承链。先用warn观察再翻牌block你的组织就拥有了对 AI 智能体来源与权限的完整治理能力。【免费下载链接】apmAgent Package Manager项目地址: https://gitcode.com/gh_mirrors/apm10/apm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考