paruff/uFawkesPipe

# uFawkesPipe [](https://github.com/paruff/uFawkesPipe/actions/workflows/ci-pipeline.yml) [](LICENSE) **Fawkes IDP 家族的集成与交付层** uFawkesPipe 是一个基于 Woodpecker CI 的 CI/CD 平台，集成了 SAST（SonarQube、Trivy、Gitleaks）、Cloud Native Buildpacks 以及 DefectDojo 安全扫描摄取功能 —— 即 Fawkes IDP 的 CI/CD 层。 ## 🚀 功能 - **多语言支持** - 通过 Cloud Native Buildpacks 构建使用 Java、Python、Node.js、Go、Ruby 等语言的应用程序 - **标准流水线契约** - 通过 `.fawkespipe.yml` 配置定义 CI/CD 行为（参见 [docs/pipeline-contract.md](docs/pipeline-contract.md)） - **Cloud Native Buildpacks** - 无需 Dockerfile 即可构建兼容 OCI 的容器镜像 - **安全第一的流水线** - 集成了 Gitleaks 密钥扫描、Trivy 漏洞扫描（文件系统 + 容器）以及 SonarQube SAST - **DefectDojo 集成** - 构建后自动摄取安全扫描结果 - **基于 Woodpecker** - 轻量级、YAML 驱动的 CI/CD 编排，支持 GitHub OAuth - **DORA 可观测性** - 结构化 JSON 日志、OTEL 部署事件发射、Prometheus 指标 - **独立 + 套件模式** - 独立运行或连接至 uFawkesRes（PostgreSQL/Traefik）和 uFawkesObs（OTEL/Loki） ## 📋 流水线阶段 uFawkesPipe 中的每个流水线都遵循以下标准化阶段（定义在 [`.woodpecker.yml`](.woodpecker.yml) 中）： | # | 阶段 | 步骤 | 并行 | 分支门控 | |---|-------|-------|----------|-------------| | 1 | **validate (验证)** | `init` → `lint-yaml` + `lint-shell` | 是 (lint) | 无 | | 2 | **test (测试)** | `unit-tests` + `integration-tests` + `contract-tests` | 是 | 无 | | 3 | **security (安全)** | `secrets-scan` → `vuln-scan-fs` → `vuln-scan-image` | 顺序执行 | `vuln-scan-image`: 仅限 main | | 4 | **build (构建)** | `build-image` | — | 仅限 main | | 5 | **publish (发布)** | `upload-defectdojo` | — | 仅限 main | | 6 | **deploy (部署)** | `notify-obs` | — | 仅限 main | **步骤详情：** - **init** — 创建制品目录（security、coverage、tests） - **lint-yaml** — 使用 yamllint 验证 `compose.yaml`、`.woodpecker.yml`、`.env.example` - **lint-shell** — 对 `scripts/*.sh` 和 `validate.sh` 进行 ShellCheck 验证 - **unit-tests** — 快速、隔离的 pytest 单元测试（无外部依赖） - **integration-tests** — 跨组件测试（可能需要 Docker） - **contract-tests** — 流水线契约、compose 和 YAML 验证 - **secrets-scan** — 硬门控：使用 `.gitleaks.toml` 规则和 `.secrets.baseline` 进行 Gitleaks 密钥检测 - **vuln-scan-fs** — Trivy 文件系统漏洞扫描（整个工作区） - **vuln-scan-image** — Trivy 容器镜像漏洞扫描（仅限 main 分支） - **build-image** — 通过 CNB 构建容器镜像（占位符） - **upload-defectdojo** — 收集 Gitleaks + Trivy 结果并 POST 到 DefectDojo API（非阻塞） - **notify-obs** — 向 uFawkesObs OTEL collector 发送结构化部署事件（非阻塞） 所有步骤均通过 `scripts/dora-log.sh` 发送结构化 JSON 日志，与 uFawkesObs/Loki 摄取兼容。 ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ uFawkesPipe Platform │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌────────────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Woodpecker Server │ │ SonarQube │ │ Portainer │ │ │ │ + Agent │ │ (SAST) │ │ CE (CD) │ │ │ │ │ │ │ │ │ │ │ │ - Pipeline YAML │ │ - Quality │ │ - Stacks │ │ │ │ - GitHub OAuth │ │ Gates │ │ - Secrets │ │ │ │ - CLI triggers │ │ - Coverage │ │ - Volumes │ │ │ └────────────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ └──────────────────────────┴────────────────┘ │ │ │ │ │ ┌────────▼────────┐ │ │ │ CNB Builder │ │ │ │ (Buildpacks) │ │ │ └────────┬────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ Docker │ │ │ │ Registry │ │ │ └─────────────────┘ │ │ │ │ Suite mode: ┌────────────┐ ┌───────────────────┐ │ │ │ uFawkesRes │ │ uFawkesObs │ │ │ │ (Postgres, │◄──│ (OTEL, Loki, │ │ │ │ Traefik) │ │ Prometheus) │ │ │ └────────────┘ └───────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` - **独立模式** (`make up`)：Woodpecker + SonarQube + Portainer，本地存储 - **套件模式** (`make up-suite`)：增加 uFawkesRes PostgreSQL、Valkey、Traefik ingress 以及 uFawkesObs OTEL Collector、Alloy、Loki、Prometheus ## 🛠️ 快速开始 ### 前置条件 - Docker Engine 20.10+ - Docker Compose v2.0+（`docker compose` 插件，而非独立的 `docker-compose`） - 4GB+ 内存可供容器使用 - 用于 Woodpecker 身份验证的 GitHub OAuth App（Client ID + Secret） - DockerHub 账户（用于镜像仓库） ### 设置 1. **克隆仓库** git clone https://github.com/paruff/uFawkesPipe.git cd uFawkesPipe 2. **配置环境** cp .env.example .env # 使用您的凭证和 OAuth 密钥编辑 .env nano .env 3. **启动平台** # 独立模式 (Woodpecker + SonarQube + Portainer) make up # 或套件模式 (连接到 uFawkesRes + uFawkesObs) make up-suite 4. **访问平台** | 服务 | 端口 | URL | 认证方式 | | ------------- | ---- | ---------------------- | -------------------------- | | Woodpecker CI | 8000 | http://localhost:8000 | GitHub OAuth | | Portainer CE | 9443 | https://localhost:9443 | 管理员账户（首次使用） | | SonarQube | 9000 | http://localhost:9000 | admin / (来自 .env) | ### 首次流水线 1. 在您的应用程序仓库中添加 `.fawkespipe.yml`（参见 [docs/pipeline-contract.md](docs/pipeline-contract.md)） 2. 推送到 GitHub 3. 在 Woodpecker UI 中：Repositories → 激活您的仓库 4. 推送代码 → 通过 GitHub webhook 自动触发流水线 完整详情：[QUICKSTART.md](QUICKSTART.md) ## 📖 流水线契约参考 `.fawkespipe.yml` 文件是标准的流水线契约，定义了应用程序如何构建、测试、扫描和部署。它放置在您的应用程序仓库的根目录下。 ### 核心部分 - **`app`** - 应用程序元数据（名称、类型、语言、版本） - **`build`** - 构建配置：`cnb` (Cloud Native Buildpacks)、`docker` 或 `custom` - **`stages`** - 启用/禁用并配置流水线阶段（lint、test、sast、dependency_scan、build、image_scan、push） - **`notifications`** - Slack 和电子邮件通知配置 - **`kubernetes`** - Kubernetes 部署配置（晋升路径） - **`advanced`** - 超时、重试、并行执行、制品保留 ### 特定语言示例 - [Java/Maven](examples/.fawkespipe-java-maven.yml) - [Python/Flask](examples/.fawkespipe-python-flask.yml) - [Node.js/Express](examples/.fawkespipe-nodejs-express.yml) - [Go](examples/.fawkespipe-go.yml) **完整参考：[docs/pipeline-contract.md](docs/pipeline-contract.md)** ## 🔌 Webhook API uFawkesPipe 暴露 Woodpecker CI webhook 以用于外部平面集成。 ### 通过 Webhook 触发流水线 当仓库被激活时，Woodpecker CI 会自动接收来自 GitHub 的 push webhook。webhook URL 由 Woodpecker 在激活仓库期间自动配置。 **GitHub Webhook 集成**： 在 Woodpecker 中激活仓库时会自动配置。该 webhook 指向： - Payload URL: `http://:8000/api/hooks/` - Content type: `application/json` - 事件: Push、Pull Request ### CLI 命令 **Woodpecker CLI** 从命令行触发： ``` # 列出 repositories 和 pipelines woodpecker-cli repo ls woodpecker-cli repo info woodpecker-cli pipeline ls --repo # 触发特定 pipeline woodpecker-cli pipeline start ``` 完整用法请参见 [Woodpecker CLI 文档](https://woodpecker-ci.org/docs/cli)。 ## ☸️ Kubernetes 晋升路径 uFawkesPipe 专为使用 Docker Compose 的单节点开发而设计。针对 Woodpecker 技术栈的 Kubernetes 部署支持已在计划中，但尚未实现。 有关计划中的配置 schema，请参阅流水线契约中的 [`kubernetes` 部分](docs/pipeline-contract.md#kubernetes---kubernetes-deployment)。 ## 🔒 安全特性 ### 密钥检测 - **Gitleaks** — 硬门控：在每次提交/推送时扫描所有文件以查找密钥、API key 和凭证 - **Pre-commit hook** — 用于已知误报的 detect-secrets 基准（`.secrets.baseline`） - **基准自动更新** — `.secrets.baseline` 在行号更改时自动更新 ### 静态应用程序安全测试 (SAST) - **SonarQube** — 代码质量和安全漏洞分析 - **Trivy** — 文件系统和代码漏洞扫描 ### 依赖扫描 - **Trivy** — 全面的漏洞数据库扫描（文件系统和容器镜像） - **OWASP Dependency-Check** — 已知的易受攻击依赖项（在 `.fawkespipe.yml` 中配置） ### 容器安全 - **Trivy** — 容器镜像漏洞扫描（仅限 main 分支） - **Cloud Native Buildpacks** — 无需 Dockerfile 即可构建 OCI 镜像（减少攻击面） - **镜像锁定** — 所有服务镜像均锁定至特定版本（不使用 `:latest`） ### DefectDojo 集成 - 自动将 Gitleaks 和 Trivy 扫描结果上传至 DefectDojo API - 非阻塞 — 扫描摄取失败不会导致流水线失败 ## 🧪 测试覆盖率 `tests/unit/` 测试套件静态验证 `.woodpecker.yml` 流水线定义 — 它**不会**针对活动的 Woodpecker 实例执行流水线。端到端流水线执行通过 `make up` + Woodpecker UI 进行手动验证。 ### `pytest tests/unit/` 验证的内容 | 测试模块 | 覆盖范围 | |-------------|----------| | `test_woodpecker_yml.py` | **流水线结构**：有效的 YAML、`steps` 列表存在、包含 `when` 部分。**步骤排序**：`init` 在首位、lint 在 security 之前、test 在 security 之前。**步骤配置**（每个步骤）：正确的镜像及版本锁定（例如 `alpine:3.20`、`zricethezav/gitleaks:v8.18.2`、`curlimages/curl:8.6.0`）、必需的命令/标志（针对密钥的 `--format json`、`--no-progress`、`--exit-code=1`）、输出路径（`artifacts/security/*.json`）、密钥配置（`from_secret`）、分支条件（`when: branch: main`）、DORA 日志记录（`source dora-log.sh`、`dora_start`、`dora_emit`）、非阻塞行为（失败时 `dora_warn`）。**Trivy 例外**：明确断言扫描镜像使用 `aquasec/trivy:latest` 并附有文档说明理由。**制品目录**：`init` 通过 `mkdir -p` 创建 `artifacts/security`、`artifacts/coverage`、`artifacts/tests`。 | | `test_docker_compose_validation.py` | **Compose 结构**：有效的 YAML、`services` 部分、所有服务都有 `image`、没有 `:latest` 标签、所有服务都有 `labels`、存在卷声明、命名卷（无主机路径）、compose 中无密钥。**健康检查**：服务声明了 `healthcheck`（`dependency-check`、`pack-cli` 除外）。 | | `test_compose_network.py` | **独立模式**：`compose.yaml` 声明无 `fawkes-net`，没有服务附加到它，`woodpecker-agent` 没有 `WOODPECKER_BACKEND_DOCKER_NETWORK`。**套件模式**：`compose.suite.yaml` 将 `fawkes-net` 声明为 `external: true` 及 `name: fawkes-net`，所有 4 个服务都附加，agent 包含 `WOODPECKER_BACKEND_DOCKER_NETWORK=fawkes-net`。**Makefile**：`network` 目标幂等地创建 `fawkes-net`（双管道 true）；`up` 无 `network` 依赖；`up-suite` 有 `network` 依赖。 | | `test_artifact_dirs` | **Init 步骤**：第一步是使用 `alpine:3.20` 的 `init`；命令包含使用 `mkdir -p` 的 `mkdir -p artifacts/security`、`artifacts/coverage`、`artifacts/tests`。 | ### 单元测试未涵盖的内容 - ❌ 针对 Woodpecker 服务器的实时流水线执行 - ❌ GitHub webhook 投递 / 仓库激活流程 - ❌ Docker 镜像构建 / CNB buildpack 执行 - ❌ SonarQube 质量门评估 - ❌ DefectDojo API 摄取 - ❌ OTEL collector 事件发射 / Loki 摄取 - ❌ 跨服务集成（Woodpecker ↔ SonarQube ↔ Portainer） - ❌ 性能 / 负载特性 ### 运行测试 ``` # 所有单元测试（快速，无外部 deps） python3 -m pytest tests/unit/ -v # 带 markers（unit, integration, smoke, acceptance） python3 -m pytest tests/ -m unit python3 -m pytest tests/ -m integration python3 -m pytest tests/ -m smoke python3 -m pytest tests/ -m acceptance ``` ## 🔧 配置 ### 流水线配置 CI 流水线定义在 [`.woodpecker.yml`](.woodpecker.yml) 中。自定义它以： - 添加或删除流水线步骤 - 为不同阶段配置环境变量 - 为 registry 身份验证和 API token 定义密钥 ### 流水线契约配置 应用程序团队通过位于其仓库根目录下的 `.fawkespipe.yml` 配置其流水线行为。完整参考请参见 [docs/pipeline-contract.md](docs/pipeline-contract.md)。 ### 服务配置 编辑 [`compose.yaml`](compose.yaml) 以： - 更改暴露端口 - 添加更多服务 - 配置资源限制 - 添加额外网络 ### 卷管理 持久化数据存储在 Docker 卷中： - `woodpecker_data` — Woodpecker CI 数据库和配置 - `portainer_data` — Portainer CD 数据 - `sonarqube_data` — SonarQube 分析数据 - `pack_cache` — CNB 构建缓存 **备份卷：** ``` docker run --rm -v ufp_woodpecker_data:/data -v $(pwd):/backup alpine \ tar czf /backup/woodpecker-backup.tar.gz -C /data . ``` ## 🐛 故障排除 ### Woodpecker 无法启动 ``` # 检查日志 make logs # 检查 Woodpecker 状态 make status # 验证 .env 中的 GitHub OAuth 配置 grep WOODPECKER_GITHUB .env # 重置 Woodpecker 数据 make down docker volume rm ufp_woodpecker_data make up ``` ### 端口 8000（或 9000、9443）已被占用 ``` lsof -i :8000 lsof -i :9000 lsof -i :9443 ``` 如有需要，编辑 `compose.yaml` 更改主机端口映射。 ### SonarQube 无法启动 ``` # 检查日志 make logs sonarqube # 增加 vm.max_map_count（Elasticsearch 必需） sudo sysctl -w vm.max_map_count=262144 # 设为永久 echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf ``` ### GitHub webhook 失败 - 验证 `.env` 中的 `WOODPECKER_HOST` 是否与 webhook 回调 URL 匹配 - 检查 Woodpecker UI → Repositories → 您的仓库 → Settings 中的 webhook 状态 - 确保您的 Woodpecker 实例可以从 GitHub 访问 ### OTEL collector 无法访问（套件模式） ``` # 验证 OTEL endpoint 已设置 grep OTEL_ENDPOINT .env # 检查来自 Woodpecker agent container 的连通性 docker compose -f compose.yaml exec woodpecker-agent wget -qO- http://otel-collector:4318 ``` ### Pack 构建失败 ``` # 检查 Docker 访问权限 docker ps # 验证 builder image docker pull paketobuildpacks/builder:base # 在 Woodpecker CI 构建输出中检查 pack 日志 ``` ### Trivy 扫描缓慢 - 首次运行会下载 CVE 数据库（1-5 分钟） - 后续运行使用缓存数据（更快） - Trivy 镜像扫描仅在 main 分支推送时运行 ## 📚 附加资源 - [Woodpecker CI 文档](https://woodpecker-ci.org/docs/intro) - [Cloud Native Buildpacks](https://buildpacks.io/) - [SonarQube 文档](https://docs.sonarqube.org/) - [Trivy 文档](https://aquasecurity.github.io/trivy/) - [Gitleaks 文档](https://gitleaks.io/) - [DefectDojo 文档](https://docs.defectdojo.com/) - [uFawkesObs — 可观测性平面](https://github.com/paruff/uFawkesObs) ## 📄 许可证 Apache License 2.0 — 详情见 [LICENSE](LICENSE)。 ## 🙋 支持 - GitHub Issues: https://github.com/paruff/uFawkesPipe/issues - 文档: https://github.com/paruff/uFawkesPipe/wiki 专为平台工程师和开发者打造 ## uFawkes 技术栈生态系统 uFawkesPipe 是 [uFawkes](https://ufawkes.dev) 平台工程生态系统的一部分： | 技术栈 | 描述 | 链接 | | --------------- | ---------------------------------------------------- | ----------------------------------------------- | | **uFawkesRes** | 资源平面 — PostgreSQL、Valkey、Traefik、Authelia | [GitHub](https://github.com/paruff/uFawkesRes) | | **uFawkesPipe** | CI/CD — Woodpecker、Buildpacks、DevSecOps | [GitHub](https://github.com/paruff/uFawkesPipe) | | **uFawkesObs** | 可观测性 — Prometheus、Grafana、Loki、OTEL | [GitHub](https://github.com/paruff/uFawkesObs) | | **uFawkesDORA** | DORA 指标 — 仪表盘、VSM、交付性能 | [GitHub](https://github.com/paruff/uFawkesDORA) | | **uFawkesSec** | 安全 — 策略即代码、供应链、护栏 | [GitHub](https://github.com/paruff/uFawkesSec) | | **uFawkesDevX** | 开发者体验 — 黄金路径、IDP 模板 | [GitHub](https://github.com/paruff/uFawkesDevX) | | **uFawkesAI** | AI 智能体模板 — 黄金路径脚手架 | [GitHub](https://github.com/paruff/uFawkesAI) | **产品套件路线图**：[fawkes/ROADMAP.md](https://github.com/paruff/fawkes/blob/main/ROADMAP.md)

标签：DevOps平台, DevSecOps, Woodpecker CI, 上游代理, 测试用例, 用户代理, 自定义请求头, 请求拦截, 逆向工具