sudoNaji/devsec-vault-cli

# DevSec Vault ## 为什么选择 DevSec Vault？ 密钥泄露是导致云泄露的头号原因。DevSec Vault 实现了一个**纵深防御**流水线，可在开发生命周期的每个阶段捕获密钥——在提交之前，在推送之前，以及追溯检查仓库历史。 ## 检测层 ``` Developer workstation │ ├── [Layer 1] pre-commit hook ──── devsec-vault staged │ └── Blocks commit if staged diff contains a secret │ ├── [Layer 2] detect-secrets ──── baseline-driven allowlist │ └── Catches additional patterns not in our regex set │ ▼ Git push │ ├── [Layer 3] GitHub Push Protection │ └── Server-side block for 200+ known token types │ ├── [Layer 4] GitHub Secret Scanning │ └── Full-history scan across all branches │ ▼ Pull Request / CI (GitHub Actions) │ ├── [Layer 5] devsec-vault scan ── file + directory scan, SARIF upload ├── [Layer 6] devsec-vault history ─ full commit history scan ├── [Layer 7] CodeQL ── static analysis (security-and-quality) └── [Layer 8] pip-audit ── dependency CVE check │ ▼ Release │ └── [Layer 9] Artifact Attestation + OpenSSF Scorecard ``` ## 快速开始 ``` # Clone git clone https://github.com/your-org/devsec-vault cd devsec-vault # Install pip install click rich # 安装 pre-commit hooks pip install pre-commit pre-commit install # 运行扫描 python src/cli.py scan src/ # 扫描 git 历史 python src/cli.py history --max-commits 200 # 扫描暂存更改 python src/cli.py staged ``` ## CLI 参考 ### `scan` — 扫描文件或目录 ``` python src/cli.py scan [OPTIONS] TARGETS... Options: --format [text|json|sarif] Output format (default: text) --output PATH Write report to file --baseline PATH Allowlist baseline file --min-severity LEVEL CRITICAL|HIGH|MEDIUM|LOW (default: LOW) --fail-on [any|high|critical|never] Exit-1 threshold (default: any) --no-entropy Disable entropy heuristic --max-file-size KB Skip files larger than N KB (default: 500) ``` ### `staged` — Pre-commit 门禁 ``` python src/cli.py staged [--repo PATH] [--format text|json|sarif] ``` 如果在暂存区的 diff 中发现密钥，将返回退出代码 1 并阻止提交。 ### `history` — 完整的 git 历史扫描 ``` python src/cli.py history [--max-commits 500] [--format sarif] [--output history.sarif] ``` 检查从所有分支可达的每一次提交。 ### `baseline` — 允许列表管理 ``` # 基于当前发现生成 baseline（全部标记为 accepted） python src/cli.py baseline generate src/ --output .devsec-baseline.json # 显示相对于 baseline 的新内容 (regressions) python src/cli.py baseline diff src/ # 查看 baseline 内容 python src/cli.py baseline show ``` ### `report` — 重新渲染已保存的报告 ``` python src/cli.py report report.json --format sarif --output results.sarif python src/cli.py report report.json --format metrics ``` ### `info` — 显示已加载的检测规则 ``` python src/cli.py info ``` ## 检测覆盖范围 | 规则 | 严重级别 | 捕获内容 | |------|----------|-----------------| | `AWS_ACCESS_KEY_ID` | CRITICAL | `AKIA...` AWS 访问密钥 | | `AWS_SECRET_KEY` | CRITICAL | AWS 秘密访问密钥 | | `GITHUB_PERSONAL_TOKEN` | CRITICAL | `ghp_...` PATs | | `GITHUB_OAUTH_TOKEN` | HIGH | `gho_...` OAuth token | | `GITHUB_APP_TOKEN` | HIGH | `ghs_/ghu_` 应用 token | | `STRIPE_SECRET_KEY` | CRITICAL | `sk_live_/sk_test_` | | `RSA_PRIVATE_KEY` | CRITICAL | PEM 私钥头 | | `OPENSSH_PRIVATE_KEY` | CRITICAL | OpenSSH 私钥 | | `DB_CONN_STRING` | CRITICAL | `postgres://user:pass@host/db` | | `GCP_API_KEY` | HIGH | `AIza...` Google API 密钥 | | `AZURE_CLIENT_SECRET` | CRITICAL | Azure 客户端密钥 | | `SLACK_TOKEN` | HIGH | `xoxb-/xoxp-` token | | `JWT_TOKEN` | HIGH | `eyJ...` JWTs | | `HIGH_ENTROPY` | HIGH | 香农熵 ≥ 4.2 启发式判断 | | … +10 更多 | MEDIUM–HIGH | Stripe pub, Discord, NPM, PyPI… | ## 分支保护策略 `main` 分支受以下策略保护： - ✅ 必须提交 Pull Request（1 个批准的审查） - ✅ 必需的状态检查：`test`, `secret-scan`, `codeql` - ✅ 签名提交（GPG/SSH）— 未签名的提交将被拒绝 - ✅ 禁止强制推送 · 禁止删除 · 保持线性历史 - ✅ 包含管理员 有关完整的规则集 JSON，请参阅 [`policies/branch-protection.md`](policies/branch-protection.md)。 ## 攻击演示 ### 被阻止的提交（本地） ``` $ echo 'AWS_KEY=AKIAIOSFODNN7EXAMPLE' >> src/config.py $ git add src/config.py && git commit -m "test" DevSec Vault — staged secret scan.......................Failed - hook id: devsec-vault-staged - exit code: 1 Severity Rule Line Masked Value CRITICAL AWS_ACCESS_KEY_ID 1 AKIA****MPLE ✗ Secret(s) detected in staged changes — commit blocked. ``` ### 被阻止的推送（GitHub Push Protection） ``` remote: error: GH013: Repository rule violations found for refs/heads/main. remote: - Push cannot contain secrets remote: —— Amazon AWS Access Key ID —— remote: locations: src/config.py:1 remote: To https://github.com/your-org/devsec-vault ! [remote rejected] feature/add-config -> main (push declined due to repository rule violations) ``` ## 威胁模型 有关涵盖资产、威胁行为者和缓解措施的完整威胁模型，请参阅 [`policies/threat-model.md`](policies/threat-model.md)。 ## 指标 跟踪一段时间内的安全态势： ``` python src/cli.py report report.json --format metrics ``` ``` { "total_findings": 0, "by_source": {}, "by_severity": {}, "clean_targets": 42, "targets_scanned": 42 } ``` | 指标 | 目标 | |--------|--------| | 本地捕获的密钥 | 全部 | | 被 Push Protection 阻止的密钥 | 0 个到达远程 | | 未修复的依赖 CVE | 0 个 CRITICAL，<5 个 HIGH | | 未签名的提交 | `main` 上为 0 | | 待处理的 CodeQL 警报 | 0 个 CRITICAL/HIGH | ## 供应链安全 - 每次发布都会生成**制品证明**（通过 SLSA 实现构建来源证明） - 仓库中的 **OpenSSF Scorecard** 徽章 — 衡量分支保护、签名发布和 token 权限 - 任何云部署均使用 **OIDC** — 不在 GitHub Secrets 中存储长期有效的凭证 ## 运行测试 ``` pytest tests/ -v ``` ## 许可证 MIT

标签：CI/CD安全扫描, CodeQL, DevSecOps, GitHub Actions, JSONLines, LNA, OpenSSF, Python, SARIF, SAST, StruQ, 上游代理, 依赖项安全检查, 安全助手, 安全评估工具, 密钥泄露防护, 开发安全, 提示注入防御, 无后门, 机器学习安全, 机密信息检测, 源代码安全, 盲注攻击, 策略即代码, 聊天机器人安全, 自动笔记, 逆向工具, 错误基检测, 零信任, 静态代码分析