matte97p/pentest-framework

# Pentest Framework 一个模块化、自动化的渗透测试 pipeline，它可以编排开源工具，将结果标准化为单一的 schema，进行去重，可选择使用 LLM 来丰富发现的问题，并生成专业的 PDF 报告。 ## Pipeline ``` target ─▶ recon ─▶ scanners ─▶ api_checks ─▶ aggregate ─▶ [enrich] ─▶ PDF report (subfinder/ (nuclei/ (headers/CORS/ (dedup + (Claude, amass/httpx) nikto) exposed paths) group) optional) ``` ## 设计上的低噪声 大多数 header/recon 扫描器会让你淹没在误报中。本工具会在源头抑制常见的误报： - **感知 Content-type 的 headers** —— CSP、X-Frame-Options、Referrer-Policy 和 Permissions-Policy 仅在渲染的 HTML 文档上被标记，而在它们不起作用的 JSON API 上不会被标记。 - **仅在 HTTPS 上启用 HSTS** —— 绝不会在明文 `http://` 目标上报告，因为浏览器会忽略该 header。 - **SPA-fallback 指纹识别** —— 对于为每个路径返回 index shell 的单页应用 catch-all，不会被报告为“暴露的 endpoint”。 - **CORS** —— 仅标记精确的危险组合（反射的 / `null` origin *带有凭据*），而不是配置正确的 allowlist。 - **统一的 schema** —— 每个工具的输出都会被标准化、去重，并进行严重性升级，最终汇聚为一种单一的 finding 数据结构。 ## 架构 ``` pentest-framework/ # repo root ├── pentest_framework/ # the package │ ├── main.py # full pipeline (CLI: pentest-framework) │ ├── scan_local.py # scan a locally-running app by URL │ ├── recon/ scanner/ api_checks/ parser/ enrichment/ report/ │ ├── models/ # the single Finding schema + Severity │ └── utils/ # logging, subprocess runner, scope handling ├── examples/ # standalone usage examples ├── tests/ # pytest unit tests └── pyproject.toml LICENSE README.md ``` ## 安装 ``` pip install -e ".[ai]" # editable install; '[ai]' adds optional Claude enrichment # 或仅 runtime deps： pip install -r requirements.txt ``` 会安装一个 `pentest-framework` 控制台命令（等同于 `python -m pentest_framework.main`）。 外部 CLI 工具**不是** Python 包 —— 请单独安装它们并将其放置在 `$PATH` 中： | 工具 | 作用 | 链接 | |------|------|------| | `subfinder` | 子域名枚举（主要） | https://github.com/projectdiscovery/subfinder | | `httpx` | 存活检测 + 技术指纹识别 | https://github.com/projectdiscovery/httpx | | `nuclei` | 漏洞扫描（主要） | https://github.com/projectdiscovery/nuclei | | `amass` | 子域名枚举（备选） | https://github.com/owasp-amass/amass | | `nikto` | Web 服务器扫描（备选） | https://github.com/sullo/nikto | 该 pipeline **支持优雅降级**：缺失的工具会被记录并跳过，而不会导致运行崩溃。 ## 使用方法 ``` # 完整运行 python -m pentest_framework.main example.com # 使用 scope file 和 AI enrichment python -m pentest_framework.main example.com --scope scope.txt --enrich # 扫描单个 IP，自定义输出目录，无交互提示 python -m pentest_framework.main 203.0.113.10 -o /output --no-confirm ``` 输出（在 `--output` 下，默认为 `output/`）： - `pentest_report.pdf` —— 报告 - `findings.json` —— 标准化且去重后的 findings - `recon.json` —— recon 结果 - `pentest.log` —— 完整的运行日志 成功时会打印： ``` Pentest completed. Report saved at output/pentest_report.pdf ``` ### Scope 文件格式 ``` # 每行一个条目；允许 '#' 注释 example.com api.example.com *.staging.example.com 203.0.113.10 ``` 任何被发现的不符合授权范围内的 host，都会在探测前被丢弃。 ## 独立运行模块 每个模块都可以独立运行： ``` python -m pentest_framework.recon.recon example.com python -m pentest_framework.scanner.scanner --url https://example.com python -m pentest_framework.api_checks.api_checks https://example.com python -m pentest_framework.parser.aggregator findings.json python -m pentest_framework.enrichment.enrich findings.json python -m pentest_framework.report.report findings.json --target example.com ``` ## AI 辅助的信息丰富 `enhance_finding(finding)` 会澄清描述，添加现实的影响，并建议修复措施。它是**严格的编辑行为** —— 它绝不会捏造漏洞，也绝不会更改严重性/标题/目标/证据。 - 如果安装了 `anthropic` 并设置了 `ANTHROPIC_API_KEY`，它将使用 Claude （默认为 `claude-opus-4-8`；可通过 `ANTHROPIC_MODEL` 覆盖）。 - 否则，它将回退到安全的离线启发式方法，该方法仅填充明显缺失的字段。 ## 扫描本地应用 `recon` 会解析域名，因此对于位于非标准端口上的应用，请直接将 URL 作为目标： ``` python -m pentest_framework.scan_local # defaults: localhost:8080 + :8000 python -m pentest_framework.scan_local --targets http://localhost:3000/ ``` ## Finding schema ``` { "title": "", "severity": "Critical | High | Medium | Low | Info", "description": "", "target": "", "evidence": "", "remediation": "" } ``` ## 测试 ``` pip install -e ".[dev]" && pytest ``` ## License MIT —— 请参阅 [LICENSE](LICENSE)。仅供授权的安全测试使用；在贡献之前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。

标签：Python, 安全规则引擎, 实时处理, 密码管理, 对称加密, 无后门, 自动化审计, 逆向工具