PythonWoods/zenzic-action

面向 Markdown/MDX 图的确定性文档完整性引擎与 SAST。

在 CI 中运行 Zenzic SAST 和图完整性分析——直接在 GitHub Code Scanning 中展示结果，无需阅读日志。 **退出码契约 (ADR-075)。** 该封装器原样传播 Zenzic 的退出码，不进行重映射。退出码 1（质量）遵循 `fail-on-error` 设置。退出码 2（凭证）和退出码 3（路径遍历）无论 `fail-on-error: false` 或 `--exit-zero` 设置如何，都会终止作业——安全发现绝不会在执行边界处被抑制。 ## 核心功能 | 功能 | 类别 | 描述 | |---|---|---| | **安全扫描 (SAST)** | 安全 | 检测硬编码 token (Z201) 和路径遍历 (Z202/Z203)；退出码 2/3 在 `fail-on-error: false` 下依然生效 | | **图拓扑分析** | 拓扑 | 虚拟站点地图 (VSM) 验证跨文件链接、孤立页面和失效的导航图节点 | | **确定性 CI/CD 执行** | CI/CD | 零 DBT 质量门禁，确保跨构建环境的按位可复现执行 | | **零配置安装** | 执行 | `uvx zenzic` —— runner 上无需 Python 工具链 | | **SARIF 输出** | 集成 | 发现结果直接输入至 GitHub Code Scanning | | **主权审计模式** | 安全 | `audit: "true"` 绕过抑制规则，展示未过滤的文档图状态 | | **PR 批注** | 反馈 | 在 diff 上进行内联批注，按严重性进行颜色编码 | | **版本锁定** | 治理 | 锁定到确切版本（例如 `0.25.0`），实现确定性、可复现的 CI 门禁 | ## 快速开始 最小化配置——零 Python 设置，一步即可将 SARIF 发送到 Code Scanning： ``` - uses: actions/checkout@v4 - name: Run Zenzic Documentation Quality Gate uses: PythonWoods/zenzic-action@v2 with: version: "0.27.0" format: sarif upload-sarif: "true" permissions: contents: read security-events: write ``` 在你的仓库根目录放置一个 `.zenzic.toml`，该 action 会自动识别它——无需提供 `config-file` 输入。如果你的文档不在默认的 `docs/` 目录下，请运行一次 `zenzic init` 来生成配置。 有关高级配置（配置发现、主权覆盖、质量门禁评分、每晚审计），请参阅 [Zenzic Action 文档](https://zenzic.dev/docs/reference/zenzic-action)。 ## 🔍 可视化反馈 Zenzic Action 直接在你工作的地方展示结果——无需深入翻阅 CI 日志。

## 集成蓝图 以下开箱即用的 GitHub Actions 工作流模板涵盖了 `zenzic-action` 的四种主要集成模式。 ### 1. 基线检查（SAST 与拓扑验证） 此蓝图提供静态应用安全测试 (SAST)、链接验证和图拓扑验证。它在 push 和 PR 期间执行，确保仓库中不会引入损坏的链接、凭证泄漏或无效配置。 ``` name: Zenzic Baseline Audit on: push: branches: [ main ] pull_request: branches: [ main ] jobs: baseline-check: runs-on: ubuntu-latest steps: - name: Checkout Repository uses: actions/checkout@v4 - name: Run Zenzic Baseline uses: PythonWoods/zenzic-action@v2 with: version: "0.25.0" format: text fail-on-error: "true" ``` ### 2. 安全强化（SARIF + 上传集成） 此蓝图运行安全强化门禁。它执行密钥扫描器 (`guard-scan`) 以捕获暴露的凭证和路径遍历，然后将 SARIF 报告直接上传到 GitHub Code Scanning Security 标签页。 ``` name: Zenzic Hardened Quality Gate on: push: branches: [ main ] pull_request: branches: [ main ] jobs: security-gate: runs-on: ubuntu-latest permissions: contents: read security-events: write steps: - name: Checkout Repository uses: actions/checkout@v4 - name: Run Hardened Zenzic Audit uses: PythonWoods/zenzic-action@v2 with: version: "0.25.0" format: sarif upload-sarif: "true" guard-scan: "true" ``` ### 3. PR 治理（内联批注与 DQS 追踪） 此蓝图实施 pull-request 治理。它从默认分支下载 DQS 基线，运行质量门禁比较，将问题映射为内联批注，并发布文档质量分数 (DQS) 摘要到工作流运行中。 ``` name: Zenzic PR Governance & DQS Tracking on: pull_request: branches: [ main ] jobs: pr-governance: runs-on: ubuntu-latest permissions: contents: read pull-requests: write steps: - name: Checkout Repository uses: actions/checkout@v4 - name: Run PR Governance Check uses: PythonWoods/zenzic-action@v2 with: version: "0.25.0" format: text fail-on-error: "true" ``` ### 4. 主权每晚审计（完全未过滤审计） 按计划运行未抑制的审计，将隐藏的技术债务直接报告给 Code Scanning。 ``` name: Zenzic Sovereign Audit on: schedule: - cron: "0 2 * * *" # Daily at 02:00 UTC jobs: sovereign-audit: runs-on: ubuntu-latest permissions: contents: read security-events: write steps: - name: Checkout Repository uses: actions/checkout@v4 - name: Run Sovereign Audit uses: PythonWoods/zenzic-action@v2 with: version: "0.25.0" audit: "true" format: sarif upload-sarif: "true" ``` ## Action 输入参考 | 输入 | 默认值 | 描述 | |:---|:---|:---| | `version` | `0.27.0` | 要执行的 Zenzic Core 版本。锁定到特定版本（例如 `0.25.0`）以实现可复现的 CI。 | | `format` | `"text"` | 输出格式：`text`、`json` 或 `sarif` | | `upload-sarif` | `"false"` | 自动将 SARIF 输出上传到 GitHub Code Scanning | | `guard-scan` | `"false"` | 触发致命的前置门禁安全扫描 (`zenzic guard scan`) | | `audit` | `"false"` | 主权审计模式：绕过所有活动的抑制规则 | | `fail-on-error` | `"true"` | 控制质量发现（退出码 1）时的作业失败状态 | | `config-file` | `""` | 自定义 `.zenzic.toml` 配置的可选路径 | ## 职责矩阵 (ADR-075) | 关注点 | Zenzic Core | Zenzic Action | |:---|:---:|:---:| | 链接与拓扑验证 | ✅ | 执行 Core | | 凭证扫描器 (Z2xx) | ✅ | 执行 Core | | 退出码契约 (0/1/2/3) | ✅ | 强制执行 | | GitHub 批注 (`::error::`) | — | ✅ | | Code Scanning SARIF 上传 | — | ✅ | | PR 内联 diff 批注 | — | ✅ | ## 许可证与支持 采用 Apache-2.0 许可证。有关完整的发现分类和开发者指南，请访问 [zenzic.dev](https://zenzic.dev)。

标签：GitHub Action, Markdown, SAST, 云安全监控, 图数据库, 文档完整性, 盲注攻击, 逆向工具, 静态分析