- **30 个模块化工具**，电子邮件、用户名（sherlock + WhatsMyName）、跨越 3,000+ 网站的广泛用户名发现、基于搜索的足迹发现、IP、IP 自我暴露报告、域名、WHOIS、数据泄露、Gravatar 配置文件、EmailRep 信誉、电话、paste、EXIF/GPS 元数据、Shodan、VirusTotal、Censys、IP2Location、AbuseIPDB、GitHub（配置文件 + 公开代码/机密暴露）、DNS、通过证书透明度 进行子域名发现、通过 Wayback Machine（Internet Archive）进行历史 URL 恢复、大规模扫描可见性、信息窃取暴露检查（Hudson Rock，免费层，无明文凭据）、dork 生成、实时 dork 搜索、URL 抓取、BTC/ETH 地址查询以及被动域名侦察 - **内置 MCP server**，将所有 30 个工具原生暴露给 Claude Code、Claude Desktop 和任何兼容 MCP 的客户端 - **三种 AI 后端**，Anthropic Claude（默认）、本地 Ollama 或任何 OpenAI 兼容的 endpoint；工具结果来自真实的子进程调用，绝不产生幻觉 - **完全异步**，通过带有严格子进程超时的 `asyncio.gather()` 并行执行工具 - **MIT 许可证**，无嵌入式 LLM；自带您的 API 密钥或完全离线运行 ## 什么是 Clearfront？ Clearfront 是一个用于开源情报的 AI agent，具有三个接口：交互式终端 REPL、直接 CLI 和可暴露给 Claude Code、Claude Desktop 或任何兼容 MCP 客户端的 MCP server，以及基于浏览器的 Web UI。AI 层使用 Anthropic 原生的工具使用 API（或本地 Ollama 模型，或任何兼容 OpenAI 的 endpoint）：当模型需要工具时会发出硬停止，您的代码执行真实的二进制文件，实际输出返回，从结构上排除了工具结果中的幻觉。 ## 安装 ``` git clone https://github.com/scottmartinanderson/clearfront cd clearfront pip install -e . ``` **外部二进制文件**（必须位于 `PATH` 中）： | Binary | Purpose | Install | |--------|---------|---------| | `holehe` | 电子邮件账户枚举 | `pip install holehe` | | `sherlock` | 用户名枚举（300+ 平台） | `pip install sherlock-project` | | `sublist3r` | 子域名枚举 | `pip install sublist3r` | | `phoneinfoga` | 电话号码情报 | [下载二进制文件](https://github.com/sundowndev/phoneinfoga/releases) | | `theHarvester` | 被动域名侦察（电子邮件/子域名） | `pip install git+https://github.com/laramies/theHarvester.git` | 如果缺少某个二进制文件，相应的工具将返回描述性错误字符串。所有其他工具仍保持可操作。 ## 快速开始 ``` # 交互式 AI REPL（默认） clearfront # Web 界面 clearfront web # 直接工具（无 AI） clearfront email target@example.com ``` ## 配置 将所有密钥存储在项目根目录的 `.env` 文件中（复制 `.env.example`）。`python-dotenv` 会在启动时自动加载它。 | Variable | Tool | Required | Purpose | |----------|------|----------|---------| | `ANTHROPIC_API_KEY` | AI agent | 是（或使用 Ollama / OpenAI） | Anthropic API 密钥 | | `OPENAI_BASE_URL` | AI agent | 可选 | 兼容 OpenAI 的 endpoint 的 base URL（例如 `http://localhost:4000/v1`）。设置此项且缺少 `ANTHROPIC_API_KEY` 时，它将用作 AI 后端（优先于 Ollama）。该模型必须支持工具/函数调用。 | | `OPENAI_API_KEY` | AI agent | 可选 | 兼容 OpenAI 的 endpoint 的 API 密钥（本地服务器可能会忽略它） | | `OPENAI_MODEL` | AI agent | 可选 | 从 endpoint 请求的模型名称（默认值：`gpt-4o-mini`） | | `HIBP_API_KEY` | `search_breach` | 可选 | HaveIBeenPwned v3，[获取一个](https://haveibeenpwned.com/API/Key) | | `IPINFO_TOKEN` | `search_ip` | 可选 | ipinfo.io 更高频率限制 | | `SHODAN_API_KEY` | `search_shodan` | 可选 | Shodan API，[获取一个](https://account.shodan.io) | | `VIRUSTOTAL_API_KEY` | `search_virustotal` | 可选 | VirusTotal API v3，[获取一个](https://www.virustotal.com/gui/my-apikey) | | `IP2LOCATION_API_KEY` | `search_ip2location` | 可选 | IP2Location.io 增强型 IP 情报，[获取一个](https://www.ip2location.io/pricing) | | `CENSYS_PAT` + `CENSYS_ORG_ID` | `search_censys` | 可选 | Censys Platform API：Personal Access Token + Organization ID，[获取一个](https://platform.censys.io) | | `ABUSEIPDB_API_KEY` | `search_abuseipdb` | 可选 | AbuseIPDB v2，[获取一个](https://www.abuseipdb.com/account/api) | | `GITHUB_TOKEN` | `search_github` | 可选 | GitHub API，将速率限制从 60 提升至 5000 请求/小时，[获取一个](https://github.com/settings/tokens) | | `SERPER_API_KEY` | `search_dorks_live`, `search_footprint` | 可选 | Serper.dev Google SERP API，首选的 SERP 后端（约 $1/1k，免费 2,500 次），[获取一个](https://serper.dev)。 | | `BRIGHTDATA_API_KEY` | `search_dorks_live`, `scrape_url` | 可选 | Bright Data API 密钥，[获取一个](https://get.brightdata.com/8ygvxztgo5dr)（免费层：5,000 次请求/月）。 | | `BRIGHTDATA_SERP_ZONE` | `search_dorks_live` | 可选 | 您的 Bright Data SERP API 区域名称（例如 `serp_api1`）。 | | `BRIGHTDATA_UNLOCKER_ZONE` | `scrape_url` | 可选 | 您的 Bright Data Web Unlocker 区域名称（例如 `web_unlocker1`）。 | 上面的 Bright Data 链接是一个推荐链接；通过它注册可以支持 Clearfront，对您没有任何额外成本。 **可选 Python 包：** | Package | Purpose | Install | |---------|---------|---------| | `ollama` | 本地 LLM 后端（无 API 密钥） | `pip install ollama` *（同时安装 [Ollama runtime](https://ollama.com)）* | | `openai` | 用于 REPL/CLI 的兼容 OpenAI 的后端（`--provider openai`） | `pip install "clearfront[openai]"` | | `shodan` | Shodan API 客户端 | `pip install shodan` | | `reportlab` | PDF 报告导出 | `pip install reportlab` | | `censys` | Censys API 客户端 | `pip install censys` | ## 工具 | Tool | Powered by | What it investigates | |------|-----------|---------------------| | `search_email` | holehe | 链接到电子邮件地址的社交账户 | | `search_username` | sherlock | 跨越 300+ 平台的用户名存在情况 | | `search_breach` | HaveIBeenPwned v3 API | 数据泄露暴露 | | `search_whois` | python-whois | 域名注册人和 DNS 信息 | | `search_ip` | ipinfo.io | 地理位置、ASN、hostname | | `search_domain` | sublist3r | 子域名枚举 | | `search_crt` | crt.sh | 通过证书透明度获取子域名（免密钥、被动） | | `search_wayback` | Internet Archive | 在域名下归档的历史/已删除 URL（免密钥、被动） | | `search_greynoise` | GreyNoise Community | IP 的大规模扫描器噪音与针对性攻击者对比（免费，50 次/周） | | `generate_dorks` | 内置 | 12 个针对性的 Google dork URL（无网络调用） | | `search_paste` | psbdmp.ws | Pastebin 转储提及 | | `search_phone` | phoneinfoga | 运营商、国家、线路类型 | | `search_shodan` | Shodan API | 开放端口、banners、CVEs | | `search_virustotal` | VirusTotal API v3 | 来自 70+ 防病毒引擎的判定结果 | | `search_ip2location` | IP2Location.io API | 增强型 IP 情报：VPN/Proxy/Tor/datacenter 标记 | | `search_censys` | Censys Search API | 面向互联网的基础设施、证书 | | `search_abuseipdb` | AbuseIPDB v2 API | IP 滥用信誉：置信度分数、报告、国家、ISP | | `search_github` | GitHub REST API | 配置文件、repos、commit 发现的电子邮件、用户名/关键字搜索 | | `search_dns` | dnspython（内置） | A/AAAA/MX/NS/TXT/CNAME/SOA 记录；SPF、DMARC、DKIM 分析 | | `search_dorks_live` | Bright Data SERP API | 用于 dork 查询的实时 Google 搜索结果（标题、URL、摘要） | | `scrape_url` | Bright Data Web Unlocker | 绕过 Cloudflare/CAPTCHA 获取任何 URL，返回干净的 Markdown | | `search_maigret` | maigret | 跨越 3,000+ 网站的用户名存在情况 | | `search_footprint` | SERP (Serper / Bright Data / DuckDuckGo) | 针对姓名或 handle 的基于搜索的足迹发现 | | `search_gravatar` | Gravatar API | 电子邮件的公开 Gravatar 配置文件：头像、显示名称、关联账户 | | `search_emailrep` | EmailRep.io | 电子邮件信誉和足迹摘要 | | `search_hudsonrock` | Hudson Rock Cavalier (免费) | 电子邮件或用户名的信息窃取暴露检查（无明文凭据） | | `search_exif` | exiftool | 本地文件的 EXIF / IPTC / XMP 元数据和嵌入的 GPS | | `search_crypto` | 公共链 APIs | 比特币 / 以太坊地址摘要：余额、交易计数 | | `search_harvester` | theHarvester | 被动域名侦察：电子邮件、子域名、主机 | | `search_exposure` | 内置（复合） | 跨越基础设施工具的 IP 自我暴露报告 | ## 接口 ### 交互式 REPL 运行不带参数的 `clearfront` 以启动 AI 驱动的 REPL。输入目标（电子邮件、用户名、域名、IP、姓名）或问题；agent 决定运行哪些工具，根据发现链接它们，并编译报告。 **REPL 命令：** ``、`clear`、`save`、`tools`、`config`、`history`、`help`、`exit` / Ctrl-D。 所有会话都会自动保存到 `~/.clearfront/history/`。使用 `clearfront history` 浏览。 ### Web UI ``` pip install "clearfront[web]" clearfront web # 自动打开 http://localhost:8080 ``` 基于浏览器的 AI 聊天，具有流式传输工具输出、内联结果卡片以及浅色/深色主题切换。通过 Ollama 或任何兼容 OpenAI 的 endpoint 支持完全本地推理（使用本地后端时无需 Anthropic API 密钥）。 控制台完全在您的机器上运行，默认绑定到 `127.0.0.1`。在 Settings 中选择您的后端并粘贴您自己的密钥；您的密钥和您调查的目标永远不会触及我们的服务器。屏幕截图位于 [`media/screenshots/`](media/screenshots/)。 ### MCP Server 所有 30 个工具暴露给任何兼容 MCP 的 AI 客户端。 **Claude Code：** ``` claude mcp add clearfront python /absolute/path/to/clearfront/mcp_server.py claude mcp list ``` **Claude Desktop**，添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`： ``` { "mcpServers": { "clearfront": { "command": "python", "args": ["/absolute/path/to/clearfront/mcp_server.py"] } } } ``` ## Docker ``` docker compose up --build docker compose run --rm clearfront email target@example.com --json ``` 在 `.env` 文件中设置 `ANTHROPIC_API_KEY`（以及可选的 `HIBP_API_KEY`、`IPINFO_TOKEN`），或者在运行前导出它们。报告通过卷挂载持久化到 `./reports/`。 ## CLI 参考 | Flag / Subcommand | Description | |---|---| | `clearfront` | 交互式 AI REPL（默认） | | `clearfront web [--port N] [--no-browser]` | 启动浏览器 UI | | `clearfront email ADDRESS [-t N]` | 直接电子邮件扫描 | | `clearfront username HANDLE [-t N]` | 直接用户名扫描 | | `clearfront shodan QUERY [-t N]` | Shodan 查找 | | `clearfront virustotal TARGET [-t N]` | VirusTotal 查找 | | `clearfront censys TARGET [-t N]` | Censys 查找 | | `clearfront ip2location IP [-t N]` | IP2Location 查找 | | `clearfront abuseipdb IP [-t N]` | AbuseIPDB 信誉检查 | | `clearfront github QUERY [-t N]` | GitHub 配置文件/repo/电子邮件发现 | | `clearfront dns DOMAIN [-t N]` | DNS 记录 + 电子邮件安全分析 | | `clearfront multi TARGETS` | 并行多目标调查（最多 10 个） | | `clearfront graph TARGET [-o PATH] [--format graphml\|json\|mermaid\|all]` | 自动枢纽并导出实体关联图（GraphML/JSON/Mermaid） | | `clearfront history [--all] [open N] [clear]` | 查看/管理 REPL 会话历史 | | `-v, --verbose` | 启用调试日志输出到 stderr | | `-t, --timeout N` | 覆盖子进程超时（秒） | | `--api-key KEY` | Anthropic API 密钥（覆盖环境变量） | | `--parallel` | 并发运行互补工具 | | `--json` | 输出结构化 JSON 格式的结果 | | `-o, --output FILE` | 将结果写入 FILE 而不是标准输出（原始格式；与 `--json` 结合使用可生成 JSON 文件） | | `--provider {anthropic,ollama,openai}` | AI provider（默认值：`anthropic`） | | `--ollama-model MODEL` | Ollama 模型名称（默认值：`llama3.2`） | | `--ollama-host URL` | Ollama 服务器 URL（默认值：`http://localhost:11434`） | | `--openai-base-url URL` | 兼容 OpenAI 的 endpoint base URL（环境变量：`OPENAI_BASE_URL`） | | `--openai-model MODEL` | 从 endpoint 请求的模型（环境变量：`OPENAI_MODEL`） | | `--openai-api-key KEY` | endpoint 的 API 密钥（环境变量：`OPENAI_API_KEY`） | | `--no-pdf` | 禁用自动生成 PDF | ## 许可证 Clearfront 是开源的，遵循 [MIT 许可证](./LICENSE)。 捆绑的用户名数据集 `clearfront/tools/data/wmn-data-unique.json` 是 由 Micah Hoffman 创建的 [WhatsMyName](https://github.com/WebBreacher/WhatsMyName) 项目的过滤改编版本， 根据 [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) 许可使用；该文件（及其改编版本）仍受 CC BY-SA 4.0 保护。请参阅 [`clearfront/tools/data/NOTICE`](./clearfront/tools/data/NOTICE)。 *仅用于授权的安全研究。请参阅 [DISCLAIMER.md](DISCLAIMER.md)。*

标签：AI安全分析师, AI风险缓解, ESC4, GitHub, MCP服务, OSINT, Python, 安全情报, 实时处理, 无后门, 计算机取证, 请求拦截, 进程管理, 逆向工具