clearfront.sh · Disclaimer
- 30 modular tools, email, username (sherlock + WhatsMyName), broad username discovery across 3,400+ sites (maigret), search-based footprint discovery, IP, IP self-exposure report, domain, WHOIS, breach, Gravatar profile, EmailRep reputation, phone, paste, EXIF/GPS metadata, Shodan, VirusTotal, Censys, IP2Location, AbuseIPDB, GitHub (profile + public code/secret exposure), DNS, subdomain discovery via certificate transparency (crt.sh), historical URL recovery via the Wayback Machine (Internet Archive), mass-scan visibility (GreyNoise Community), infostealer-exposure check (Hudson Rock, free tier, no plaintext credentials), dork generation, live dork search, URL scraping, BTC/ETH address lookup, and passive domain recon (theHarvester)
- MCP server built in, expose all 30 tools natively to Claude Code, Claude Desktop, and any MCP-compatible client
- Three AI backends, Anthropic Claude (default), local Ollama, or any OpenAI-compatible endpoint; tool results come from real subprocess calls, never hallucinated
- Fully async, parallel tool execution via
asyncio.gather() with hard subprocess timeouts
- MIT licensed, no embedded LLM; bring your own API key or run fully offline
Legal Disclaimer: Clearfront is intended for legal and authorized use only.
Users are solely responsible for ensuring their use complies with all applicable laws and regulations.
The authors accept no liability for misuse. See DISCLAIMER.md.
What is Clearfront?
Clearfront is an AI agent for Open Source Intelligence with five interfaces: an interactive terminal REPL, a direct CLI, a browser-based web console, an MCP server exposable to Claude Code, Claude Desktop or any MCP-compatible client, and an agent skill for any client following the Agent Skills standard. The AI layer uses Anthropic's native tool use API (or a local Ollama model, or any OpenAI-compatible endpoint): the model issues hard stops when it needs a tool, your code executes the real binary, the actual output goes back, hallucination in tool results is structurally impossible.
Installation
pip install clearfront
Or from source, if you want to modify it:
git clone https://github.com/scottmartinanderson/clearfront
cd clearfront
pip install -e .
External binaries (must be in PATH):
| Binary | Purpose | Install |
|---|
holehe | Email account enumeration | pip install holehe |
sherlock | Username enumeration (300+ platforms) | pip install sherlock-project |
sublist3r | Subdomain enumeration | pip install sublist3r |
phoneinfoga | Phone number intelligence | Download binary |
theHarvester | Passive domain recon (emails/subdomains) | pip install git+https://github.com/laramies/theHarvester.git |
If a binary is absent, the corresponding tool returns a descriptive error string. All other tools remain operational.
Quick Start
# Interactive AI REPL (default)
clearfront
# Web interface
clearfront web
# Direct tool (no AI)
clearfront email target@example.com
Configuration
Store all keys in a .env file at the project root (copy .env.example). python-dotenv loads it automatically at startup.
| Variable | Tool | Required | Purpose |
|---|
ANTHROPIC_API_KEY | AI agent | Yes (or use Ollama / OpenAI) | Anthropic API key |
OPENAI_BASE_URL | AI agent | Optional | Base URL of an OpenAI-compatible endpoint (e.g. http://localhost:4000/v1). When set and ANTHROPIC_API_KEY is absent, it is used as the AI backend (takes precedence over Ollama). The model must support tool/function calling. |
OPENAI_API_KEY | AI agent | Optional | API key for the OpenAI-compatible endpoint (local servers may ignore it) |
OPENAI_MODEL | AI agent | Optional | Model name to request from the endpoint (default: gpt-4o-mini) |
HIBP_API_KEY | search_breach | Optional | HaveIBeenPwned v3, get one |
IPINFO_TOKEN | search_ip | Optional | ipinfo.io higher rate limits |
SHODAN_API_KEY | search_shodan | Optional | Shodan API, get one |
VIRUSTOTAL_API_KEY | search_virustotal | Optional | VirusTotal API v3, get one |
IP2LOCATION_API_KEY | search_ip2location | Optional | IP2Location.io enhanced IP intelligence, get one |
CENSYS_PAT + CENSYS_ORG_ID | search_censys | Optional | Censys Platform API: Personal Access Token + Organization ID, get one |
ABUSEIPDB_API_KEY | search_abuseipdb | Optional | AbuseIPDB v2, get one |
The Bright Data link above is a referral link; signing up through it supports Clearfront at no extra cost to you.
Optional Python packages:
| Package | Purpose | Install |
|---|
ollama | Local LLM backend (no API key) | pip install ollama (also install the Ollama runtime) |
openai | OpenAI-compatible backend for the REPL/CLI (--provider openai) | pip install "clearfront[openai]" |
shodan | Shodan API client | pip install shodan |
reportlab | PDF report export | pip install reportlab |
censys | Censys API client | pip install censys |
Tools
| Tool | Powered by | What it investigates |
|---|
search_email | holehe | Social accounts linked to an email address |
search_username | sherlock | Username presence across 300+ platforms |
search_breach | HaveIBeenPwned v3 API | Data breach exposure |
search_whois | python-whois | Domain registrant and DNS info |
search_ip | ipinfo.io | Geolocation, ASN, hostname |
search_domain | sublist3r | Subdomain enumeration |
search_crt | crt.sh | Subdomains from certificate transparency (keyless, passive) |
search_wayback | Internet Archive | Historical/deleted URLs archived under a domain (keyless, passive) |
search_greynoise | GreyNoise Community | Mass-scanner noise vs. targeted actor for an IP (free, 50/week) |
generate_dorks | built-in | 12 targeted Google dork URLs (no network calls) |
search_paste | psbdmp.ws | Pastebin dump mentions |
search_phone | phoneinfoga | Carrier, country, line type |
search_shodan | Shodan API | Open ports, banners, CVEs |
search_virustotal | VirusTotal API v3 | Verdict from 70+ antivirus engines |
search_ip2location | IP2Location.io API | Enhanced IP intel: VPN/Proxy/Tor/datacenter flags |
search_censys | Censys Search API | Internet-facing infrastructure, certificates |
search_abuseipdb | AbuseIPDB v2 API | IP abuse reputation: confidence score, reports, country, ISP |
search_github | GitHub REST API | Profile, repos, commit-discovered emails, username/keyword search |
|
Interfaces
Interactive REPL
Run clearfront with no arguments to start the AI-powered REPL. Type a target (email, username, domain, IP, name) or a question; the agent decides which tools to run, chains them on findings, and compiles a report.
REPL commands: <target>, clear, save, tools, config, history, help, exit / Ctrl-D.
All sessions are auto-saved to ~/.clearfront/history/. Browse with clearfront history.
Web UI
pip install "clearfront[web]"
clearfront web
# Opens http://localhost:8080 automatically
Browser-based AI chat with streaming tool output, inline result cards, and a light/dark theme toggle. Supports fully local inference via Ollama or any OpenAI-compatible endpoint (no Anthropic API key required when using a local backend).
The console runs entirely locally and binds to 127.0.0.1 by default. Choose your backend and paste your own key in Settings; your keys and the targets you investigate never touch our servers. Screenshots are in media/.
MCP Server
Expose all 30 tools to any MCP-compatible AI client.
Claude Code:
claude mcp add clearfront python /absolute/path/to/clearfront/mcp_server.py
claude mcp list
Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"clearfront": {
"command": "python",
"args": ["/absolute/path/to/clearfront/mcp_server.py"]
}
}
}
Agent Skill
skills/clearfront-osint teaches an agent
how to drive Clearfront: which approach fits a given request, the direct
subcommands, how to read the confidence ratings, and the authorized-use rules.
It follows the Agent Skills open standard, so it works
in Claude Code, Cursor, Codex, Copilot, VS Code, Gemini, Windsurf, Zed and the other
skills-compatible clients.
npx skills add scottmartinanderson/clearfront
Install Clearfront itself as well (pip install clearfront); the skill is the
instructions, not the tool. Use the skill when you want the agent to decide how
to run a sweep, and the MCP server above when you want it calling the 30 tools
directly.
Docker
docker compose up --build
docker compose run --rm clearfront email target@example.com --json
Set ANTHROPIC_API_KEY (and optionally HIBP_API_KEY, IPINFO_TOKEN) in a .env file or export them before running. Reports persist to ./reports/ via a volume mount.
CLI Reference
| Flag / Subcommand | Description |
|---|
clearfront | Interactive AI REPL (default) |
clearfront web [--port N] [--no-browser] | Launch browser UI |
clearfront email ADDRESS [-t N] | Direct email scan |
clearfront username HANDLE [-t N] | Direct username scan |
clearfront shodan QUERY [-t N] | Shodan lookup |
clearfront virustotal TARGET [-t N] | VirusTotal lookup |
clearfront censys TARGET [-t N] | Censys lookup |
clearfront ip2location IP [-t N] | IP2Location lookup |
clearfront abuseipdb IP [-t N] | AbuseIPDB reputation check |
clearfront github QUERY [-t N] | GitHub profile/repo/email discovery |
clearfront dns DOMAIN [-t N] | DNS records + email security analysis |
clearfront multi TARGETS | Parallel multi-target investigation (max 10) |
clearfront graph TARGET [-o PATH] [--format graphml|json|mermaid|all] | Auto-pivot and export the entity correlation graph (GraphML/JSON/Mermaid) |
clearfront history [--all] [open N] [clear] | View/manage REPL session history |
-v, --verbose | Enable debug logging to stderr |
-t, --timeout N | Override subprocess timeout (seconds) |
--api-key KEY | Anthropic API key (overrides env var) |
--parallel | Run complementary tools concurrently |
--json | Output results as structured JSON |
-o, --output FILE | Write results to FILE instead of stdout (raw; combine with --json for a JSON file) |
--provider {anthropic,ollama,openai} | AI provider (default: anthropic) |
--ollama-model MODEL |
Contributing
Issues and pull requests are welcome. See CONTRIBUTING.md for the development workflow and coding conventions. Please read DISCLAIMER.md before contributing.
License
Clearfront is open source under the MIT License.
The bundled username dataset clearfront/tools/data/wmn-data-unique.json is a filtered
adaptation of the WhatsMyName project
by Micah Hoffman, used under the CC BY-SA 4.0
license; that file (and adaptations of it) remains under CC BY-SA 4.0. See
clearfront/tools/data/NOTICE.
For authorized security research only. See DISCLAIMER.md.
