内容
<div align="center">
<h1>Clearfront</h1>
<p><strong>您数字足迹上的开源人工智能情报。</strong></p>
<p>给Clearfront一个电子邮件、用户名、域名、IP地址或名称，其AI安全分析师会在一次扫描中扫描公共数据源，然后返回一份校准报告和一个交互式证据图。检查您自己的暴露情况，或调查一个授权的目标。它在本地运行，使用您自己的API密钥，不会向我们发送任何信息。</p>
<p>交互式REPL · CLI · 本地网页控制台 · MCP服务器。由Anthropic Claude、本地Ollama模型或任何OpenAI兼容的端点提供支持。</p>
</div>
<div align="center">
[](https://www.python.org/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](CHANGELOG.md)
**[clearfront.sh](https://clearfront.sh)** · [免责声明](./DISCLAIMER.md)
</div>
- **30个模块化工具**，电子邮件、用户名（sherlock + WhatsMyName）、跨3000+网站的广泛用户名发现（maigret）、基于搜索的足迹发现、IP地址、IP自我暴露报告、域名、WHOIS、泄露、Gravatar配置文件、EmailRep声誉、电话、粘贴、EXIF/GPS元数据、Shodan、VirusTotal、Censys、IP2Location、AbuseIPDB、GitHub（配置文件+公共代码/秘密暴露）、DNS、通过证书透明度（crt.sh）进行子域名发现、通过Wayback Machine（Internet Archive）进行历史URL恢复、mass-scan可见性（GreyNoise Community）、infostealer-exposure检查（Hudson Rock，免费层，无纯文本凭证）、dork生成、实时dork搜索、URL爬取、BTC/ETH地址查找和被动域名侦察（theHarvester）
- **内置MCP服务器**，原生暴露所有30个工具给Claude Code、Claude Desktop和任何MCP兼容的客户端
- **三个AI后端**，Anthropic Claude（默认）、本地Ollama或任何OpenAI兼容的端点；工具结果来自真正的子进程调用，从不臆造
- **完全异步**，通过`asyncio.gather()`进行并行工具执行，带有硬子进程超时
- **MIT许可**，无嵌入式LLM；自带API密钥或完全离线运行
---
> **法律免责声明**：Clearfront仅用于**合法和授权的使用**。用户完全负责确保其使用符合所有适用的法律和法规。作者不对滥用行为承担任何责任。请参阅[DISCLAIMER.md](DISCLAIMER.md)。
## 什么是Clearfront？
Clearfront是一款开源智能情报代理，具有三个接口：交互式终端REPL、直接CLI和MCP服务器，可暴露给Claude Code、Claude Desktop或任何MCP兼容的客户端，以及基于Web的用户界面。AI层使用Anthropic的原生工具使用API（或本地Ollama模型，或任何OpenAI兼容的端点）：模型在需要工具时发出硬停止，您的代码执行真正的二进制操作，实际输出返回，工具结果中的臆造在结构上是不可能的。
## 安装
```bash
git clone https://github.com/scottmartinanderson/clearfront
cd clearfront
pip install -e .
```
**外部二进制文件**（必须在`PATH`中）：
| 二进制文件 | 目的 | 安装 |
| --- | --- | --- |
| `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` |
如果缺少二进制文件，则相应的工具会返回描述性错误字符串。所有其他工具仍可正常运行。
## 快速入门
```bash
# 交互式AI REPL（默认）
clearfront
# 网页界面
clearfront web
# 直接工具（无AI）
clearfront email target@example.com
```
## 配置
将所有密钥存储在项目根目录的`.env`文件中（复制`.env.example`）。`python-dotenv`会在启动时自动加载它。
| 变量 | 工具 | 必需 | 目的 |
| --- | --- | --- | --- |
| `ANTHROPIC_API_KEY` | AI代理 | 是（或使用Ollama/OpenAI） | Anthropic API密钥 |
| `OPENAI_BASE_URL` | AI代理 | 可选 | OpenAI兼容端点的基准URL（例如`http://localhost:4000/v1`）。设置后，如果未提供`ANTHROPIC_API_KEY`，则使用它作为AI后端（优先于Ollama）。模型必须支持工具/函数调用。 |
| `OPENAI_API_KEY` | AI代理 | 可选 | OpenAI兼容端点的API密钥（本地服务器可能忽略它） |
| `OPENAI_MODEL` | AI代理 | 可选 | 从端点请求的模型名称（默认：`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平台API：个人访问令牌+组织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 req/h，[获取一个](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 req/月）。 |
| `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包：**
| 包 | 目的 | 安装 |
| --- | --- | --- |
| `ollama` | 本地LLM后端（无API密钥） | `pip install ollama` *(还需安装[Ollama运行时](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` |
## 工具
| 工具 | 支持 | 调查内容 |
| --- | --- | --- |
| `search_email` | holehe | 与电子邮件地址相关的社交账户 |
| `search_username` | sherlock | 300+平台上的用户名存在情况 |
| `search_breach` | HaveIBeenPwned v3 API | 数据泄露暴露 |
| `search_whois` | python-whois | 域名注册人和DNS信息 |
| `search_ip` | ipinfo.io | 地理位置、ASN、主机名 |
| `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 | 开放端口、横幅、CVE |
| `search_virustotal` | VirusTotal API v3 | 70+防病毒引擎的判决 |
| `search_ip2location` | IP2Location.io API | 增强的IP情报：VPN/代理/Tor/数据中心标志 |
| `search_censys` | Censys搜索API | 面向互联网的基础设施、证书 |
| `search_abuseipdb` | AbuseIPDB v2 API | IP滥用声誉：置信度、报告、国家、ISP |
| `search_github` | GitHub REST API | 配置文件、仓库、提交发现的电子邮件、用户名/关键词搜索 |
| `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 | 3000+站点上的用户名存在情况 |
| `search_footprint` | SERP（Serper / Bright Data / DuckDuckGo） | 基于搜索的姓名或句柄的足迹发现 |
| `search_gravatar` | Gravatar API | 电子邮件的公共Gravatar配置文件：头像、显示名称、链接账户 |
| `search_emailrep` | EmailRep.io | 电子邮件声誉和足迹总结 |
| `search_hudsonrock` | Hudson Rock Cavalier（免费） | 电子邮件或用户名的信息窃取者暴露检查（无纯文本凭证） |
| `search_exif` | exiftool | EXIF / IPTC / XMP元数据和本地文件中的嵌入式GPS |
| `search_crypto` | 公共链API | Bitcoin / Ethereum地址摘要：余额、交易次数 |
| `search_harvester` | theHarvester | 被动域名侦察：电子邮件、子域名、主机 |
| `search_exposure` | 内置（复合） | IP的基础设施工具的自我暴露报告 |
## 接口
### 交互式REPL
运行`clearfront`时不带任何参数即可启动AI驱动的REPL。输入目标（电子邮件、用户名、域名、IP地址或名称）或问题；代理决定运行哪些工具，根据发现结果链接它们，并编译报告。
**REPL命令：** `<target>`、`clear`、`save`、`tools`、`config`、`history`、`help`、`exit` / Ctrl-D.
所有会话自动保存到`~/.clearfront/history/`。使用`clearfront history`浏览。
### 网页界面
```bash
pip install "clearfront[web]"
clearfront web
# 自动打开http://localhost:8080
```
基于浏览器的AI聊天，带有流式工具输出、内联结果卡和浅色/深色主题切换。支持使用Ollama或任何OpenAI兼容的端点进行完全本地推理（使用本地后端时不需要Anthropic API密钥）。
控制台完全在您的机器上运行，默认绑定到`127.0.0.1`。选择您的后端并在设置中粘贴您自己的密钥；您的密钥和您调查的目标永远不会触及我们的服务器。截图位于[`media/screenshots/`](media/screenshots/)。
### MCP服务器
将所有30个工具暴露给任何MCP兼容的AI客户端。
**Claude Code：**
```bash
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`:
```json
{
"mcpServers": {
"clearfront": {
"command": "python",
"args": ["/absolute/path/to/clearfront/mcp_server.py"]
}
}
}
```
## Docker
```bash
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参考
| 标志/子命令 | 描述 |
| --- | --- |
| `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配置文件/仓库/电子邮件发现 |
| `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而不是stdout（原始；与`--json`结合使用以生成JSON文件） |
| `--provider {anthropic,ollama,openai}` | AI提供者（默认：`anthropic`） |
| `--ollama-model MODEL` | Ollama模型名称（默认：`llama3.2`） |
| `--ollama-host URL` | Ollama服务器URL（默认：`http://localhost:11434`） |
| `--openai-base-url URL` | OpenAI兼容端点基准URL（env：`OPENAI_BASE_URL`） |
| `--openai-model MODEL` | 从端点请求的模型（env：`OPENAI_MODEL`） |
| `--openai-api-key KEY` | 端点的API密钥（env：`OPENAI_API_KEY`） |
| `--no-pdf` | 禁止自动生成PDF |
## 贡献
欢迎提交问题和拉取请求。参阅[CONTRIBUTING.md](CONTRIBUTING.md)了解开发工作流程和编码约定。请阅读[DISCLAIMER.md](DISCLAIMER.md)后再贡献。
## 许可证
Clearfront在[MIT License](./LICENSE)下开源。
捆绑的用户名数据集`clearfront/tools/data/wmn-data-unique.json`是[WhatsMyName](https://github.com/WebBreacher/WhatsMyName)的过滤适配，由Micah Hoffman使用[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).*
