geraldoschuetze/security-kit-agent
GitHub: geraldoschuetze/security-kit-agent
将 Claude Code 和 Gemini CLI 转变为 Snyk 风格安全 agent 的开源工具包，结合规则扫描与 LLM 语义推理实现全链路安全审计。
Stars: 0 | Forks: 0
# Security Kit Agent 🛡️ (OSS，对标 Snyk) — Claude + Gemini
**English** · [Português](README.pt-BR.md)
仅使用**开源工具**将 **Claude Code** 和 **Gemini CLI** 转变为 Snyk 风格的安全 agent，并在你**提交、构建和测试的所有内容**中强制执行安全检查 —— 包括本地（全局安装）和 **GitHub CI** 环境。
它的与众不同之处在于：它结合了**两种互补的**分析体系。
**基于签名/规则**的工具（覆盖广、确定性强：CVE、机密信息、IaC、已知的不安全模式）**+** **基于推理的语义审查**（规则的盲点：损坏的授权、IDOR、可利用的业务逻辑、跨文件的危险数据流）。没有推理的规则会漏掉逻辑缺陷；没有规则的推理会漏掉 CVE。此工具包同时运行两者，并将结果整合为一份单一报告。
| 层级 | Snyk 对标物 | 工具 / 方法 | 许可证 |
|---|---|---|---|
| `sca-scanner` | Open Source + Container + IaC + License | **Trivy** + **OSV-Scanner** | Apache-2.0 |
| `sast-scanner` | Snyk Code (基于规则的 SAST) | **Semgrep CE** | LGPL-2.1 |
| `secrets-scanner` | Secret 检测 | **Gitleaks** | MIT |
| `semantic-reviewer` | (超越 Snyk：authz/IDOR/logic) | **LLM 推理** | — |
| `dast-scanner` | (原生 Snyk 未涵盖) | **OWASP ZAP** | Apache-2.0 |
| 全局 git hook | 提交时阻断 | Gitleaks | — |
| 可复用 CI | PR 门禁 | Trivy+OSV+Semgrep+Gitleaks | — |
## 它在何处进行阻断
提交时的 hook 是一个快速反馈环，而不是绝对的保障。当未安装 `gitleaks`、当仓库设置了自身的本地 `core.hooksPath`（如 Husky v9 等），或者使用 `git commit --no-verify` 时，它将被跳过 —— 没有任何 pre-commit hook 能够阻止最后一种情况。**CI 才是坚守底线的门禁**，这就是为什么该工具包两者皆提供的原因。
## 安装说明（Claude + Gemini，只需一条命令）
```
git clone git@github.com:geraldoschuetze/security-kit-agent.git
cd security-kit-agent
bash bootstrap.sh # Claude + Gemini + global git hook + tools
```
Flags：`--no-gemini`（仅限 Claude） · `--no-tools`（跳过 trivy/osv-scanner/semgrep/gitleaks）。
`bootstrap.sh` 是幂等的，它会执行以下操作：
1. 将安全 skills、`agents` 和 `scripts` 复制到 `~/.claude/` 中。
2. 将这些 skills 复制到 `~/.gemini/skills` 中（它们供两者共用）。
3. 从**经过脱敏处理的模板**中安装 `settings.json` 文件（仅当它们尚不存在时 —— 绝不会覆盖你的文件）。你需要自行填写 `__SET_...__` 占位符。
4. 启用**全局提交时 git hook**（`core.hooksPath`），它将拦截机器上**任何**仓库中包含 secret 的提交。
5. 安装 **trivy / osv-scanner / semgrep / gitleaks**（固定版本 + 校验和验证）。
## 如何触发它（逐步指南）
Skills 和 agents 是**全局性的** —— 它们在任何项目中都能运行，无需按仓库单独安装。
```
cd ~/path/to/project
claude # or: gemini
```
在新的对话中，发起全面审计：
```
/security-scan
```
或者使用自然语言：*"运行一次安全审计 (run a security audit)"*，*"在部署前检查漏洞 (check for vulnerabilities before the deploy)"*。
**模式与目标设定：**
| 目标 | 输入内容 |
|---|---|
| 完整审计（整个仓库） | `/security-scan` |
| PR 模式（仅对比 `main` 的 diff） | `/security-scan diff` |
| 单个子目录 | `/security-scan ` |
| 仅依赖项/CVE | *"在此项目上运行 `sca-scanner`"* |
| 仅机密信息（工作区 + 历史） | *"运行 `secrets-scanner`"* |
| 仅逻辑/authz（推理） | *"运行 `semantic-reviewer`"* |
| 包含 DAST（应用运行时） | *"/security-scan including DAST at http://localhost:3000"* |
| 遗留代码库（仅扫描新增部分） | *"scan with baseline at commit ``"* |
**输出：** 根目录下的 `security-report.md` 以及 `.security/history/` 下带有版本记录的历史记录（带时间戳的报告 + `security-metrics-*.json`），并附带针对前一次扫描的**判定结论** 🔴/🟡/🟢 及其**趋势**。
## Agent 详细说明
每一个维度都被委派给一个在**隔离上下文**中运行的专业子 agent（扫描产生的噪音不会污染对话环境），它们具有 **只读 + Bash** 权限（绝不编辑文件），并且**仅返回结构化的摘要**（绝不返回原始 JSON）。
### 🧩 `sca-scanner` — 依赖项、IaC、容器、许可证 (Trivy + OSV-Scanner)
依赖项中的 CVE（附带修复版本）、IaC 配置错误（Dockerfile、Terraform、Kubernetes、CloudFormation、Helm）、容器镜像漏洞以及有问题的许可证。相当于 Snyk Open Source + Container + IaC + License。
它运行**两个互补的漏洞数据库**，并将结果核对调和为一个统一的列表：
| | Trivy | OSV-Scanner |
|---|---|---|
| 数据源 | NVD + GHSA + 发行版安全公告 | OSV.dev (GHSA, PySec, RustSec, Go…) |
| 索引依据 | **CVE** | **公告 ID** |
| 盲区 | **未分配 CVE** 的安全公告 | 仅限应用依赖项（无 IaC/镜像/许可证） |
| Lockfiles | 广泛覆盖，**不支持 `bun.lock`** | 广泛覆盖，**包含 `bun.lock`** |
报告会将每个发现标记为 `both` · `OSV only` · `Trivy only`。`OSV only` 这一分类正是引入第二个数据库的合理性所在：它们属于商业工具通常以专有 ID 报告、而仅靠 Trivy 永远无法发现的同一类问题。
### 🔎 `sast-scanner` — 通过规则审查你的自有代码 (Semgrep)
SQL 注入（包含 Prisma `$queryRawUnsafe`）、XSS、命令注入、路径遍历、SSRF、不安全的反序列化、弱加密以及通过 `NEXT_PUBLIC_*` 导致的泄露。**固定版本**的规则集 + `--metrics=off`。映射 CWE/OWASP 并通过阅读周边代码进行分诊处理。相当于 Snyk Code。
### 🧠 `semantic-reviewer` — 基于推理的逻辑与授权审查 *(规则无法捕捉的内容)*
损坏的授权 / **IDOR**、可利用的业务逻辑（负数价格、重放攻击、TOCTOU、状态机绕过）、**跨文件**的危险数据流（Semgrep CE 不跟踪此类问题）、缺失的验证/authz、PII 暴露。它不运行任何工具 —— 它对代码进行**推理**，追踪 source→sink，并在将某项问题归类为真实发现之前，要求必须具备具体的利用场景。这正是基于签名的工具在结构上无法覆盖的部分。
### 🔑 `secrets-scanner` — 机密信息与凭证 (Gitleaks)
在**工作区**和**整个 git 历史**中查找 API keys、tokens、密码和私钥。**绝不转录其具体值** —— 仅报告类型、file:line 以及 commit。发现真正的 secret = **CRITICAL** + **在提供商处轮换凭证**（重写历史记录无法撤销已有的 clones/forks）。
### 🌐 `dast-scanner` — 运行中的应用程序 (OWASP ZAP) — *按需运行*
缺失的 headers（CSP、HSTS）、没有 `Secure`/`HttpOnly`/`SameSite` 的 cookies、反射型 XSS、暴露的堆栈跟踪、过于宽松的 CORS。通过 Docker 对**你**提供的 URL 运行 ZAP baseline 扫描。**绝不自动运行**（因为它会产生真实的流量）。
## 执行顺序
**交叉验证**是结合这两大体系的价值所在：如果一项 SAST 发现经语义审查确认是可利用的，其严重性将被**提升**；如果语义审查表明该发现已被缓解，则会被**降级**并移至误报附录中，同时附带理由。
## GitHub — 可复用 CI
- `.github/workflows/security-reusable.yml` (`workflow_call`) — Trivy + **OSV-Scanner** + Gitleaks + Semgrep + **CycloneDX SBOM**，**在遇到 CRITICAL 时失败**。官方 Docker 镜像按版本固定，第一方 actions **按 SHA 固定**（`trivy-action` 在 2026 年 3 月遭受过供应链攻击 —— 这就是我们不用它的原因）。OSV **默认为信息提示**；传入 `osv_gate: true` 可使其同样阻断构建。
- `.github/workflows/security.yml` — 在 push/PR 时自动扫描 + **每周定期重新扫描** (cron) + `workflow_dispatch`。
在另一个仓库中，只需约 10 行代码即可引用它：
```
jobs:
security:
uses: geraldoschuetze/security-kit-agent/.github/workflows/security-reusable.yml@v1
with: { fail_on_severity: CRITICAL, osv_gate: false }
```
## 仓库结构
```
security-kit-agent/
├── bootstrap.sh # multi-machine installer (Claude + Gemini)
├── claude/
│ ├── agents/ # sca · sast · secrets · dast · semantic-reviewer
│ ├── skills/ # security-scan · security-audit · api-/web-security-testing
│ ├── scripts/ # install-tools.sh · gitleaks-gate.sh
│ └── settings.template.json # minimal template: only the PreToolUse hook (gitleaks)
├── gemini/
│ └── settings.template.json # sanitized template (Gemini CLI)
├── git-hooks/
│ └── pre-commit # global commit-time git hook (Gitleaks)
└── .github/workflows/ # security.yml + security-reusable.yml
```
## 范围与规则
- **仅限安全**：不涉及代码风格/重构/性能。
- **机密信息**：报告类型/文件/行号/提交 —— **绝不包含具体值**（已脱敏）。
- 子 agent 隔离运行，仅返回摘要（不返回原始 JSON）。
- 历史 record 中存在 secret = **轮换凭证**（重写历史无法撤销已有的 clones）。
- `settings.json` 模板已**脱敏**（包含 `__SET_...__` 占位符）—— 仓库中不存在任何 secret。
## 注意事项
- 首次扫描会下载数据库 和规则集 —— 它需要互联网连接。
- **陈旧的 Trivy DB 意味着最近的 CVE 会被漏报。** `sca-scanner` 会检查 `~/.cache/trivy/db/metadata.json` 中的 `UpdatedAt` 字段，并将该日期记录在报告中。
- 没有任何 lockfile 扫描器能看到由旧版本安装遗留在 `node_modules` 中的过期副本。如果与商业扫描器的结果不一致？请检查已安装的依赖树。
- Semgrep CE 逐个文件进行分析（无跨文件污点分析）—— `sast-scanner` 会阅读周边代码，而 `semantic-reviewer` 则负责覆盖跨文件的数据流。
- **TruffleHog**（用于验证 secret 是否仍然有效）基于 AGPL 协议：请仅在 CI 环境的容器中使用它。
标签：CI/CD 集成, Java RMI, StruQ, 代码审查, 动态应用安全测试(DAST), 大语言模型(LLM), 安全工具链, 应用安全, 请求拦截, 软件成分分析(SCA), 静态应用安全测试(SAST)