tomerblum/AI-Powered-Recon-Assistant

# AI 驱动的侦察助手 一个 CLI 工具，针对授权目标运行标准侦察工具，并使用 Claude 生成一份优先级明确的、人类可读的攻击面报告。  ## 功能介绍 输出内容（如上所示）是一份包含三个部分的 Markdown 报告： 1. **扫描元数据。** 记录了运行的内容、时间以及耗时。 2. **分模块章节。** 包含结构化发现的表格（事实来源），以及由 LLM 生成的分析，用于确定优先查看的内容。 3. **推荐的后续步骤。** 具体且可操作的分流建议。 LLM **不会执行扫描**。它读取由确定性的 Python 代码生成的结构化发现，并为其撰写叙述说明。这种分离是刻意为之：它使工具具有可预测性、可审计性，并且不可能被武器化为自主攻击者。 ### 查看输出效果 真实的、未经编辑的报告已提交到 [`samples/`](./samples/)，因此无需安装任何软件，您就可以查看 `recon-assistant` 的生成内容： - [**`scanme.nmap.org`**](./samples/scanme.nmap.org_2026-06-27.md)：一次包含所有四个模块的**主动**扫描（针对活动主机进行端口和技术栈指纹识别）。 - [**`nmap.org`**](./samples/nmap.org_2026-06-27.md)：一次**被动**扫描（OSINT 和子域名枚举，不向目标发送流量）。 ## 开发初衷 该项目处于进攻性安全、应用级 AI/LLM 集成与 Python 工程的交汇点。它展示了一种将 LLM 与现有工具相结合的深思熟虑的方法：LLM 是阅读器和综合者，而不是执行者。 ## 架构 ``` ┌─────────────┐ ┌───────────────────┐ ┌──────────────┐ ┌──────────────┐ │ CLI │ -> │ Recon modules │ -> │ LLM │ -> │ Markdown │ │ (typer) │ │ (gather + typed │ │ client │ │ report │ │ │ │ pydantic model) │ │ (Claude) │ │ │ └─────────────┘ └───────────────────┘ └──────────────┘ └──────────────┘ ``` - **Modules** 各自收集一种类型的侦察数据并返回一个类型化的 Pydantic 模型。其中三个封装了外部工具（`subfinder`、`nmap`、`whatweb`）；一个（`osint`）是通过公共 HTTP API 实现的纯 Python 代码。 - **Runner** 负责编排执行，优雅地处理超时和工具缺失错误，并对每一步进行计时。 - **LLM client** 将结构化的发现转化为 Markdown 分析章节。系统提示词在调用间会被缓存（Anthropic prompt caching）。 - **Report writer** 将结构化表格与 LLM 生成的叙述内容交织在一起。 ## 状态 **v0.1.0，早期开发阶段。** 四个 v1 模块均已发布，且架构已实现端到端的验证。 - [x] 子域名枚举（`subfinder`），被动 - [x] 端口扫描（`nmap`），仅主动模式，强度由扫描配置文件设置 - [x] 技术栈指纹识别（`whatweb`），仅主动模式 - [x] OSINT（RDAP 和证书透明度），被动，纯 Python，无需二进制文件 - [x] 示例报告已提交（见 [`samples/`](./samples/)） - [ ] HaveIBeenPwned 泄露数据源（需要付费的 API 密钥） - [ ] 将发现的子域名导入到端口和技术栈扫描器中（目前每个模块仅扫描目标主机） ## 安装说明 您需要 Python 3.11+ 以及您想使用的侦察工具。 ``` # 克隆 git clone https://github.com/tomerblum/AI-Powered-Recon-Assistant.git cd AI-Powered-Recon-Assistant # 安装（可编辑模式，包含 dev deps） pip install -e ".[dev]" # 配置 cp .env.example .env # add your ANTHROPIC_API_KEY cp recon-assistant.toml.example recon-assistant.toml # 安装 recon tools # macOS (Homebrew): brew install nmap subfinder # whatweb 不在 Homebrew 中，请从源码安装： git clone https://github.com/urbanadventurer/WhatWeb.git ~/WhatWeb ln -s "$HOME/WhatWeb/whatweb" "$(brew --prefix)/bin/whatweb" # （冒烟测试：`whatweb --version`） # Kali / Debian： # sudo apt install -y nmap whatweb subfinder ``` 该工具会在运行时检测缺失的二进制文件，并跳过受影响的模块同时提示安装建议，因此您无需安装所有工具即可运行扫描。 ## 使用说明 ``` # 被动扫描（默认）：不向目标发送流量。运行 OSINT + subdomain enum。 recon-assistant scan example.com # 主动扫描：增加 nmap 端口扫描和 whatweb 指纹识别。 # 会向目标发送探测，因此仅在获得授权时运行。 recon-assistant scan example.com --active # 通过 profile 控制强度（独立于 --active）： # light = top 100 端口，礼貌定时（温和；默认） # standard = top 1000 端口 + 服务/版本检测 # aggressive = 全部 65535 个端口，更快的定时（意味着 --active） recon-assistant scan example.com --active --profile standard recon-assistant scan example.com --profile aggressive # 自定义配置 / 输出目录 recon-assistant scan example.com --config ./prod.toml -o ./engagement-2026-q2/ ``` 运行 `recon-assistant scan --help` 获取完整的参数参考。 ### 选择 LLM 提供商 分析步骤是与提供商无关的。在 `recon-assistant.toml` 中设置 `llm.provider`： - **`anthropic`**（默认）：原生 Anthropic Messages API，支持自适应思考（adaptive thinking）和提示词缓存（prompt caching）。需要在 `ANTHROPIC_API_KEY` 中设置 `sk-ant-...` 密钥。 - **`openai-compatible`**：任何兼容 OpenAI Chat Completions 的 endpoint（OpenRouter、Ollama、LM Studio 等）。设置 `base_url`、`model`（endpoint 的 slug）和 `api_key_env`。 OpenRouter 配置示例： ``` [llm] provider = "openai-compatible" base_url = "https://openrouter.ai/api/v1" model = "anthropic/claude-sonnet-4.5" # copy the exact slug from openrouter.ai/models api_key_env = "OPENROUTER_API_KEY" ``` 然后将 `OPENROUTER_API_KEY=sk-or-v1-...` 放入 `.env` 中。更换提供商只需修改配置，无需改动代码。 ### 各模块对应工具 | 模块 | 工具 | 模式 | 备注 | |--------------|----------------------|---------|------------------------------------------------| | `osint` | RDAP + crt.sh (HTTP) | passive | 纯 Python，无需二进制文件 | | `subdomains` | `subfinder` | passive | 证书透明度和公共 DNS 来源 | | `ports` | `nmap` | active | TCP connect scan (`-sT`)，无需 root 权限 | | `tech_stack` | `whatweb` | active | HTTP 指纹识别；强度由配置文件设定 | ## 安全注意事项 - **API 密钥存储。** LLM API 密钥保存在被 gitignore 忽略的 `.env` 文件中，这与 `~/.aws/credentials`、`gh auth` 等工具的模型相同。在 Unix 上运行 `chmod 600 .env`。 - **无漏洞利用代码。** LLM 系统提示词将分析定位于防御者侧的分流（triage），并禁止生成 payload、漏洞利用代码或攻击指令。 - **默认被动模式。** `--active` 是一项明确的主动选择。若不使用此参数，则仅运行查询第三方数据源的模块，因此不会有任何数据包发送到目标。 - **无自主工具执行。** LLM 仅处理结构化数据。它从不决定运行哪个工具，从不执行 shell 命令，也从不发起超出分析调用范围的外部请求。该 pipeline 是确定性的 Python 代码。 ## 局限性 - 每个模块仅扫描目标主机。发现的子域名尚未反馈到端口和技术栈扫描器中。 - 扫描结果不会被缓存，因此对同一目标重新运行会再次调用工具。 - LLM 的分析质量仅取决于结构化输入的质量。垃圾进，听起来很客气的垃圾出。 ## 开发说明 ``` # 运行测试 pytest # 类型检查 mypy # Lint ruff check src tests ``` 测试基于已提交的 fixture 文件（捕获的工具输出）运行，没有实时子进程或网络调用。 ## 许可证 MIT。

标签：AI报告生成, GitHub, Python, 实时处理, 密码管理, 无后门, 自动化侦察, 逆向工具