Ayyankhan101/PipeChecker

# PipeChecker [](https://github.com/Ayyankhan101/PipeChecker/actions/workflows/ci.yml) [](https://crates.io/crates/pipechecker) [](LICENSE-MIT) []() [](Cargo.toml) ## 解决了什么问题？ 每个开发者都遇到过这种情况： ``` 💀 You push a small change → CI fails 10 minutes later → you fix it → push again → CI fails again → repeat 3 more times ``` **PipeChecker 在本地运行**，在提交之前验证你的 CI/CD 工作流，以便你提前发现： | 捕获的问题 | 示例 | |---------|---------| | ❌ **循环依赖** | Job A → Job B → Job A | | ❌ **缺少作业引用** | `needs: [build]` 但没有 `build` 作业 | | ❌ **空流水线** | 没有定义作业或步骤 | | ⚠️ **硬编码密钥** | `API_KEY=sk_live_abc123` 出现在环境变量中 | | ⚠️ **未声明的环境变量** | `${{ env.UNKNOWN }}` 从未定义 | | ⚠️ **未固定的操作** | `uses: actions/checkout` 没有 `@v4` | | ⚠️ **Docker 使用 `:latest` 标签** | `image: nginx:latest`（不可重现的构建） | | ⚠️ **缺少作业超时** | 没有设置 `timeout-minutes` — 作业可能无限运行 | ## 视觉概览 ``` ┌─────────────────────────────────────────────────────────┐ │ YOUR WORKFLOW FILE │ │ (.github/workflows/ci.yml) │ └────────────────────────┬────────────────────────────────┘ │ ▼ ┌──────────────────────┐ │ PIPECHECKER │ │ │ │ ┌────────────────┐ │ │ │ YAML Parser │ │ │ │ GitHub/GitLab │ │ │ │ CircleCI │ │ │ └───────┬────────┘ │ │ │ │ │ ┌───────▼────────┐ │ │ │ Auditors │ │ │ │ │ │ │ │ 📋 Syntax │ │ │ │ 🔗 DAG/Cycle │ │ │ │ 🔒 Secrets │ │ │ │ 🐳 Docker │ │ │ │ 📌 Pinning │ │ │ └───────┬────────┘ │ │ │ │ └──────────┼───────────┘ │ ┌──────────────┼──────────────┐ ▼ ▼ ▼ ✅ PASS ⚠️ WARNINGS ❌ ERRORS No issues Fix before Must fix found! production before push ``` ## 支持的平台 | 平台 | 文件模式 | 状态 | |----------|-------------|--------| | **GitHub Actions** | `.github/workflows/*.yml` | ✅ 完整支持 | | **GitLab CI** | `.gitlab-ci.yml` | ✅ 完整支持 | | **CircleCI** | `.circleci/config.yml` | ✅ 完整支持 | ## 安装 ### 从 crates.io ``` cargo install pipechecker ``` ### 从源码 ``` git clone https://github.com/Ayyankhan101/PipeChecker.git cd PipeChecker cargo install --path . ``` ### 通过 npm（即将发布） ``` npm install -g pipechecker ``` ## 快速开始 ### 1. 检查单个文件 ``` pipechecker .github/workflows/ci.yml ``` ### 2. 自动检测工作流 ``` pipechecker # ✓ 自动检测: .github/workflows/ci.yml # 提供者: GitHubActions # 0 个错误，0 个警告 ``` ### 3. 审计所有内容 ``` pipechecker --all # 正在检查 3 个工作流文件... # # 📄 .github/workflows/ci.yml # 提供者: GitHubActions # ✅ 未发现问题 # # 📄 .github/workflows/deploy.yml # 提供者: GitHubActions # 1 个错误，2 个警告 # ❌ 错误: 检测到循环依赖（作业: deploy） # 💡 移除其中一个依赖以打破循环 # ⚠️ 警告: 作业 'deploy' 没有步骤 # # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ # 总计: 1 个错误，2 个警告（涉及 3 个文件） ``` ## 交互式 TUI PipeChecker 包含一个 **终端 UI**，用于浏览多个文件的结果： ``` pipechecker --tui ``` ``` ┌──────────────────────────────────────────┐ │ 🔍 Pipecheck - Interactive Mode │ ├──────────────────────────────────────────┤ │ Workflows │ │▶ ❌ deploy.yml │ 2 errors │ 1 warnings │ │ ✅ ci.yml │ 0 errors │ 0 warnings │ │ ⚠️ lint.yml │ 0 errors │ 3 warnings │ ├──────────────────────────────────────────┤ │ [↑/↓] Navigate [Enter] Details [Q] Quit│ └──────────────────────────────────────────┘ ``` **键盘快捷键：** | 按键 | 操作 | |-----|--------| | `↑` / `k` | 向上移动 | | `↓` / `j` | 向下移动 | | `Enter` / `Space` | 切换详细视图 | | `q` / `Esc` | 退出 | ## 全部 CLI 参数 | 参数 | 描述 | |------|-------------| | `FILE` | 工作流文件路径 | | `--all`, `-a` | 审计 **所有** 发现的工作流文件 | | `--tui` | 启动交互式终端 UI | | `--watch`, `-w` | 监视文件变化并重新运行审计 | | `--fix` | 自动修复问题（固定未固定的操作 + Docker `:latest` 标签） | | `--install-hook` | 安装 git pre-commit 钩子 | | `--format`, `-f` `` | 输出格式（默认：`text`） | | `--strict`, `-s` | 将警告视为错误（退出代码为 1） | | `--quiet`, `-q` | 仅输出错误 — 抑制警告和信息。适用于 CI | | `--verbose` | 显示诊断信息（运行的审计器、每个严重性计数、发现的文件） | | `--no-pinning` | 跳过 Docker 镜像和操作固定检查 | | `--version` | 显示版本 | | `--help` | 显示帮助 | ## 输出说明 ### 严重性级别 | 符号 | 级别 | 含义 | |--------|-------|---------| | ❌ | **错误** | 必须修复 — 会破坏你的流水线 | | ⚠️ | **警告** | 应该修复 — 可能导致后续问题 | | ℹ️ | **信息** | 提示信息 — 无需担心 | ### 详细输出的示例 ``` Provider: GitHubActions 2 errors, 1 warnings ❌ ERROR: Circular dependency detected (job: deploy) [line 42] 💡 Remove one of the dependencies to break the cycle ❌ ERROR: Job 'deploy' depends on non-existent job 'build' (job: deploy) [line 45] 💡 Add a job with id 'build' or remove the dependency ⚠️ WARNING: Job 'lint' has no steps (job: lint) [line 12] 💡 Add steps to perform work in this job ``` 每个问题都包括： - **问题描述**（清晰说明） - **位置**（作业名称 + 行号） - **修复建议**（可操作的建议） ## JSON 输出 适用于 CI/CD 集成或程序化处理： ``` pipechecker --format json ``` ``` { "provider": "GitHubActions", "issues": [ { "severity": "Error", "message": "Circular dependency detected: job-a -> job-b -> job-a", "location": { "line": 42, "column": 3, "job": "deploy" }, "suggestion": "Remove one of the dependencies to break the cycle" } ], "summary": "1 errors, 0 warnings" } ``` ## 运行模式 ### 🔧 自动修复模式 自动固定未固定的 GitHub Actions 到已知版本： ``` pipechecker --fix ``` ``` 🔧 Auto-fix mode ✨ Fixed 2 issue(s) in .github/workflows/ci.yml: actions/checkout → actions/checkout@v4 actions/setup-node → actions/setup-node@v4 💡 Review the changes and commit them! ``` ### 👀 监视模式 监视工作流文件并在每次保存时重新运行 — 适合开发过程： ``` pipechecker --watch ``` ``` 👀 Watching for workflow changes... Press Ctrl+C to stop 🔄 File changed: .github/workflows/ci.yml Provider: GitHubActions 0 errors, 0 warnings ✅ All checks passed ``` ### 🤫 静默模式（CI 友好） 仅输出错误 — 抑制警告和信息。适用于 CI 流水线，需要干净的日志输出： ``` pipechecker --quiet # 或 pipechecker -q ``` ``` ❌ Circular dependency detected (job: deploy) (in .github/workflows/deploy.yml) ``` 如果存在错误，退出代码仍为 `1` — 与 `--strict` 配合使用可在发现任何问题时使 CI 失败。 ### 📢 详细模式 查看 PipeChecker 的具体操作 — 包括发现了哪些文件、运行了哪些审计器，以及按严重性统计： ``` pipechecker --verbose ``` ``` 📄 Auditing: .github/workflows/ci.yml 🔍 Auditors ran: syntax, dag, secrets, pinning 📊 Found: 0 errors, 1 warnings, 0 info ⏱️ Checked in 3.2ms ``` ### ⏱️ 耗时统计 每个审计现在都会显示耗时 — 因为速度很重要： ``` pipechecker .github/workflows/ci.yml ``` ``` Provider: GitHubActions 0 errors, 0 warnings ✅ All checks passed ⏱️ Checked in 2.1ms ``` ### 🔒 预提交钩子 再也不用提交有问题的流水线了： ``` pipechecker --install-hook ``` ``` ✅ Pre-commit hook installed! Pipecheck will run before every commit Use 'git commit --no-verify' to skip ``` 该钩子会自动验证你暂存的任何工作流文件： ``` $ git commit -m "Update CI pipeline" 🔍 Checking workflows with pipechecker... ❌ ERROR: Circular dependency detected (job: deploy) [line 42] 💡 Remove one of the dependencies to break the cycle ❌ Workflow validation failed! Fix errors above or use 'git commit --no-verify' to skip ``` ## 配置文件 在项目根目录创建 `.pipecheckerrc.yml` 来自定义行为： ``` # 要跳过的文件（支持通配符模式） ignore: - .github/workflows/experimental-*.yml - .github/workflows/draft-*.yml - old-pipeline.yml # 切换单个审计规则 rules: circular_dependencies: true # Detect dependency cycles missing_secrets: true # Flag hardcoded secrets docker_latest_tag: true # Warn about :latest tags ``` PipeChecker 按以下顺序搜索配置文件： 1. `.pipecheckerrc.yml` 2. `.pipecheckerrc.yaml` 3. `.pipechecker.yml` ## 审计器如何工作 ### 📋 语法审计器 验证流水线的结构完整性： - ✅ 已定义作业 - ✅ 作业中包含步骤 - ✅ 无重复作业 ID - ✅ `needs` / `depends_on` 目标存在 ### 🔗 DAG 审计器（循环检测） 构建 **依赖图** 并运行 **Tarjan 强连通分量** 算法： ``` job-a ──depends──▶ job-b ▲ │ │ ▼ └────depends──── job-c ``` → ❌ **检测到循环依赖：** job-a → job-b → job-c → job-a ### 🔒 密钥审计器 扫描环境变量和运行块中的安全问题： ``` env: API_KEY: sk_live_abc123 # ⚠️ Hardcoded secret TOKEN: ${{ secrets.TOKEN }} # ✅ Correct way RUN: echo ${{ secrets.API_KEY }} # ℹ️ Info — ensure it's configured RUN: echo ${{ env.UNDEFINED }} # ⚠️ Undeclared env var ``` 检测内容包括： - 硬编码的 API 密钥、密码、令牌 - `with:` 块中的密钥引用 - 未声明的 `${{ env.X }}` 引用 - 可疑值（长字母数字字符串、Base64） ### 🐳 Docker 与 📌 固定审计器 确保可重现的构建： ``` uses: actions/checkout # ⚠️ No version pin uses: actions/checkout@v4 # ✅ Pinned image: nginx:latest # ⚠️ Unpredictable image: nginx:1.25-alpine # ✅ Specific ``` ## 实际示例 ### 示例 1：有效的流水线 ``` $ pipechecker .github/workflows/ci.yml Provider: GitHubActions 0 errors, 0 warnings ``` ### 示例 2：循环依赖 ``` jobs: deploy: needs: [test] steps: [{ run: echo deploy }] test: needs: [deploy] steps: [{ run: echo test }] ``` ``` $ pipechecker broken.yml Provider: GitHubActions 1 errors, 0 warnings ❌ ERROR: Circular dependency detected (job: deploy) 💡 Remove one of the dependencies to break the cycle ``` ### 示例 3：硬编码密钥 ``` jobs: build: env: API_SECRET: sk_live_hardcoded_value steps: [{ run: echo building }] ``` ``` $ pipechecker secrets.yml Provider: GitHubActions 0 errors, 1 warnings ⚠️ WARNING: Job 'build' env 'API_SECRET' may contain a hardcoded secret 💡 Use secrets.API_SECRET instead of hardcoding ``` 架构 ``` pipechecker/ ├── src/ │ ├── main.rs # CLI entry point (clap) │ ├── lib.rs # Public API — audit_file, audit_content, discover_workflows │ ├── models.rs # Core types — Pipeline, Job, Step, Issue, Severity │ ├── error.rs # Error enum (thiserror) │ ├── config.rs # .pipecheckerrc.yml loading │ ├── fix.rs # Auto-fix for action pinning │ ├── tui.rs # Interactive terminal UI (ratatui + crossterm) │ ├── parsers/ │ │ ├── mod.rs # Provider detection + dispatch │ │ ├── github.rs # GitHub Actions YAML parser │ │ ├── gitlab.rs # GitLab CI YAML parser │ │ └── circleci.rs # CircleCI YAML parser │ └── auditors/ │ ├── mod.rs # Module gate │ ├── syntax.rs # Structural validation │ ├── dag.rs # Dependency graph + cycle detection (petgraph) │ ├── secrets.rs # Secret/env var scanning (regex) │ └── pinning.rs # Action/Docker image pinning ├── tests/ │ ├── parser_test.rs # Parser integration tests │ └── auditors_test.rs # Auditor + fixture tests └── tests/fixtures/ # Sample workflow files for testing ``` ## CI/CD 集成 将 PipeChecker 加入你自己的 CI 流水线： ``` - name: Validate workflows run: | cargo install pipechecker pipechecker --all --strict --format json ``` 或将其用作预提交钩子（推荐）： ``` pipechecker --install-hook ``` ## 开发 ### 运行测试 ``` cargo test # 103 个测试 — 全部通过 ``` ### 代码风格与格式化 ``` cargo clippy -- -D warnings cargo fmt -- --check ``` ### 覆盖率 ``` cargo tarpaulin --fail-under 55 ``` ## 许可证 本项目根据 **MIT** 或 **Apache-2.0** 许可协议授权： ``` SPDX: MIT OR Apache-2.0 ```

**PipeChecker** — *因为等待 10 分钟让 CI 告诉你有拼写错误并不是乐趣所在。* [报告问题](https://github.com/Ayyankhan101/PipeCheck/issues) · [请求功能](https://github.com/Ayyankhan101/PipeCheck/issues) · [贡献指南](CONTRIBUTING.md)

标签：CircleCI, GitHub Actions, GitLab CI, Rust, TUI工具, Watch模式, WebSocket, 二进制发布, 云安全监控, 交互式TUI, 依赖分析, 可视化界面, 威胁情报, 安全扫描, 工作流验证, 开发者工具, 开源工具, 开源框架, 循环依赖检测, 持续集成, 文件监听, 时序注入, 本地校验, 硬编码密钥, 管道审计, 网络流量审计, 网络调试, 自动化, 自动笔记, 语法检查, 通知系统, 静态分析