brazilco-platforms/secure-code-orchestrator

# Secure Scan CLI [](https://github.com/brazilco-platforms/secure-code-orchestrator/actions/workflows/ci.yml) [](https://codecov.io/gh/brazilco-platforms/secure-code-orchestrator) [](https://go.dev/) [](https://github.com/brazilco-platforms/secure-code-orchestrator/releases/latest) [](LICENSE) [](https://goreportcard.com/report/github.com/brazilco-platforms/secure-code-orchestrator) `secure-scan` 是一个使用 Go 编写的 CLI 工具，用于编排针对本地源代码的安全分析。在 **bundle 版本**（发布在 release 中）中，扫描器作为**原生二进制文件运行，无需 Docker**；在 **Docker 版本**（开发/源码）中，它们运行在容器中。该工具集成了按分析类型组织的 **17 个扫描器**： ### 静态分析 (SAST) - 静态代码 分析源代码**无需执行**的扫描器： | 扫描器 | 类别 | 分析内容 | |---------|-----------|---------------| | **Opengrep** | SAST | 代码中的漏洞 (OWASP Top 10) | | **Dependency-Check** | SCA | 依赖项中的 CVE | | **License Checker** | SCA | npm 包的许可证 | | **Trivy** | Container | Dockerfile 和镜像 | | **GitLeaks** | Secrets | Git 中暴露的凭证 | | **Checkov** | IaC | Kubernetes, Terraform, Dockerfile | | **Spectral** | API | OpenAPI/AsyncAPI 规范 | | **Syft** | SBOM | 组件清单 | | **Conftest** | Policy | OPA/Rego 策略 | ### 动态分析 (DAST) - 运行中的应用程序 **需要应用程序在运行中**的扫描器： | 扫描器 | 类别 | 分析内容 | |---------|-----------|---------------| | **OWASP ZAP** | DAST | 运行时的 Web 应用程序 | | **GraphQL Cop** | API | GraphQL endpoints | | **Nmap** | Network | 端口和服务 | | **Nuclei** | Network | Web 漏洞 | | **testssl** | Network | TLS/SSL 配置 | 汇总的输出结果以 JSON/Markdown 格式提供，可以通过 CLI 本身的子命令转换为附加报告。 ## 治理 此编排器是 **[ADR-0015] 的实现**（仓库 [`BrazilCo/governance`](https://github.com/BrazilCo/governance)）：停用 **GitHub Code Security (GHAS/CodeQL)**，并使用零成本的自主工具（Opengrep + Trivy + gitleaks）覆盖 SAST/SCA/secrets。此仓库的决策及其实现/相关的治理 ADR 位于 **[docs/adr/](docs/adr/)**。 ## 前置条件 - **Bundle 版本 (release)：** 无需任何外部 runtime — 内嵌原生扫描器，无需 Docker。 - **Docker 版本 (开发/源码)：** 需要运行 Docker 以使用容器化的扫描器。 - 对工作目录具有写入权限（用于生成 cache、报告和 artifacts）。 ## 安装说明 ### 方法 1：离线 Bundle（推荐 — 无需 Docker） Release **仅发布 bundle 版本**：每个平台一个自包含的包，包含 `secure-scan` + **9 个原生扫描器 + 内嵌的 SAST 规则** — 可 **100% 离线运行，无需 Docker**（仅在执行 `cache update` 时需要网络）。 **Linux (x64)：** ``` curl -LO https://github.com/brazilco-platforms/secure-code-orchestrator/releases/latest/download/secure-scan-bundle-linux-amd64.tar.gz tar -xzf secure-scan-bundle-linux-amd64.tar.gz sudo mv secure-scan-bundle-linux-amd64 /opt/secure-scan sudo ln -sf /opt/secure-scan/bin/secure-scan /usr/local/bin/secure-scan ``` **macOS (Intel / Apple Silicon)：** 替换为 `secure-scan-bundle-darwin-amd64.tar.gz` / `secure-scan-bundle-darwin-arm64.tar.gz`（流程相同）。 **Windows：** 从 [发布页面](https://github.com/brazilco-platforms/secure-code-orchestrator/releases/latest)下载 `secure-scan-bundle-windows-amd64.zip`，解压并将 `bin\` 添加到 `PATH`。 ### 方法 2：Go Install（仅编排器，Docker 版本） 仅安装**编排器**（不包含内嵌的扫描器）— 扫描器在 **Docker 容器**中运行（需要宿主机上安装 Docker）。用于开发用途： ``` go install github.com/brazilco-platforms/secure-code-orchestrator@latest ``` 二进制文件将安装在 `$GOPATH/bin/secure-scan`。 ### 方法 3：手动编译 克隆仓库并在本地编译： ``` # 克隆仓库 git clone https://github.com/brazilco-platforms/secure-code-orchestrator.git cd secure-scan-cli # 安装依赖 go mod download # Build 与安装 make install ``` ### 验证安装 ``` secure-scan --version # 预期输出：Secure Scan CLI vX.Y.Z ``` ### 故障排除 **Docker 不可用：** - 确保 Docker 正在运行：`docker ps` - 在 Linux 上，将您的用户添加到 docker 组：`sudo usermod -aG docker $USER` **权限被拒绝 (Linux/macOS)：** ``` chmod +x /usr/local/bin/secure-scan # 或者 sudo chmod +x /usr/local/bin/secure-scan ``` **找不到命令：** - 检查 `/usr/local/bin` 是否在您的 `$PATH` 中 - 或者使用完整路径：`/usr/local/bin/secure-scan --version` ## 快速入门 安装 CLI 后（参见[安装说明](#installation)），执行： ``` # 更新本地数据库 (NVD/Trivy) secure-scan cache update # 在当前仓库上运行所有 scanner # 注意：对于 security full，--output-dir 是必需的（无默认值） secure-scan security full . --output-dir /path/to/reports # 生成汇总的 Markdown 报告 secure-scan report security /path/to/reports ``` 对于动态分析 (DAST)，通过 `--target` 将扫描器指向目标。各个子命令 接受 `-o/--output-dir`（默认为 `security-reports`）： ``` # 扫描在本地运行的 app（使用 --network host 以访问宿主机的 localhost） secure-scan security zap --target http://localhost:3000 --network host -o ./reports # 扫描可路由的外部目标（默认/bridge 网络） secure-scan security zap --target https://app.example.com -o ./reports ``` ### 报告结构 使用 `--output-dir /reports` 时，报告的组织方式如下： ``` /reports/ ├── secure-scan/ # Relatório agregado │ ├── secure-scan-report.json │ └── secure-scan-report.md ├── opengrep/ # SAST ├── trivy/ # Container ├── gitleaks/ # Secrets ├── checkov/ # IaC └── ... ``` ## 主要命令 | 类别 | 命令 | 描述 | |--------------|------------------------------------------------------|-------------------------------------------------------------| | 安全 | `secure-scan security full [path] -o ` | 运行所有启用的扫描器（并行）。 | | | `secure-scan security sast [path] -o ` | 通过 Opengrep 进行 SAST。 | | | `secure-scan security deps [path] -o ` | 通过 Dependency-Check 进行 SCA。 | | | `secure-scan security licenses [path] -o ` | 通过 license-checker 生成许可证清单。 | | | `secure-scan security containers [path] -o ` | 通过 Trivy 进行 Container 安全检测。 | | | `secure-scan security secrets [path] -o ` | 通过 GitLeaks 进行 Secrets 检测。 | | | `secure-scan security iac [path] -o ` | 通过 Checkov 进行 IaC 安全检测。 | | | `secure-scan security zap --target [--network host] -o ` | 通过 OWASP ZAP 进行 DAST（需要应用正在运行；`--target` 必填）。 | | | `secure-scan security api [path] -o ` | 通过 Spectral 进行 API 安全检测 (OpenAPI/AsyncAPI)。 | | | `secure-scan security network nmap --target -o ` | 通过 Nmap 进行网络安全检测（`--target` 必填）。 | | 报告 | `secure-scan report security -i -o ` | 根据汇总的 JSON 生成 Markdown 报告。 | | | `secure-scan report quality -o ` | 生成质量检查清单（基于内部启发式算法）。 | | | `secure-scan report markdown -i -o ` | 将任何聚合的 artifact 转换为 Markdown。 | | 清理 | `secure-scan clean reports --older-than 30d` | 删除指定目录中的旧报告。 | | Cache | `secure-scan cache update [path]` | 更新扫描器的本地 cache。 | | | `secure-scan cache status [path]` / `cache clean` | 检查或清理 cache。 | | 性能 | `secure-scan perf run --vus 10 --duration 30s` | 使用虚拟用户执行 HTTP 负载测试。 | | 环境 | `secure-scan env up|down|status [path]` | 启动/关闭内嵌的监控环境。 | | 服务 | `secure-scan services scan [path]` | 编目服务：`services/*`（monorepo）或 workspace 本身（如果是单应用且存在项目标记）。检测技术栈、endpoints (Express/NestJS/Go) 以及依赖项。 | | 测试 | `secure-scan test unit|integration [path]` | 对检测到的服务执行 `go test ./...`。 | | | `secure-scan test mutation [path]` | 优化的变异测试：Stryker (JS/TS，自定义 Docker) 或 Gremlins (Go)。自动清理报告。 | | 架构 | `secure-scan analyze deps [path]` | 运行 dependency-cruiser 并指出架构违规。 | | 文档 | `secure-scan docs generate [path]` | 在 `tool-docs/` 生成技术文档集：索引、服务目录、API 和依赖项清单、安全态势（如果进行了扫描）以及用于门户/CI 的 `index.json`。 | 所有文件夹和路径均相对于目标目录（`[path]`），该目录默认为当前目录。 ## 仓库结构 ``` secure-scan-cli/ ├── cmd/ # Comandos Cobra (CLI) ├── internal/ │ ├── domain/ # Contratos e modelos compartilhados │ ├── platform/ # Infraestrutura cross-cutting │ │ ├── runner/ # Abstração de execução (Docker/Local) │ │ ├── docker/ # Cliente Docker │ │ ├── logging/ # Logging estruturado │ │ └── config/ # Configurações │ ├── scanners/ # Scanners por domínio │ │ ├── security/ # SAST, SCA, Container, Secrets, IaC, DAST, API, Network │ │ ├── test/ # Mutation Testing │ │ ├── compliance/ # SBOM, Policy, Benchmark (futuro) │ │ └── supply-chain/ # Sign, Verify (futuro) │ ├── orchestration/ # Full scan, service scan, cache │ ├── handler/ # Handlers de comandos │ └── report/ # Geradores de relatórios ├── services/ # Serviços de exemplo ├── docs/ # Documentação └── docker/ # Dockerfiles customizados ``` ## 文档 完整文档位于 [docs/](docs)（目录索引见 [docs/README.md](docs/README.md)）： - **[快速入门](docs/getting-started.md)** — 安装 + 首次扫描 + 核心命令 - **[CLI 参考](docs/wiki/cli-reference.md)** — 所有命令 - **[扫描器](docs/wiki/scanners.md)** — 扫描器、前置条件、Docker 镜像、ZAP - **[离线 Bundle](docs/offline-bundle.md)** — air-gap 版本：平台、rulesets、mirror - **[操作](docs/guides/operations.md)** — cache/CVE 更新 + 报告 - **[本地 DAST](docs/guides/DAST_LOCAL.md)** — 针对运行中应用的 DAST - **[架构](docs/wiki/architecture.md)** · **[测试](docs/wiki/testing.md)** · **[路线图](docs/roadmap.md)** ## 贡献 - **Trunk-based 工作流：** `main` 是唯一长期存在的分支。工作在 功能分支（`feat/…`, `fix/…`, `chore/…`）上进行，并通过 PR 合并回 `main` — 没有集成分支。Release 通过 `v*` 标签从 `main` 截取。 - 使用 Conventional Commits (`feat:`, `fix:`, `docs:` 等)。 - 在提交更改之前，请执行 `go fmt ./...` 和 `go test ./...`。 - 每当添加新的命令或工作流时，请及时更新 `docs/` 中的文档。

标签：CTI, DevSecOps, EVTX分析, FTP漏洞扫描, Go, Ruby工具, 上游代理, 安全编排, 日志审计, 请求拦截, 错误基检测, 静态代码分析