momenbasel/vulnhawk
GitHub: momenbasel/vulnhawk
VulnHawk 是一款利用 AI 上下文推理能力，专注于检测业务逻辑缺陷、权限绕过及 IDOR 等传统 SAST 工具遗漏漏洞的静态代码扫描器。
Stars: 39 | Forks: 5
AI 驱动的代码安全扫描器，能够发现 Semgrep 和 CodeQL 遗漏的漏洞。
快速开始 •
GitHub Action •
对比 •
支持的语言 •
常见问题
## 问题所在
传统的 SAST 工具依赖于模式匹配和 AST 规则。它们擅长捕捉已知的漏洞模式，但根本上**无法推理意图**。
如果你的 API 有 20 个端点，其中 19 个在对资源执行操作前验证了授权，Semgrep 无法标记出那个没有验证的端点——因为没有可以匹配的模式。漏洞在于*缺失*某种模式。
## 解决方案
VulnHawk 利用 AI 分析代码，对于它检查的每一段代码，它都会包含代码库中其他地方的**相关代码**作为上下文。这个增强步骤让 AI 能够比较相似组件如何处理安全性——并找出那个处理不一致的组件。
## 快速开始
```
pip install vulnhawk
```
选择后端：
```
# Claude Code CLI - 订阅者免费（推荐）
vulnhawk scan ./src -b claude-code
# Codex CLI - ChatGPT Pro/Plus 订阅者免费
vulnhawk scan ./src -b codex
# Claude API
export ANTHROPIC_API_KEY=sk-ant-...
vulnhawk scan ./src
# OpenAI API
vulnhawk scan ./src -b openai -m gpt-4o
# Ollama - 免费、本地、完全私有
vulnhawk scan ./src -b ollama -m llama3.1
```
无需配置文件。无需编写规则。无需构建数据库。
## VulnHawk 与其他 SAST 工具的对比
| 功能 | VulnHawk | Semgrep | CodeQL | Snyk Code | Checkmarx | SonarQube |
|:---|:---:|:---:|:---:|:---:|:---:|:---:|
| 检测方法 | AI 推理 | AST 模式 | QL 数据流 | ML + 规则 | 模式 + 流 | 模式 |
| 业务逻辑缺陷 | **是** | 否 | 有限 | 有限 | 有限 | 否 |
| 跨文件上下文 | 自动 | 自定义规则 | 自定义查询 | 部分 | 付费版 | 有限 |
| 设置复杂度 | 零配置 | 规则配置 | 数据库构建 + QL | 配置文件 | 复杂 | 服务器设置 |
| 需要自定义规则 | 否 | 是 (YAML) | 是 (QL) | 部分 | 是 | 是 |
| 上下文感知修复 | **是** | 通用 | 通用 | 通用 | 通用 | 通用 |
| 本地 / 私有模式 | Ollama | 是 | 是 | 否 | 否 | 自托管 |
| CI/CD 集成 | 单行 Action | Action | Action | Action | 插件 | 插件 |
| SARIF 输入（链式工具） | **是** | 否 | 否 | 否 | 否 | 否 |
| 定价 | 免费\* | 免费 / 付费 | 免费 / 付费 | 免费 / $$$ | $$$$$ | 免费 / $$$ |
\*配合 Claude Code、Codex CLI 或 Ollama 使用免费。API 后端每次扫描费用约为 $0.50-$2.00。
### VulnHawk 能发现其他工具无法发现的问题
| 漏洞类别 | 基于规则的工具为何会漏掉它 |
|:---|:---|
| N 个端点中有一个缺少授权 | 没有可匹配的模式——漏洞在于*缺失*检查 |
| IDOR / BOLA | 需要理解 JWT 中的用户 ID 应与 URL 中的 ID 匹配 |
| 支付金额篡改 | 业务逻辑——不应信任来自客户端的金额字段 |
| 输入验证不一致 | 5 个处理器进行了清理，第 6 个没有——需要跨文件比较 |
| 存储输入的误用 | 输入被安全保存，但在 3 个文件外被 `eval()` 或直接作为原始 SQL 使用 |
| 状态更新中的竞态条件 | 并发修改余额且未加锁 |
### 推荐的工具组合
VulnHawk 被设计为一个**互补层**，而非替代品：
| 层级 | 工具 | 目的 |
|:---|:---|:---|
| 1 | **Semgrep** | 对已知的不良模式进行快速、确定性的把关 |
| 2 | **CodeQL** | 跨越复杂调用链进行深度污点追踪 |
| 3 | **VulnHawk** | 业务逻辑、授权缺口、IDOR 以及规则无法表达的不一致问题 |
## 使用方法
### 扫描模式
```
vulnhawk scan ./src # Full scan (default)
vulnhawk scan ./src --mode auth # Auth bypass, missing checks, session flaws
vulnhawk scan ./src --mode injection # SQLi, command injection, SSTI, XSS
vulnhawk scan ./src --mode secrets # Hardcoded keys, tokens, passwords
vulnhawk scan ./src --mode config # Debug mode, permissive CORS, insecure cookies
vulnhawk scan ./src --mode crypto # Weak hashing, hardcoded keys, bad RNG
```
### 输出格式
```
vulnhawk scan ./src -o json -f results.json # JSON
vulnhawk scan ./src -o sarif -f results.sarif # SARIF (GitHub Code Scanning)
vulnhawk scan ./src -o markdown -f report.md # Markdown report
```
### 严重程度过滤
```
vulnhawk scan ./src --severity high # Critical + High only
vulnhawk scan ./src --severity info # Everything
```
### SARIF 输入 - 与其他工具链式组合
将 Semgrep、CodeQL 或任何生成 SARIF 的工具的输出输入到 VulnHawk。它利用这些发现作为额外的上下文来**验证、扩展并串联**它们，从而挖掘更深层的漏洞。
```
# 先运行 Semgrep，然后用 VulnHawk 丰富
semgrep --config auto ./src -o semgrep.sarif --sarif
vulnhawk scan ./src --sarif-input semgrep.sarif
```
这实现了：
- 验证其他工具的发现是真实的还是误报
- 在标记位置附近发现相关漏洞
- 构建连接跨工具发现的多步骤攻击链
- 检查建议的修复是否解决了真正的根本原因
### 试运行
```
vulnhawk info ./src # Preview files, chunks, and language breakdown
```
## GitHub Action
VulnHawk 作为**默认分支上的基准扫描**运行，并在**每个 Pull Request 上进行增量扫描**。
### 推荐设置
```
name: VulnHawk Security Scan
on:
push:
branches: [main, master]
pull_request:
permissions:
security-events: write
contents: read
jobs:
vulnhawk:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: momenbasel/vulnhawk@main
with:
target: '.'
backend: 'claude-code'
claude-code-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
severity: 'medium'
fail-on-findings: 'true'
```
发现结果会通过 SARIF 自动上传到 GitHub 的 **Security > Code Scanning** 选项卡。
### 后端选项
| 后端 | 配置 |
|---|
| Claude Code (免费) |
```
backend: 'claude-code'
claude-code-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
```
获取你的 token：`claude config get oauth_token`
|
| Codex (免费) |
```
backend: 'codex'
```
需要在 runner 上执行 `codex login`。
|
| Claude API |
```
api-key: ${{ secrets.ANTHROPIC_API_KEY }}
```
|
| OpenAI API |
```
backend: 'openai'
api-key: ${{ secrets.OPENAI_API_KEY }}
```
|
### 在 CI 中与 Semgrep 链式组合
```
steps:
- uses: actions/checkout@v4
- name: Semgrep (fast pattern scan)
uses: returntocorp/semgrep-action@v1
with:
config: auto
generateSarif: true
- name: VulnHawk (deep AI analysis)
uses: momenbasel/vulnhawk@main
with:
target: '.'
backend: 'claude-code'
claude-code-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
sarif-input: 'semgrep.sarif'
```
## 支持的语言
| 语言 | 扩展名 | 框架检测 |
|:---|:---|:---|
| Python | `.py` | Django, Flask, FastAPI |
| JavaScript | `.js` `.jsx` | Express, Fastify, Next.js |
| TypeScript | `.ts` `.tsx` | Express, NestJS, Fastify |
| Go | `.go` | net/http handlers |
| Java | `.java` | 类/方法拆分 |
| PHP | `.php` | Laravel routes, classes, traits, interfaces |
| Ruby | `.rb` `.erb` | Rails routes, classes, modules |
## 工作原理
```
Codebase ──> Discover ──> Chunk ──> Enrich ──> Analyze ──> Validate ──> Report
│ │ │ │ │
Respects Functions Related LLM with Dedup +
.gitignore Classes code from security confidence
.vulnhawk- Routes same dir + prompts scoring
ignore Modules auth patterns
```
**增强**步骤是核心差异点。对于每个代码块，VulnHawk 包含：
- 同一目录中的其他函数/路由
- 整个代码库中的 Auth 中间件和守护模式
这为 AI 提供了识别不一致性所需的上下文。
## 配置
### .vulnhawkignore
从扫描中排除路径（gitignore 语法）：
```
generated/
vendor/
third_party/
*.gen.go
```
### 环境变量
| 变量 | 描述 |
|:---|:---|
| `CLAUDE_CODE_OAUTH_TOKEN` | Claude Code CLI 身份验证（订阅用户免费） |
| `ANTHROPIC_API_KEY` | Claude API 密钥 |
| `OPENAI_API_KEY` | OpenAI API 密钥 |
## 成本
| 后端 | 每次扫描（约 100 个文件） | 要求 |
|:---|:---|:---|
| **Claude Code CLI** | **免费** | Claude Code Max 或 Team 订阅 |
| **Codex CLI** | **免费** | ChatGPT Pro 或 Plus 订阅 |
| Claude API | ~$0.50 - $2.00 | Anthropic API 额度 |
| OpenAI API | ~$1.00 - $4.00 | OpenAI API 额度 |
| **Ollama** | **免费** | 具有 8GB+ VRAM 的本地机器 |
## 常见问题
Claude Code CLI 后端如何实现免费？
Claude Code 订阅（Max 每月 $100-$200，或 Team 计划）包含无限的 CLI 使用权限。VulnHawk 在底层调用 `claude --print`，通过你现有的订阅传输分析提示词。无需 API 密钥。无按 Token 计费。
如何获取用于 CI/CD 的 OAuth token？
在本地计算机上运行 `claude config get oauth_token`。将输出作为名为 `CLAUDE_CODE_OAUTH_TOKEN` 的 GitHub Actions Secret 添加。
我应该在每个 PR 上运行，还是仅在 main 分支上运行？
两者皆可。推送到 main 分支的扫描建立你的安全基准并填充 Security 选项卡。PR 扫描在合并前捕获新漏洞。推荐的工作流配置会处理这两种触发器。
我的代码是否会被发送到外部服务？
是的——代码块会被发送到配置的 LLM 提供商（Anthropic 或 OpenAI）。对于完全私密、隔离环境的扫描，请使用完全在本地机器上运行的 **Ollama** 后端。
它会替代 Semgrep 或 CodeQL 吗？
不会。VulnHawk 是一个互补层。Semgrep 和 CodeQL 在各自擅长的领域（模式匹配和污点追踪）表现出色。VulnHawk 能够捕获业务逻辑漏洞、授权缺口以及规则无法表达的不一致问题。将这三者结合使用可获得最强的覆盖能力。
它支持 PHP / Laravel 和 Ruby / Rails 吗？
支持。VulnHawk 包含针对两者的框架感知代码分块功能。它检测 Laravel `Route::get()` 定义、PHP 类/trait/接口、Rails 路由声明（`get`、`post`、`resources`）以及 Ruby 类/模块。它还提取框架特定的导入（`use`、`require`、`include`）。
什么是 SARIF 输入？
你可以将任何其他扫描器（Semgrep、CodeQL、Snyk 等）生成的 SARIF 文件输入给 VulnHawk。VulnHawk 在分析过程中将这些发现作为额外的上下文——验证它们，在附近发现相关问题，并构建连接跨工具发现的多步骤攻击链。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
```
git clone https://github.com/momenbasel/vulnhawk.git
cd vulnhawk
uv venv .venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest
```
## 支持本项目
如果 VulnHawk 对你有用，请考虑 [赞助本项目](https://github.com/sponsors/momenbasel) 以支持持续开发。
## 许可证
VulnHawk 采用 [VulnHawk License](LICENSE)，是**源码可用**的。
**对所有人免费**——个人、团队、初创公司和企业可以免费使用 VulnHawk 进行内部安全扫描，前提是通过官方分发渠道安装：
- [GitHub Marketplace](https://github.com/marketplace/actions/vulnhawk-security-scan)
- [PyPI](https://pypi.org/project/vulnhawk/)
- [本仓库](https://github.com/momenbasel/vulnhawk)
你不得出售本软件，不得将其作为竞争性服务提供，也不得将 Fork 作为产品重新分发。Fork 仅允许用于向此仓库提交 Pull Request。完整条款请参阅 [LICENSE](LICENSE)。
标签：AI风险缓解, C2, CMS安全, DevSecOps, GitHub Action, Go, IDOR, JavaScript, OpenVAS, PHP, Python, Ruby, Ruby工具, SAST, TypeScript, 上游代理, 云安全监控, 人工智能, 代码安全, 安全插件, 授权绕过, 无后门, 源码扫描, 漏洞枚举, 用户模式Hook绕过, 盲注攻击, 知识库, 结构化查询, 自动化安全, 逆向工具, 逻辑漏洞, 静态分析