SAST供应链安全CI/CD【免费下载链接】zizmorStatic analysis for GitHub Actions (and more)项目地址https://gitcode.com/gh_mirrors/zi/zizmor点击查看免费下载本文以 zizmor 仓库的 crates/README.md 为骨架逐一梳理其 Rust 工作区中 10 个 crate 的定位、实现细节与相互依赖关系。zizmor 是一个面向 GitHub Actions及 Dependabot、pre-commit 配置的静态分析工具它把“解析 YAML / 解析表达式 / 建模 / 审计 / 输出报告”拆解成多个可独立发布的小型 crate。读完本文你将掌握整个仓库的模块边界、每个 crate 的入口文件与关键实现以及如何基于这些 crate 二次开发自己的安全分析工具。一、工作区总览一个 workspace十个 crate仓库根目录的 Cargo.toml 定义了名为zizmor的 Cargo workspace采用resolver 2共包含 10 个成员[workspace] resolver 2 members [ crates/github-actions-expressions, crates/github-actions-models, crates/pre-commit-models, crates/subfeature, crates/tree-sitter-iter, crates/yamlpatch, crates/yamlpath, crates/zizmor, crates/zizmor-dev, crates/zizmor-sarif, ]工作区还统一了所有 crate 的版本号version 1.30.1、Rust 版本要求rust-version 1.97.0、edition2024与许可证MIT。其中 crates/zizmor 是核心可执行程序其余 crate 大多作为其依赖存在例如 crates/zizmor/Cargo.toml 的[dependencies]中直接引用了github-actions-expressions、github-actions-models、pre-commit-models、subfeature、yamlpatch、yamlpath、zizmor-sarif等内部 crate并外挂了tree-sitter、tree-sitter-bash、tree-sitter-powershell、tree-sitter-yaml、regex、clap、tokio、tower-lsp-server等依赖。crates/README.md 给出的 crate 索引表如下链接已转换为仓库根目录相对路径Crate说明zizmorzizmorCLI 与核心审计功能zizmor-dev供zizmor测试与基准测试使用的共享辅助工具subfeatureSubfeature 处理 APIyamlpath保留格式的 YAML 特性feature提取yamlpatch保留注释与格式的 YAML 补丁操作github-actions-modelsGitHub Actions 工作流、action 及相关组件的非官方高质量数据模型github-actions-expressionsGitHub Actions 表达式的解析器与库tree-sitter-iter用于 tree-sitter CST 的极简前序遍历迭代器zizmor-sarif供zizmor使用的极简 SARIF 2.1.0 数据模型pre-commit-modelspre-commit 的非官方高质量数据模型整体架构按职责可以划分为五层CLI 与审计引擎层zizmor、YAML 解析层yamlpath / yamlpatch / subfeature、语法树迭代层tree-sitter-iter 及 tree-sitter 各语法、领域建模层github-actions-models / github-actions-expressions / pre-commit-models、输出层zizmor-sarif / zizmor 内置的多格式输出。二、核心层zizmor——CLI 与审计引擎crates/zizmor 是整个项目的“大脑”其src目录结构清晰反映了职责划分CLI 入口cli.rs 基于clap定义命令行参数main.rs 负责程序启动与参数分发审计规则audit/ 目录下按规则粒度拆分了 50 个审计模块例如unpinned_uses未固定版本引用、excessive_permissions权限过大、template_injection模板注入、cache_poisoning缓存投毒、dangerous_triggers危险触发器、unpinned_images未固定镜像等每个规则对应一个独立的.rs文件便于单独阅读与测试领域模型桥接models.rs 与 models/ 负责把 YAML 文档映射为可审计的数据结构输出格式output/ 支持plain人类可读文本、githubGitHub 注解、json/v1、sarif以及fix自动修复建议等多种报告形式注册表与在线能力registry.rs、github.rs 承担 Action 注册表查询、GitHub 远程数据获取等任务LSP 支持lsp.rs 基于tower-lsp-server提供语言服务器协议能力该功能通过默认启用的lspfeature 引入见 Cargo.toml 的[features]。zizmor 的 feature 设计也值得关注见 crates/zizmor/Cargo.tomldefault [lsp]crater-tests、gh-token-tests、online-tests、tty-tests均为测试专用 feature其中online-tests需要GH_TOKEN才能执行依赖 GitHub 的在线审计schemafeature 通过schemars生成zizmor.yml的 JSON Schema。与审计规则一一对应的集成测试位于 crates/zizmor/tests/integration/audit每个规则都配有真实/合成的test-data用例例如 crates/zizmor/tests/integration/test-data/unpinned-uses.yml、crates/zizmor/tests/integration/test-data/template-injection.yml 等可作为理解各审计规则触发条件的现成样例。三、YAML 解析层yamlpath 与 yamlpatchGitHub Actions 工作流是 YAML 文件而 zizmor 需要在保留原始格式的前提下分析它们这正是 yamlpath / yamlpatch 存在的原因。3.1 yamlpath保留格式的 YAML 特性提取crates/yamlpath/README.md 解释了其核心动机常规做法是把 YAML 解析成文档对象再解释但该解析过程是破坏性的——它会抹掉注释和精确格式。而安全工具的用户习惯以“第几行第几列”来理解问题而不是“文档层级中的某个子对象”。yamlpath 正是为了弥合这两个视角的鸿沟让程序先基于文档视图操作再把结果“翻译”回人类可理解的原始输入坐标。实现层面yamlpath 底层依赖tree-sitter与tree-sitter-yaml见 crates/yamlpath/Cargo.toml其核心实现在 src/lib.rs。仓库还提供了丰富的测试用例集crates/yamlpath/tests/testcases 下覆盖了锚点anchors-basic.yml、anchors-nested.yml、注释、指令、flow 风格、带引号的键、键缺失等场景对应的集成测试见 crates/yamlpath/tests/integration_test.rs。注意正如其 README 强调的yamlpath 不是 JSONPath / jq 之类的完整查询语言替代品它只负责“保留格式的特性提取”。3.2 yamlpatch保留注释与格式的补丁操作yamlpatch 在 yamlpath 之上提供“外科手术式”修改能力核心诉求是修改后仍保留注释、缩进、块/流式风格、单/多行样式等人类可读要素避免传统“解析—改模型—重新序列化”方案对版本控制与人工评审的破坏。其支持的操作见 crates/yamlpatch/README.md 与 crates/yamlpatch/tests/unit_tests.rsReplace替换指定路径上的值Add向映射中新增键值对Remove删除键或元素MergeInto把值合并进已有映射Append向块序列追加条目ReplaceComment替换与特性关联的注释EmplaceComment插入或更新特性关联的注释RewriteFragment重写字符串值中的局部片段对模板类场景尤其有用。每项操作都以“尽力保留文档格式与结构”为原则单元测试 crates/yamlpatch/tests/unit_tests.rs 验证了这些行为的正确性。在 zizmor 中fix输出模式output/fix.rs正是依托这类补丁能力向用户呈现可执行的修复建议。3.3 subfeature特性/子特性抽象crates/subfeature 提供“subfeature”处理 API。其 README 给出的定义subfeature 是 feature 的子集而 feature 是 zizmor 对“YAML 文档中一个语法相关提取片段”的术语。该 crate 提供创建 subfeature 并将其与父 feature 匹配的 API核心实现在 crates/subfeature/src/lib.rs。简单理解yamlpath 从原始文档中提取出一个个“feature”带位置信息的片段subfeature 则负责在这些 feature 之上做更细粒度的子集划分与匹配为审计规则定位“某一行”级别的证据提供支撑。四、语法树迭代层tree-sitter-itertree-sitter-iter 是一个极简工具库为 tree-sitter 的 CST具体语法树提供前序遍历迭代器。其 README 给出了完整用法use tree_sitter_iter::TreeIter; let tree: tree_sitter::Tree parse(); // Your parsing logic here. for node in TreeIter::new(tree) { println!(Node kind: {}, node.kind()); }由于TreeIter实现了标准Iteratortrait可以自由组合迭代器方法例如只筛选特定类型的节点for node in TreeIter::new(tree).filter(|n| n.kind() call) { // Do something with each call node. }从性能角度看README 明确指出tree-sitter-iter 的空间与时间复杂度等价于使用TreeCursorAPI 手动遍历即“与手动使用 TreeCursor 完全一致但提供了更符合人体工程学的迭代器接口”。该库被 zizmor 用于遍历tree-sitter-bash、tree-sitter-powershell、tree-sitter-yaml生成的语法树依赖关系见 crates/zizmor/Cargo.toml是template_injection、insecure_commands等需要分析脚本片段的审计规则的技术底座。五、领域建模层三个“模型”crate5.1 github-actions-modelscrates/github-actions-models/README.md 将其定位为“GitHub Actions 工作流、action 与 Dependabot 配置文件的非官方高质量数据模型”。其诞生背景是从 JSON Schema 自动生成模型“无论从表达力还是工具缺陷角度都行不通”因此改为手工维护高质量模型。源码结构印证了这一分工src/lib.rs 为 crate 根src/action.rs 建模 action含输入/输出描述测试样例见 crates/github-actions-models/tests/sample-actionssrc/workflow/ 建模工作流的 event、job 与整体结构含 event.rs、job.rs、mod.rssrc/dependabot/ 建模 Dependabot 配置v2.rssrc/common/expr.rs 承载与表达式相关的通用类型。该 crate 的集成测试收集了大量来自真实 GitHub 仓库的样例工作流见 crates/github-actions-models/tests/sample-workflows这些样例带有指向原始仓库的注释并沿用其各自的许可证条款。5.2 github-actions-expressionsgithub-actions-expressions 是 GitHub Actions 表达式的解析器与库其 README 列出的关键特性为对 GitHub Actions 表达式进行忠实解析faithful parsing带 span 的 AST 节点方便定位源码位置与 yamlpath 的“行列视角”哲学一脉相承对常量表达式提供有限的求值支持如fromJSON、toJSON、字符串函数等。实现层面src/lib.rs 组织起 lexer.rs词法、parser.rs语法、literal.rs字面量、op.rs运算符、call.rs函数调用、identifier.rs标识符、context.rs求值上下文等模块。其测试数据非常系统crates/github-actions-expressions/tests/testdata覆盖运算符优先级operators_precedence.json、大小写不敏感operators_case_insensitive.json、类型强制转换coerce_boolean.json/coerce_number.json/coerce_string.json、字符串函数startsWith.json/endsWith.json/contains.json、fromJSON/toJSON、索引与点操作op_dot.json/op_idx.json/op_idx_star.json、逻辑运算op_and.json/op_or.json/op_not.json、比较运算op_eq.json/op_ne.json/op_gt.json/op_gte.json/op_lt.json/op_lte.json以及语法错误用例syntax-errors.json。配套测试见 crates/github-actions-expressions/tests/languageservices_kat.rs。zizmor 的unsound_condition、unsound_contains、unsound_ternary等审计规则正是借助该库对工作流中的条件表达式做语义分析参见 crates/zizmor/src/audit 下的对应模块。5.3 pre-commit-modelspre-commit-models 提供 pre-commit 配置与 hook 定义的非官方高质量数据模型是 zizmor 审计范围从 GitHub Actions 扩展到 pre-commit 生态的桥梁。其结构如下src/lib.rs crate 根src/config.rs 建模.pre-commit-config.yaml配置src/hooks.rs 建模.pre-commit-hooks.yamlhook 定义测试样例见 crates/pre-commit-models/tests/sample-configs 与 crates/pre-commit-models/tests/sample-hooks配套测试 test_config.rs、test_hooks.rs。zizmor 的forbidden_uses、unpinned_uses等审计规则同样支持 pre-commit 场景测试数据可见 crates/zizmor/tests/integration/test-data/forbidden-uses/pre-commit。六、输出层zizmor-sarif 与多格式报告zizmor-sarif 是“极简 SARIF 2.1.0 数据模型”只覆盖 zizmor 当前会输出的字段见 crates/zizmor-sarif/README.md。它服务于 zizmor 的 SARIF 输出模式实现在 output/sarif.rs使 zizmor 的审计结果可以被 GitHub Code Scanning 等 SARIF 消费者直接使用仓库内对应的端到端快照测试见 crates/zizmor/tests/integration/e2e/snapshots/integration__e2e__sarif_zizmor_properties.snap。除了 SARIFzizmor 的输出层crates/zizmor/src/output还提供plainplain.rs带颜色的终端可读报告githubgithub.rsGitHub Actions 注解格式json/v1json/v1.rs结构化 JSON其快照见 crates/zizmor/tests/integration/e2e/snapshots/integration__e2e__json_v1__json_v1.snapfixfix.rs借助 yamlpatch 的补丁能力输出修复建议。七、测试与基准辅助层zizmor-devzizmor-dev 是“共享给 zizmor 集成测试与基准测试的辅助工具”。它的 README 明确警告该 crate 不提供任何稳定或受保证的接口其功能仅适用于完整源码检出环境也就是说它是纯开发期依赖不会进入生产链路。zizmor 的[dev-dependencies]中确实以路径方式引用它见 crates/zizmor/Cargo.toml。仓库根目录的 bench/ 目录含common.py、conftest.py及多个基准测试用例与 crates/zizmor/tests/integration 便是其典型使用场景。八、构建、测试与二次开发整个工作区用标准 Cargo 命令即可操作# 构建全部 crate含 zizmor CLI cargo build --release # 运行全部单元测试与集成测试 cargo test仓库通过 rust-toolchain.toml 与 Cargo.toml 中的rust-version 1.97.0固定了工具链要求并使用 mise.toml 管理开发环境测试基础设施还包括 Makefile 与 pyproject.tomlPython 侧的基准测试工具链。对于希望基于这些 crate 二次开发的场景可以从“按需取用”的角度选型只想解析 GitHub Actions 表达式 → 直接用 github-actions-expressions解析器 span 感知 AST需要在不丢失注释/格式的前提下分析 YAML → 用 yamlpath需要程序化修改 YAML 且保留人读要素 → 用 yamlpatch需要遍历 tree-sitter 语法树 → 用 tree-sitter-iter需要生成 SARIF 报告 → 用 zizmor-sarif需要完整的 GitHub Actions / pre-commit 领域模型 → 用 github-actions-models 与 pre-commit-models。九、小结zizmor 的 crate 拆分遵循了清晰的“解析 → 建模 → 分析 → 输出”分层yamlpath / yamlpatch / subfeature 负责“保留格式地读懂 YAML”tree-sitter-iter 与各类 tree-sitter 语法负责“读懂脚本片段”github-actions-expressions 负责“读懂表达式”github-actions-models / pre-commit-models 提供领域数据结构zizmor 本体完成审计并借助 zizmor-sarif 等输出模块呈现结果zizmor-dev 则为这套体系提供测试与基准支撑。每个 crate 都配有针对性的单元测试与真实样例既可以作为 zizmor 自身的构建单元也可以作为独立的 Rust 库被其他安全/静态分析项目复用。赞分享SAST供应链安全CI/CD【免费下载链接】zizmorStatic analysis for GitHub Actions (and more)项目地址https://gitcode.com/gh_mirrors/zi/zizmor点击查看免费下载相关推荐DBX Rust crates 工作区架构全解12 个模块化 crate 的职责划分、依赖边界与构建验证DBX Rust crates 工作区架构全解12 个模块化 crate 的职责划分、依赖边界与构建验证 本指南以 crates/README.md http数据库开发者工具桌面应用CLIMCP 服务AI 应用Redux-Saga源码架构包结构与模块职责解析Redux Saga源码架构包结构与模块职责解析 Redux Saga作为Redux生态中处理异步操作的核心中间件其源码架构采用模块化设计通过合理的包结构前端Windows Terminal 源码导读仓库代码组织规则、目录架构与各模块文件职责详解Windows Terminal 源码导读仓库代码组织规则、目录架构与各模块文件职责详解 本文基于仓库中的 代码组织规范文档 https://link.git桌面应用上一篇如何快速配置FGO自动化工具3步实现智能战斗下一篇GKD_THS_List一站式GKD订阅导航平台告别规则寻找困扰创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考