Zizmor项目使用指南：GitHub Actions安全审计工具详解

Zizmor项目使用指南：GitHub Actions安全审计工具详解

zizmor A static analysis tool for GitHub Actions 项目地址: https://gitcode.com/gh_mirrors/zi/zizmor

项目概述

Zizmor是一款专为GitHub Actions设计的安全审计工具，能够帮助开发者和安全团队识别工作流和复合动作中的潜在安全问题。它通过静态分析技术检测代码注入、环境变量滥用、未固定依赖等常见安全风险。

输入源管理

Zizmor支持三种输入源类型，可灵活组合使用：

1. 独立工作流文件：直接指定YAML文件路径，如ci.yml
2. 本地代码仓库：指定包含.github/workflows的目录路径
3. 远程代码仓库：使用owner/repo格式指定GitHub仓库

对于远程仓库，支持通过@符号指定特定版本：

# 默认分支最新提交
zizmor owner/repo

# 指定分支或标签
zizmor owner/repo@v1.0

# 指定具体提交SHA
zizmor owner/repo@a1b2c3d

收集模式配置

Zizmor提供多种收集策略，通过--collect参数控制：

# 默认模式，遵守.gitignore规则
zizmor --collect=default my-repo/

# 收集所有文件（包括通常被忽略的文件）
zizmor --collect=all my-repo/

# 仅收集工作流文件
zizmor --collect=workflows-only my-repo/

# 仅收集动作定义
zizmor --collect=actions-only my-repo/

运行模式详解

Zizmor提供三种运行模式以适应不同场景：

1. 离线模式：完全本地运行，不访问网络

   zizmor --offline workflow.yml
   

2. 在线模式：允许获取远程资源并执行需要网络的审计

   zizmor --gh-token $(gh auth token) workflow.yml
   

3. 有限在线模式：仅获取远程资源但不执行网络审计

   zizmor --no-online-audits --gh-token $(gh auth token) repo/example
   

身份验证配置

使用在线模式时，Zizmor需要GitHub API令牌。推荐使用GitHub CLI提供的令牌：

zizmor --gh-token $(gh auth token) owner/repo

对于私有仓库审计，令牌需要以下权限：

• GitHub Actions：contents: read
• OAuth/经典PAT：repo范围
• 细粒度PAT：适当的仓库访问范围

结果输出格式

Zizmor支持多种输出格式，便于不同场景使用：

1. 默认格式：类Cargo风格，适合终端查看

   zizmor workflow.yml
   

2. JSON格式：适合自动化处理

   zizmor --format=json workflow.yml | jq .
   

3. 静态分析结果交换格式：与GitHub高级安全功能集成

   zizmor --format=static-analysis-results workflow.yml
   

4. GitHub注释格式：直接在CI中显示问题

   zizmor --format=github workflow.yml
   

审计策略配置

Zizmor提供三种预设审计策略：

1. 常规策略（默认）：平衡信号与噪音，适合大多数场景

   zizmor --persona=regular workflow.yml
   

2. 严格策略：报告代码异味和潜在问题

   zizmor --pedantic workflow.yml
   

3. 审计员策略：报告所有可能问题（包括可能的误报）

   zizmor --persona=auditor workflow.yml
   

结果过滤与忽略

基础过滤

# 仅显示中高严重性问题
zizmor --min-severity=medium workflow.yml

# 仅显示高置信度结果
zizmor --min-confidence=high workflow.yml

高级JSON过滤

zizmor --format=json workflow.yml | jq 'map(select(.determinations.severity == "High"))'

忽略特定结果

1. 行内注释忽略：

   run: | # zizmor: ignore[template-injection] 此处安全
     echo "${{ inputs.user_input }}"
   

2. 配置文件忽略（zizmor.yml）：

   rules:
     template-injection:
       ignore:
         - safe.yml
         - special-case.yml:123
   

CI/CD集成建议

1. 常规检查：使用中等严格度和JSON格式

   zizmor --min-severity=medium --format=json . > results.json
   

2. 高级安全检查：启用所有审计并使用静态分析结果交换格式

   zizmor --persona=auditor --format=static-analysis-results . > results.static-analysis
   

3. 开发环境检查：使用严格策略和默认输出

   zizmor --pedantic .
   

最佳实践

1. 在CI流水线中使用--min-severity=medium平衡信号与噪音
2. 开发时使用--pedantic模式识别潜在问题
3. 安全审计时使用--persona=auditor进行全面检查
4. 对已知安全的设计决策使用忽略注释或配置文件
5. 定期更新Zizmor以获取最新的审计规则

通过合理配置Zizmor，您可以有效提升GitHub Actions工作流的安全性，同时保持开发效率。工具提供的多种运行模式和输出格式使其能够适应从本地开发到企业级CI/CD的各种场景。

zizmor A static analysis tool for GitHub Actions 项目地址: https://gitcode.com/gh_mirrors/zi/zizmor