andupetcu/penclaw
GitHub: andupetcu/penclaw
PenClaw 是一款 AI 驱动的渗透测试 CLI，将静态分析、动态扫描与智能分类整合为一条命令，仅报告经主动验证确认可利用的真实漏洞。
Stars: 2 | Forks: 0
# 🦀 PenClaw
**AI 驱动的渗透测试 CLI。** 一条命令 → 生成真实渗透测试报告，仅包含经证实且可利用的漏洞。
PenClaw 将静态分析、动态扫描和 AI 辅助的分类整合到一个工具中。将其指向源代码或在线 URL，即可获得具有可操作性的安全报告 —— 而不是一长串 CVE 编号。
## 功能
### 静态分析
- **Trivy** 文件系统扫描（CVE、配置错误）
- **Semgrep** 安全规则集（代码模式）
- **机密检测** — 正则表达式 + 基于熵的检测（API key、token、凭证）
- **目标画像** — 自动检测语言、框架、包管理器
### 动态扫描
- **Nuclei** 漏洞模板（5,600+ 项检查）
- **Playwright** 浏览器自动化 — 爬取、表单发现、XSS 验证
- **API fuzzing** — SQLi、NoSQLi、命令注入、路径遍历、IDOR、身份验证绕过
- **OWASP Top 10** 检查 — 标头、CORS、CSRF、开放重定向、SSRF
- **目录爆破** — 常见路径、管理后台、备份文件
- **JWT 攻击** — none/alg 混淆、弱密钥爆破、声明验证
### AI 分类
- 多提供商：**Anthropic Claude**、**OpenAI GPT**、**Ollama**（本地模型）
- AI 生成的**推理过程、概念验证和修复建议**（针对每个发现）
- 静态 ↔ 动态漏洞关联
### 报告
- **Markdown** — 易于阅读，非常适合用于 PR
- **JSON** — 机器可解析，可通过管道传递给其他工具
- **SARIF** — 集成 GitHub 代码扫描
- **HTML** — 交互式暗色主题仪表盘，支持过滤和置信度条
## 快速开始
```
# 安装
git clone https://github.com/andupetcu/penclaw.git
cd penclaw
npm install
npm run build
# 扫描源代码（静态）
npx penclaw scan ./my-project --output report.md
# 扫描实时 URL（动态）
npx penclaw scan https://example.com --dynamic --format html -o report.html
# 完整扫描（静态 + 动态）
npx penclaw scan ./my-project https://example.com --full -o report.html
```
### 前置条件
| 工具 | 用途 | 安装 |
|------|-------------|---------|
| Node.js 20+ | 核心组件 | [nodejs.org](https://nodejs.org) |
| Trivy | 静态 CVE 扫描 | `brew install trivy` |
| Semgrep | 静态代码分析 | `pip install semgrep` |
| Nuclei | 动态漏洞模板 | `brew install nuclei` |
| Playwright | 浏览器爬取/XSS | 通过 npm 捆绑安装 |
PenClaw 具备优雅降级功能 —— 如果缺少某个工具，它会跳过该扫描器并报告警告。
## CLI 参考
```
penclaw scan [options]
Arguments:
target Filesystem path(s) or URL(s) to scan
Options:
-o, --output Write report to file
-f, --format Output format: markdown, json, sarif, html
--dynamic Enable dynamic scanning (URL targets)
--full Enable both static and dynamic scanning
--ci CI mode with severity-based exit codes
--fail-on Min severity to fail in CI (default: high)
--provider AI provider: anthropic, openai, ollama
--model AI model identifier
--config Path to .penclaw.yml config file
--insecure Disable TLS certificate verification during crawling (DANGEROUS)
--allow-private Allow scanning private/internal/loopback hosts
--auth-bearer Bearer token for authenticated dynamic scanning
--auth-cookie Cookie header value for authenticated dynamic scanning
--auth-bearer-b Second identity bearer token (enables two-identity IDOR confirmation)
```
### 安全与身份验证标志
| 标志 | 描述 |
|------|-------------|
| `--insecure` | 在爬取过程中禁用 TLS 证书验证。**危险** — 可能会将凭证暴露给路径上的攻击者。默认情况下，证书验证为**开启**状态。注意：`--insecure` 目前仅影响基于浏览器的爬取；其他 HTTP 请求始终会验证 TLS。 |
| `--allow-private` | 允许扫描私有 / 内部 / 回环主机。默认情况下 SSRF 防护为**开启**状态并会阻止这些主机。 |
| `--auth-bearer ` | 用于经过身份验证的动态扫描的 Bearer token。 |
| `--auth-cookie ` | 用于经过身份验证的动态扫描的 Cookie 标头值。 |
| `--auth-bearer-b ` | 第二个身份的 Bearer token，用于启用双身份 IDOR 验证。 |
### 主动确认
PenClaw 不会仅凭怀疑就报告 JWT 和 IDOR 问题 —— 它会在将其报告为高/严重级别之前，**主动针对目标进行确认**：
- **JWT `alg:none` / 过期 token** — 将伪造的 `alg:none` token 和任何过期的 token 重放到受保护的 endpoint。仅当服务器确实在拒绝了未经身份验证的请求的情况下，接受了伪造/过期的 token 时，该漏洞才会被提升级别（严重/高）。
- **IDOR** — 使用两个身份进行确认最为可靠：提供 `--auth-bearer` 和 `--auth-bearer-b`，当身份 B 可以读取身份 A 的资源时，PenClaw 即可确认 IDOR。如果只有一个身份，它只能标记可能的 IDOR，并建议您使用 `--auth-bearer-b` 重新运行。
无法确认的候选项将被标记为未确认，并在分类阶段予以抑制，而不会作为真实的漏洞报告。
### CI 模式
```
# 在发现高危及以上严重性结果时使构建失败
npx penclaw scan ./src --ci --fail-on high
# Exit codes：
# 0 = clean
# 1 = 发现结果超过阈值
# 2 = critical findings
```
## 配置
在您的项目根目录中创建 `.penclaw.yml`：
```
ai:
provider: anthropic # anthropic | openai | ollama
model: claude-sonnet-4-20250514
scan:
static: true
dynamic: false
excludePaths:
- node_modules/
- dist/
- "**/*.test.ts"
skipDirectoryScan: false
skipJwtTests: false
maxConcurrentRequests: 10
requestDelayMs: 100
output:
format: markdown
path: ./report.md
```
AI 凭证将从环境变量中读取：
- `ANTHROPIC_API_KEY` 用于 Claude
- `OPENAI_API_KEY` 用于 GPT
- Ollama 在本地运行（无需 key）
## 架构
```
src/
├── cli/ # Commander.js CLI entry point
├── config/ # cosmiconfig loader (.penclaw.yml)
├── profiler/ # Target profiling (filesystem + URL fingerprinting)
├── scanners/ # Static scanners (Trivy, Semgrep, secrets)
├── dynamic/ # Dynamic scanners (Nuclei, OWASP, directory, JWT)
├── crawl/ # Playwright browser crawler + API fuzzer
├── triage/ # AI-powered finding triage + PoC generation
├── reporters/ # Output formatters (MD, JSON, SARIF, HTML)
├── types/ # TypeScript interfaces
└── utils/ # Shared utilities
```
### 工作原理
1. **画像** — 检测目标类型（文件系统还是 URL），识别技术栈
2. **扫描** — 并行运行适用的扫描器
3. **分类** — AI 审查原始漏洞发现，生成 PoC，并提供修复建议
4. **关联** — 将静态漏洞发现与动态证据进行匹配
5. **报告** — 以选定格式输出可操作的报告
## 示例
### 扫描 Node.js 项目
```
npx penclaw scan ./my-api --output security-report.md
```
### 对在线应用进行全面渗透测试
```
npx penclaw scan https://staging.myapp.com --full --format html -o pentest.html
```
### CI pipeline（GitHub Actions）
```
- name: Security scan
run: npx penclaw scan ./src --ci --fail-on high --format sarif -o results.sarif
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
```
## 路线图
- [x] **阶段 1** — 静态分析 + AI 分类 MVP
- [x] **阶段 2** — 动态测试（Nuclei、Playwright、API fuzzing、OWASP）
- [x] **阶段 2.5** — 达到真实世界渗透测试同等水平（payload 包、盲注 SQLi、JWT 攻击、目录爆破）
- [ ] **阶段 3** — GitHub Action (`uses: penclaw/scan@v1`)
- [ ] **阶段 4** — 负日（0-day）依赖项监控
- [ ] **阶段 5** — SaaS 仪表盘
## 许可证
MIT
## 贡献
欢迎提交 PR。提交前请运行 `npm test`。
```
npm install
npm run build
npm test
```
由 [Andrei Petcu](https://github.com/andupetcu) 和 [Kai](https://github.com/andupetcu/penclaw) 构建 ⚡
标签：AI风险缓解, CISA项目, MITM代理, StruQ, 人工智能, 代码生成, 动态扫描, 渗透测试工具, 特征检测, 用户模式Hook绕过, 聊天机器人, 自动化攻击, 错误基检测, 静态代码分析