尧图网页设计 
gh-aw安全架构完整梳理7层纵深防御如何守护AI代理工作流【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-awgh-awGitHub Agentic Workflows将自然语言编写的 Markdown 工作流编译成受安全管控的 GitHub Actions 工作流。它的安全架构采用 7 层纵深防御设计从编译期校验、输入净化、输出隔离到网络隔离、权限最小化、沙箱隔离和威胁检测每一层都由 specs/security-architecture-spec.md 形式化定义并配有持续运行的合规测试。本文将带你从代码与 ADR 的角度完整梳理这套纵深防御设计。为什么AI代理需要一套专门的安全架构传统 CI 流水线执行的是开发者写好的脚本而 gh-aw 让 AI 代理Copilot、Claude 等在 GitHub 上自动干活——它会读取 issue、PR 评论这些不可信内容再执行写操作。这就引入了三类新威胁威胁类型攻击方式对应防御层模板注入恶意输入操纵${{ }}表达式输入净化层提示注入在 issue 里藏指令操纵 AI威胁检测层数据外泄诱导 AI 把数据发到外部站点网络隔离层权限提升让代理获得写仓库的权限输出隔离 权限层供应链攻击依赖的 Action 被篡改编译期 SHA 固定gh-aw 的应对思路是读与写分离AI 代理永远只读所有写操作必须经过验证后的safe_outputs作业完成。编译期校验第一道防线Layer 0gh-aw compile在生成.lock.yml之前就会做四件事任何一项失败都会拒绝编译fail-secure 原则Schema 校验frontmatter 字段逐一对照 JSON Schema未知字段直接报错表达式安全分析prompt:里出现的${{ github.event.issue.title }}等不可信表达式会被编译器自动改写为净化后的steps.sanitized.outputs.text原始上下文永远到不了生成文件权限校验strict 模式下禁止给 agent 作业任何 write 权限并建议使用safe-outputsAction 固定Pinning生成的uses:必须锁定到 40 位 commit SHAv6、main这类可变引用会被 CI 工具actionlint、poutine、zizmor拒绝。 关键原则SG-07安全校验失败时编译器不产出任何工件——宁可编译失败也不降级运行。输入净化层给AI喂什么先洗一遍所有来自 issue 标题、PR 评论、提交信息的内容在进入 AI 提示词前必须经过固定顺序的净化管道要求 IS-01 ~ IS-11原始输入净化后防御目标octocatoctocat防止通知滥用fixes #123fixes #123防止 bot 触发scriptalert(1)/scriptlt;scriptgt;...防 XSS / 注入https://evil.example.com(redacted)防钓鱼链接\x1b[31m红色文本红色文本防终端注入净化规则还包括内容上限 0.5 MB / 65536 行超限截断、剥离javascript:、data:等危险协议、删除控制字符且非白名单域名一律脱敏。输出隔离层AI永远只读写操作走安检口gh-aw 把编译后的工作流拆成职责单一的作业链见 specs/security-architecture-spec.md 附录 A 的作业依赖图pre_activation → activation → agent → detection → safe_outputs 角色检查 输入净化 只读 威胁扫描 验证后写入作业权限职责pre_activationcontents: read校验触发者是否具备 admin/maintainer 角色activationcontents: read时间戳校验 输入净化agentcontents: readAI 执行零写权限detection无权限扫描 agent 产出safe_outputs按需授予 write验证 agent 输出 JSON 后才执行写操作写操作只允许使用预定义的安全出口类型create-issue、add-comment、create-pull-request、close-issue等且 token 必须来自${{ secrets.* }}表达式——明文 token 会直接编译失败。下图就是经过这道安检口后AI 产出的 issue 分诊评论网络隔离层默认只开白名单域名AI 代理和 MCP 服务器的出站网络受network配置约束支持三种模式network: defaults—— 仅基础基础设施证书、Ubuntu 源等network: { allowed: [...] }—— 自定义域名白名单支持子域与通配符匹配network: {}—— 完全断网。白名单里还可以直接使用生态标识github、pythonPyPI、nodenpm、go、rust、containersDocker Hub/GHCR等它们会自动展开为对应的域名列表blocked列表则拥有最高优先级。强制手段包括 AWF 进程级防火墙iptables、MCP 容器的 Squid 代理出口过滤以及代理式过滤。权限管理与strict模式最小权限是默认值权限层的默认值是只读PM-01未声明的权限默认为none。开启strict: true后编译器会额外强制拦截一切 write 权限contents: write等要求改用safe-outputs拒绝网络通配符*强制 Action 固定到 commit SHA拒绝已废弃的 frontmatter 字段。此外还有针对 fork 仓库的保护pull_request触发时会注入仓库 ID 比对条件防止 fork 仓库借事件上下文搭便车执行工作流。沙箱隔离层AI代理关进AWF容器AI 代理默认运行在AWFAgent Workflow Firewall沙箱中要求 SI-01 ~ SI-10文件系统chroot 透明化——用户路径$HOME、工作区、/tmp可读写系统路径只读Docker socket 完全隐藏网络iptables 出口白名单独立于 chroot 的第二道隔离权限回收容器启动后丢弃CAP_NET_ADMIN、CAP_SYS_CHROOT等能力MCP 服务器独立容器、非 root 用户、降权运行、镜像固定到 digest 并做漏洞扫描与 SBOM 追踪。值得一提的是 docs/adr/38325-require-operator-justification-for-disabling-agent-sandbox.md关闭沙箱必须提供至少 20 字符的书面理由布尔值和动态表达式一律被编译期拒绝——因为移除信任边界这件事必须留下可审计的人工意图记录。威胁检测层写出前最后一道AI安检只要配置了safe-outputs编译器就会自动生成detection作业在 agent 产出后、写入前执行三类检测要求 TD-01 ~ TD-15提示注入agent 是否被输入中的隐藏指令操纵密钥泄露API key、token、密码是否出现在产出里恶意补丁代码变更是否引入后门或漏洞。检测结果为结构化 JSON任一字段为true工作流立即失败safe_outputs不会执行。检测还支持自定义步骤如 TruffleHog 静态扫描与自定义提示词。下图是 gh-aw 自己的CI 故障医生工作流自动产出的根因分析正是这类检测与输出能力的体现从ADR看安全决策的演进每个洞都有据可查gh-aw 仓库的 docs/adr/ 目录记录了上百条架构决策记录安全类 ADR 尤其值得新手学习如何把一次修复变成可追溯的决策ADR解决的问题决策要点44590 形式化验证7 条安全保证只是文字承诺回归了没人知道用 TLA/F*/Z3 建模 SG-01~07并 1:1 落地为 Go 单测50259 SSRF 与密钥脱敏嵌套 import 可让编译器向任意主机发认证请求解析器侧强制 GitHub 主机白名单敏感 env 输出前脱敏48318 密钥传输加固密钥出现在进程参数里include可路径穿越密钥改走 stdin 传递写入前校验路径边界形式化验证ADR-44590是其中的亮点specs/security-architecture-spec-summary.md 给出了每条保证的状态机不变量例如 SG-07fail-secure被编码为危险权限 ⟹ 编译输出为空且 emitAllowedfalse。这 24 个不变量一一对应 pkg/workflow/security_architecture_sg_formal_test.go 中的 Go 测试——调用的是生产代码本身没有 mock——所以任何一次安全保证的退化都会立刻让 CI 挂掉。可审计性安全动作都留下痕迹规范SG-06要求所有安全相关动作必须产生可见工件工作流日志、自动评论、PR。下图是 gh-aw 的每日仓库报告工作流自动创建的 issue它本身就是一次安全输出的产物编译出的.lock.yml也可以人工审查规范附录 G 提供了一份Lock 文件校验清单Action 是否 SHA 固定、agent 是否零写权限、detection 作业是否存在、并发控制是否正确等附录 H 则给出 6 条Dont / Do最佳实践。合规等级三档可选的防护强度gh-aw 借鉴 W3C 规范风格把安全能力分成三档合规等级方便不同场景选用等级包含能力适用场景基础Level 1输入净化 输出隔离 权限管理 编译期检查低风险工作流标准Level 2基础 网络隔离 沙箱 运行时强制生产环境推荐完整Level 3标准 威胁检测 全部推荐项高风险、敏感数据场景每一档都配有自动化合规测试T-IS/T-OI/T-NI/T-PM/T-SI/T-TD/T-CS/T-RS 共 70 用例测试结果会明确给出达到的合规等级和失败的诊断信息。新手上手建议如果你想在自己的仓库体验这套安全架构建议按这个顺序配置开启 strict 模式strict: true让编译器替你把关写权限与 Action 固定用safe-outputs声明写操作例如create-issue、add-comment而不是直接给 agent 写权限收敛网络白名单从network: defaults起步按生态python、node逐步放行启用威胁检测可附加prompt聚焦你自己最关心的风险点如 SQL 注入限制触发角色用roles: [admin, maintainer]收紧pre_activation的成员校验。小结gh-aw 的安全架构可以用一句话概括把AI 能做什么编译成可审查、可验证、可审计的确定性约束。7 层防御中编译期校验负责事前拦截沙箱与网络隔离负责事中圈禁威胁检测与输出验证负责事后把关而形式化测试与 ADR 记录则保证这套承诺不会随代码演进而悄悄漂移。对于想在自己 CI/CD 中复制类似模型的平台工程师specs/security-architecture-spec.md 本身就是一份可逐条对标的实施清单。【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-aw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gh-aw安全架构完整梳理：7层纵深防御如何守护AI代理工作流
gh-aw安全架构完整梳理7层纵深防御如何守护AI代理工作流【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-awgh-awGitHub Agentic Workflows将自然语言编写的 Markdown 工作流编译成受安全管控的 GitHub Actions 工作流。它的安全架构采用 7 层纵深防御设计从编译期校验、输入净化、输出隔离到网络隔离、权限最小化、沙箱隔离和威胁检测每一层都由 specs/security-architecture-spec.md 形式化定义并配有持续运行的合规测试。本文将带你从代码与 ADR 的角度完整梳理这套纵深防御设计。为什么AI代理需要一套专门的安全架构传统 CI 流水线执行的是开发者写好的脚本而 gh-aw 让 AI 代理Copilot、Claude 等在 GitHub 上自动干活——它会读取 issue、PR 评论这些不可信内容再执行写操作。这就引入了三类新威胁威胁类型攻击方式对应防御层模板注入恶意输入操纵${{ }}表达式输入净化层提示注入在 issue 里藏指令操纵 AI威胁检测层数据外泄诱导 AI 把数据发到外部站点网络隔离层权限提升让代理获得写仓库的权限输出隔离 权限层供应链攻击依赖的 Action 被篡改编译期 SHA 固定gh-aw 的应对思路是读与写分离AI 代理永远只读所有写操作必须经过验证后的safe_outputs作业完成。编译期校验第一道防线Layer 0gh-aw compile在生成.lock.yml之前就会做四件事任何一项失败都会拒绝编译fail-secure 原则Schema 校验frontmatter 字段逐一对照 JSON Schema未知字段直接报错表达式安全分析prompt:里出现的${{ github.event.issue.title }}等不可信表达式会被编译器自动改写为净化后的steps.sanitized.outputs.text原始上下文永远到不了生成文件权限校验strict 模式下禁止给 agent 作业任何 write 权限并建议使用safe-outputsAction 固定Pinning生成的uses:必须锁定到 40 位 commit SHAv6、main这类可变引用会被 CI 工具actionlint、poutine、zizmor拒绝。 关键原则SG-07安全校验失败时编译器不产出任何工件——宁可编译失败也不降级运行。输入净化层给AI喂什么先洗一遍所有来自 issue 标题、PR 评论、提交信息的内容在进入 AI 提示词前必须经过固定顺序的净化管道要求 IS-01 ~ IS-11原始输入净化后防御目标octocatoctocat防止通知滥用fixes #123fixes #123防止 bot 触发scriptalert(1)/scriptlt;scriptgt;...防 XSS / 注入https://evil.example.com(redacted)防钓鱼链接\x1b[31m红色文本红色文本防终端注入净化规则还包括内容上限 0.5 MB / 65536 行超限截断、剥离javascript:、data:等危险协议、删除控制字符且非白名单域名一律脱敏。输出隔离层AI永远只读写操作走安检口gh-aw 把编译后的工作流拆成职责单一的作业链见 specs/security-architecture-spec.md 附录 A 的作业依赖图pre_activation → activation → agent → detection → safe_outputs 角色检查 输入净化 只读 威胁扫描 验证后写入作业权限职责pre_activationcontents: read校验触发者是否具备 admin/maintainer 角色activationcontents: read时间戳校验 输入净化agentcontents: readAI 执行零写权限detection无权限扫描 agent 产出safe_outputs按需授予 write验证 agent 输出 JSON 后才执行写操作写操作只允许使用预定义的安全出口类型create-issue、add-comment、create-pull-request、close-issue等且 token 必须来自${{ secrets.* }}表达式——明文 token 会直接编译失败。下图就是经过这道安检口后AI 产出的 issue 分诊评论网络隔离层默认只开白名单域名AI 代理和 MCP 服务器的出站网络受network配置约束支持三种模式network: defaults—— 仅基础基础设施证书、Ubuntu 源等network: { allowed: [...] }—— 自定义域名白名单支持子域与通配符匹配network: {}—— 完全断网。白名单里还可以直接使用生态标识github、pythonPyPI、nodenpm、go、rust、containersDocker Hub/GHCR等它们会自动展开为对应的域名列表blocked列表则拥有最高优先级。强制手段包括 AWF 进程级防火墙iptables、MCP 容器的 Squid 代理出口过滤以及代理式过滤。权限管理与strict模式最小权限是默认值权限层的默认值是只读PM-01未声明的权限默认为none。开启strict: true后编译器会额外强制拦截一切 write 权限contents: write等要求改用safe-outputs拒绝网络通配符*强制 Action 固定到 commit SHA拒绝已废弃的 frontmatter 字段。此外还有针对 fork 仓库的保护pull_request触发时会注入仓库 ID 比对条件防止 fork 仓库借事件上下文搭便车执行工作流。沙箱隔离层AI代理关进AWF容器AI 代理默认运行在AWFAgent Workflow Firewall沙箱中要求 SI-01 ~ SI-10文件系统chroot 透明化——用户路径$HOME、工作区、/tmp可读写系统路径只读Docker socket 完全隐藏网络iptables 出口白名单独立于 chroot 的第二道隔离权限回收容器启动后丢弃CAP_NET_ADMIN、CAP_SYS_CHROOT等能力MCP 服务器独立容器、非 root 用户、降权运行、镜像固定到 digest 并做漏洞扫描与 SBOM 追踪。值得一提的是 docs/adr/38325-require-operator-justification-for-disabling-agent-sandbox.md关闭沙箱必须提供至少 20 字符的书面理由布尔值和动态表达式一律被编译期拒绝——因为移除信任边界这件事必须留下可审计的人工意图记录。威胁检测层写出前最后一道AI安检只要配置了safe-outputs编译器就会自动生成detection作业在 agent 产出后、写入前执行三类检测要求 TD-01 ~ TD-15提示注入agent 是否被输入中的隐藏指令操纵密钥泄露API key、token、密码是否出现在产出里恶意补丁代码变更是否引入后门或漏洞。检测结果为结构化 JSON任一字段为true工作流立即失败safe_outputs不会执行。检测还支持自定义步骤如 TruffleHog 静态扫描与自定义提示词。下图是 gh-aw 自己的CI 故障医生工作流自动产出的根因分析正是这类检测与输出能力的体现从ADR看安全决策的演进每个洞都有据可查gh-aw 仓库的 docs/adr/ 目录记录了上百条架构决策记录安全类 ADR 尤其值得新手学习如何把一次修复变成可追溯的决策ADR解决的问题决策要点44590 形式化验证7 条安全保证只是文字承诺回归了没人知道用 TLA/F*/Z3 建模 SG-01~07并 1:1 落地为 Go 单测50259 SSRF 与密钥脱敏嵌套 import 可让编译器向任意主机发认证请求解析器侧强制 GitHub 主机白名单敏感 env 输出前脱敏48318 密钥传输加固密钥出现在进程参数里include可路径穿越密钥改走 stdin 传递写入前校验路径边界形式化验证ADR-44590是其中的亮点specs/security-architecture-spec-summary.md 给出了每条保证的状态机不变量例如 SG-07fail-secure被编码为危险权限 ⟹ 编译输出为空且 emitAllowedfalse。这 24 个不变量一一对应 pkg/workflow/security_architecture_sg_formal_test.go 中的 Go 测试——调用的是生产代码本身没有 mock——所以任何一次安全保证的退化都会立刻让 CI 挂掉。可审计性安全动作都留下痕迹规范SG-06要求所有安全相关动作必须产生可见工件工作流日志、自动评论、PR。下图是 gh-aw 的每日仓库报告工作流自动创建的 issue它本身就是一次安全输出的产物编译出的.lock.yml也可以人工审查规范附录 G 提供了一份Lock 文件校验清单Action 是否 SHA 固定、agent 是否零写权限、detection 作业是否存在、并发控制是否正确等附录 H 则给出 6 条Dont / Do最佳实践。合规等级三档可选的防护强度gh-aw 借鉴 W3C 规范风格把安全能力分成三档合规等级方便不同场景选用等级包含能力适用场景基础Level 1输入净化 输出隔离 权限管理 编译期检查低风险工作流标准Level 2基础 网络隔离 沙箱 运行时强制生产环境推荐完整Level 3标准 威胁检测 全部推荐项高风险、敏感数据场景每一档都配有自动化合规测试T-IS/T-OI/T-NI/T-PM/T-SI/T-TD/T-CS/T-RS 共 70 用例测试结果会明确给出达到的合规等级和失败的诊断信息。新手上手建议如果你想在自己的仓库体验这套安全架构建议按这个顺序配置开启 strict 模式strict: true让编译器替你把关写权限与 Action 固定用safe-outputs声明写操作例如create-issue、add-comment而不是直接给 agent 写权限收敛网络白名单从network: defaults起步按生态python、node逐步放行启用威胁检测可附加prompt聚焦你自己最关心的风险点如 SQL 注入限制触发角色用roles: [admin, maintainer]收紧pre_activation的成员校验。小结gh-aw 的安全架构可以用一句话概括把AI 能做什么编译成可审查、可验证、可审计的确定性约束。7 层防御中编译期校验负责事前拦截沙箱与网络隔离负责事中圈禁威胁检测与输出验证负责事后把关而形式化测试与 ADR 记录则保证这套承诺不会随代码演进而悄悄漂移。对于想在自己 CI/CD 中复制类似模型的平台工程师specs/security-architecture-spec.md 本身就是一份可逐条对标的实施清单。【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-aw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考