isaaaac-2/secrets-audit-cli

# secrets-audit-cli 一款安全优先的 CLI 工具，用于扫描代码库中的硬编码 secrets、API keys、private keys 以及配置错误的 environment variables。扫描结果会记录在本地 SQLite 数据库中，包含严重性分级、修复状态和风险接受说明，为团队提供从检测到解决的清晰审计追踪。 本项目作为一个 DevSecOps 作品集项目构建，旨在演示安全开发实践、CI/CD pipeline 门控、容器安全扫描和基础设施即代码（infrastructure-as-code）加固。 ## 我在解决什么问题？ Secrets 不断泄露到代码库中。大多数团队是在部署后、审计期间，甚至更糟的违规事件发生后才发现它们。现有工具要么只标记问题而不跟踪修复情况，要么需要昂贵的 SaaS 平台。本项目填补了这一空白，提供了一个轻量级、自包含的扫描器，可直接作为安全门禁集成到 CI/CD pipeline 中。 ## 为什么这很重要？ 只有将安全扫描融入开发人员已经在使用的工作流中，它才能发挥作用。独立的扫描器往往会被忽视；而一个能够阻止不安全推送、并全程跟踪扫描结果直至解决的 pipeline 门禁，才能真正改变行为。本项目证明了：安全可以是自动化的、可审计的、对开发人员友好的，且不会增加阻力。 ## 功能 - 递归扫描目录以查找多种类型的 secret（AWS keys、通用 API keys、private keys、连接字符串、硬编码密码、env var 泄露） - 可配置的基于 regex 的检测，带有严重性级别（Critical、High、Medium、Low） - 跟踪修复生命周期：open → in-progress → resolved / risk-accepted - 存储审查人员备注，并在写入数据库前对检测到的值进行掩码处理 - 按严重性和状态生成摘要报告 - 通过 GitHub Actions 实现的自门控 CI/CD pipeline，可阻止包含未解决 critical 发现的推送 - 使用 Docker 进行容器化，并使用 Trivy 作为构建门禁进行扫描 - 每次推送时均使用 Semgrep（p/security-audit 规则集）进行静态分析 ## 技术栈 - 后端：FastAPI - CLI：Typer - 数据库：SQLite（带有 CHECK 约束和自动时间戳） - 容器化：Docker - CI/CD：GitHub Actions（自门控安全 pipeline） - 安全工具：Trivy（容器镜像扫描），Semgrep（SAST） ## 快速开始 1. 克隆仓库 ``` git clone https://github.com/isaaaac-2/secrets-audit-cli.git cd secrets-audit-cli ``` 2. 创建并激活虚拟环境 ``` python -m venv secret-cli # Linux / macOS source secret-cli/bin/activate # Windows (PowerShell) secret-cli\Scripts\Activate.ps1 ``` 3. 安装依赖项 ``` pip install -r requirements.txt ``` ## 使用说明 扫描目录以查找 secrets： ``` python -m app.cli scan ./your-project ``` 列出所有发现： ``` python -m app.cli list ``` 按状态过滤列出发现： ``` python -m app.cli list --status open ``` 附带修复说明解决一个发现： ``` python -m app.cli resolve --notes "Rotated API key via AWS Secrets Manager" ``` 生成摘要报告： ``` python -m app.cli report ``` ## 检测模式 模式定义在 `app/secret-patterns.json` 中，并由扫描器预编译。每个模式都包含一个严重性级别，并且无需修改代码即可进行扩展： - AWS Access Keys：`AKIA[0-9A-Z]{16}` (Critical) - 通用 API Keys：`api[_-]?key|apikey` (High) - Private Keys：`-----BEGIN.*PRIVATE KEY-----` (Critical) - 连接字符串：`mongodb://|postgres://|mysql://` (High) - Environment Variables：`os\.environ\[|os\.getenv\(` (Medium) - 硬编码密码：`password\s*=\s*['\"]` (High) 在 `app/secret-patterns.json` 中添加或修改模式。无需更改代码。 ## 架构 ``` User runs CLI command │ ▼ ┌──────────────────────────────────┐ │ app/cli.py │ │ Typer Commands │ │ scan | list | resolve | report │ │ │ └──────────────┬───────────────────┘ │ ┌────────────┴────────────┐ ▼ ▼ ┌───────────────────────┐ ┌───────────────────────┐ │ app/scanner.py │ │ app/models.py │ │ Detection Engine │ │ Database Layer │ │ │ │ │ │ • Loads regex patterns│ │ • SQLite schema │ │ • Line-by-line scan │ │ • _mask_secret() │ │ • Returns raw findings│ │ • CRUD operations │ └───────────┬───────────┘ │ • Summary reports │ │ └───────────┬───────────┘ │ │ ▼ ▼ ┌───────────────────────┐ ┌───────────────────────┐ │ secret-patterns.json │ │ SQLite DB │ │ Regex + Severity │ │ secret_findings │ └───────────────────────┘ └───────────────────────┘ Security Controls: • Plaintext secrets never stored or displayed • CHECK constraints on severity and status • Auto-updating timestamp trigger • .gitignore excludes *.db, .env, venv ``` ## CI/CD Pipeline GitHub Actions 工作流（`.github/workflows/ci.yml`）在每次推送到 main 分支时运行三个安全门控： 1. Secret 扫描器针对测试 fixtures 运行，以验证检测逻辑 2. 构建 Docker 镜像并使用 Trivy 扫描容器漏洞 3. Semgrep 使用 p/security-audit 规则集执行静态分析 任何 HIGH 或 CRITICAL 发现都会导致构建失败。没有可用补丁的未修复 OS 级漏洞及其理由都会记录在 `.trivyignore` 中。这反映了生产级 DevSecOps 团队处理漏洞管理的方式：尽可能修复，无法修复的则记录在案并予以接受。 ## 安全设计决策 - 掩码处理发生在数据库层（models.py 中的 `_mask_secret()`），以确保明文凭据永远不会到达持久化存储，无论扫描器传入什么内容 - `test/` 目录有意包含用于验证的虚拟 secrets（例如 `AKIAIOSFODNN7EXAMPLE`）。这些显然是伪造的，可以安全提交 - `.gitignore` 排除了运行时产生的文件（`*.db`、`.env`、虚拟环境目录），以防止意外的凭据或状态泄露 - Trivy 忽略文件使用 CVE ID 和理由记录了已接受的风险，遵循行业标准的漏洞管理实践 - Starlette DoS CVE（CVE-2025-62727、CVE-2026-48818、CVE-2026-54283）被接受，因为这是一个没有运行 HTTP 服务器的 CLI 工具；这些漏洞需要活动的 web endpoint 才能被利用 ## 已知权衡 - 通过 .trivyignore 接受的 Starlette 漏洞：本项目是一个 CLI 扫描器，而不是 web 服务器。这三个 Starlette CVE 需要活动的 HTTP endpoint 才能被利用，在此不适用。已记录而非全局抑制。 - Debian 基础镜像中的 OS 级漏洞：perl、ncurses 和 util-linux 中的几个 HIGH/CRITICAL CVE 目前没有可用的补丁。这些是上游问题，并非由本项目引入。在 .trivyignore 中使用 ignore-unfixed 标志进行跟踪，以便 pipeline 仅在可操作的发现上失败。 - 提交到仓库的测试 fixtures：test/ 文件夹包含用于验证的有意设置的虚拟 secrets。生产环境的部署将使用挂载卷或独立的测试基础设施来代替。 - 使用 SQLite 进行存储：选择它是为了便携性和零配置设置。生产系统将使用 PostgreSQL 或类似数据库以实现并发访问和可扩展性。 ## 项目结构 ``` secrets-audit-cli/ ├── app/ │ ├── __init__.py │ ├── main.py │ ├── scanner.py │ ├── models.py │ ├── cli.py │ └── secret-patterns.json ├── test/ │ ├── sample.py │ └── test_api.py ├── .github/workflows/ci.yml ├── Dockerfile ├── docker-compose.yml ├── .trivyignore ├── requirements.txt ├── .gitignore └── README.md ``` ## 许可证 Apache 2.0

标签：DevSecOps, GPT, StruQ, 上游代理, 安全助手, 漏洞管理, 请求拦截, 逆向工具