{
  "markdown": "<!-- mcp-name: sh.clearfront/clearfront -->\n\n<div align=\"center\">\n  <h1>Clearfront</h1>\n  <p><strong>Open-source AI intelligence on your digital footprint.</strong></p>\n  <p>Clearfront, also known as Clearfront OSINT, is a free and open-source OSINT agent. Give it an email, username, domain, IP, or name, and its AI security analyst scans 3,400+ public data sources in one sweep, then returns a calibrated report and an interactive evidence graph. Check your own exposure, or investigate an authorized target. It runs locally with your own API keys and sends nothing to us.</p>\n  <p>Interactive REPL · CLI · local web console · MCP server · agent skill. Powered by Anthropic Claude, a local Ollama model, or any OpenAI-compatible endpoint.</p>\n</div>\n\n<div align=\"center\">\n\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square)](https://www.python.org/)\n[![License MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)\n[![MCP](https://img.shields.io/badge/protocol-MCP-blueviolet?style=flat-square)](https://modelcontextprotocol.io/)\n[![Version](https://img.shields.io/badge/version-2.7.3-informational?style=flat-square)](CHANGELOG.md)\n\n**[clearfront.sh](https://clearfront.sh)** · [Disclaimer](./DISCLAIMER.md)\n\n</div>\n\n- **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)\n- **MCP server built in**, expose all 30 tools natively to Claude Code, Claude Desktop, and any MCP-compatible client\n- **Three AI backends**, Anthropic Claude (default), local Ollama, or any OpenAI-compatible endpoint; tool results come from real subprocess calls, never hallucinated\n- **Fully async**, parallel tool execution via `asyncio.gather()` with hard subprocess timeouts\n- **MIT licensed**, no embedded LLM; bring your own API key or run fully offline\n\n---\n\n> **Legal Disclaimer**: Clearfront is intended for **legal and authorized use only**.\n> Users are solely responsible for ensuring their use complies with all applicable laws and regulations.\n> The authors accept no liability for misuse. See [DISCLAIMER.md](DISCLAIMER.md).\n\n## What is Clearfront?\n\nClearfront 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.\n\n## Installation\n\n```bash\npip install clearfront\n```\n\nOr from source, if you want to modify it:\n\n```bash\ngit clone https://github.com/scottmartinanderson/clearfront\ncd clearfront\npip install -e .\n```\n\n**External binaries** (must be in `PATH`):\n\n| Binary | Purpose | Install |\n|--------|---------|---------|\n| `holehe` | Email account enumeration | `pip install holehe` |\n| `sherlock` | Username enumeration (300+ platforms) | `pip install sherlock-project` |\n| `sublist3r` | Subdomain enumeration | `pip install sublist3r` |\n| `phoneinfoga` | Phone number intelligence | [Download binary](https://github.com/sundowndev/phoneinfoga/releases) |\n| `theHarvester` | Passive domain recon (emails/subdomains) | `pip install git+https://github.com/laramies/theHarvester.git` |\n\nIf a binary is absent, the corresponding tool returns a descriptive error string. All other tools remain operational.\n\n## Quick Start\n\n```bash\n# Interactive AI REPL (default)\nclearfront\n\n# Web interface\nclearfront web\n\n# Direct tool (no AI)\nclearfront email target@example.com\n```\n\n## Configuration\n\nStore all keys in a `.env` file at the project root (copy `.env.example`). `python-dotenv` loads it automatically at startup.\n\n| Variable | Tool | Required | Purpose |\n|----------|------|----------|---------|\n| `ANTHROPIC_API_KEY` | AI agent | Yes (or use Ollama / OpenAI) | Anthropic API key |\n| `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. |\n| `OPENAI_API_KEY` | AI agent | Optional | API key for the OpenAI-compatible endpoint (local servers may ignore it) |\n| `OPENAI_MODEL` | AI agent | Optional | Model name to request from the endpoint (default: `gpt-4o-mini`) |\n| `HIBP_API_KEY` | `search_breach` | Optional | HaveIBeenPwned v3, [get one](https://haveibeenpwned.com/API/Key) |\n| `IPINFO_TOKEN` | `search_ip` | Optional | ipinfo.io higher rate limits |\n| `SHODAN_API_KEY` | `search_shodan` | Optional | Shodan API, [get one](https://account.shodan.io) |\n| `VIRUSTOTAL_API_KEY` | `search_virustotal` | Optional | VirusTotal API v3, [get one](https://www.virustotal.com/gui/my-apikey) |\n| `IP2LOCATION_API_KEY` | `search_ip2location` | Optional | IP2Location.io enhanced IP intelligence, [get one](https://www.ip2location.io/pricing) |\n| `CENSYS_PAT` + `CENSYS_ORG_ID` | `search_censys` | Optional | Censys Platform API: Personal Access Token + Organization ID, [get one](https://platform.censys.io) |\n| `ABUSEIPDB_API_KEY` | `search_abuseipdb` | Optional | AbuseIPDB v2, [get one](https://www.abuseipdb.com/account/api) |\n| `GITHUB_TOKEN` | `search_github` | Optional | GitHub API, raises rate limit from 60 to 5000 req/h, [get one](https://github.com/settings/tokens) |\n| `SERPER_API_KEY` | `search_dorks_live`, `search_footprint` | Optional | Serper.dev Google SERP API, the preferred SERP backend (~$1/1k, 2,500 free), [get one](https://serper.dev). |\n| `BRIGHTDATA_API_KEY` | `search_dorks_live`, `scrape_url` | Optional | Bright Data API key, [get one](https://get.brightdata.com/8ygvxztgo5dr) (free tier: 5,000 req/month). |\n| `BRIGHTDATA_SERP_ZONE` | `search_dorks_live` | Optional | Your Bright Data SERP API zone name (e.g. `serp_api1`). |\n| `BRIGHTDATA_UNLOCKER_ZONE` | `scrape_url` | Optional | Your Bright Data Web Unlocker zone name (e.g. `web_unlocker1`). |\n\nThe Bright Data link above is a referral link; signing up through it supports Clearfront at no extra cost to you.\n\n**Optional Python packages:**\n\n| Package | Purpose | Install |\n|---------|---------|---------|\n| `ollama` | Local LLM backend (no API key) | `pip install ollama` *(also install the [Ollama runtime](https://ollama.com))* |\n| `openai` | OpenAI-compatible backend for the REPL/CLI (`--provider openai`) | `pip install \"clearfront[openai]\"` |\n| `shodan` | Shodan API client | `pip install shodan` |\n| `reportlab` | PDF report export | `pip install reportlab` |\n| `censys` | Censys API client | `pip install censys` |\n\n## Tools\n\n| Tool | Powered by | What it investigates |\n|------|-----------|---------------------|\n| `search_email` | holehe | Social accounts linked to an email address |\n| `search_username` | sherlock | Username presence across 300+ platforms |\n| `search_breach` | HaveIBeenPwned v3 API | Data breach exposure |\n| `search_whois` | python-whois | Domain registrant and DNS info |\n| `search_ip` | ipinfo.io | Geolocation, ASN, hostname |\n| `search_domain` | sublist3r | Subdomain enumeration |\n| `search_crt` | crt.sh | Subdomains from certificate transparency (keyless, passive) |\n| `search_wayback` | Internet Archive | Historical/deleted URLs archived under a domain (keyless, passive) |\n| `search_greynoise` | GreyNoise Community | Mass-scanner noise vs. targeted actor for an IP (free, 50/week) |\n| `generate_dorks` | built-in | 12 targeted Google dork URLs (no network calls) |\n| `search_paste` | psbdmp.ws | Pastebin dump mentions |\n| `search_phone` | phoneinfoga | Carrier, country, line type |\n| `search_shodan` | Shodan API | Open ports, banners, CVEs |\n| `search_virustotal` | VirusTotal API v3 | Verdict from 70+ antivirus engines |\n| `search_ip2location` | IP2Location.io API | Enhanced IP intel: VPN/Proxy/Tor/datacenter flags |\n| `search_censys` | Censys Search API | Internet-facing infrastructure, certificates |\n| `search_abuseipdb` | AbuseIPDB v2 API | IP abuse reputation: confidence score, reports, country, ISP |\n| `search_github` | GitHub REST API | Profile, repos, commit-discovered emails, username/keyword search |\n| `search_dns` | dnspython (built-in) | A/AAAA/MX/NS/TXT/CNAME/SOA records; SPF, DMARC, DKIM analysis |\n| `search_dorks_live` | Bright Data SERP API | Live Google search results for dork queries (title, URL, snippet) |\n| `scrape_url` | Bright Data Web Unlocker | Fetch any URL bypassing Cloudflare/CAPTCHA, returns clean Markdown |\n| `search_maigret` | maigret | Username presence across 3,400+ sites |\n| `search_footprint` | SERP (Serper / Bright Data / DuckDuckGo) | Search-based footprint discovery for a name or handle |\n| `search_gravatar` | Gravatar API | Public Gravatar profile for an email: avatar, display name, linked accounts |\n| `search_emailrep` | EmailRep.io | Email reputation and footprint summary |\n| `search_hudsonrock` | Hudson Rock Cavalier (free) | Infostealer-exposure check for an email or username (no plaintext credentials) |\n| `search_exif` | exiftool | EXIF / IPTC / XMP metadata and embedded GPS from a local file |\n| `search_crypto` | public chain APIs | Bitcoin / Ethereum address summary: balance, transaction count |\n| `search_harvester` | theHarvester | Passive domain recon: emails, subdomains, hosts |\n| `search_exposure` | built-in (composite) | Self-exposure report for an IP across the infrastructure tools |\n\n## Interfaces\n\n### Interactive REPL\n\nRun `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.\n\n**REPL commands:** `<target>`, `clear`, `save`, `tools`, `config`, `history`, `help`, `exit` / Ctrl-D.\n\nAll sessions are auto-saved to `~/.clearfront/history/`. Browse with `clearfront history`.\n\n### Web UI\n\n```bash\npip install \"clearfront[web]\"\nclearfront web\n# Opens http://localhost:8080 automatically\n```\n\nBrowser-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).\n\nThe 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/`](media/).\n\n### MCP Server\n\nExpose all 30 tools to any MCP-compatible AI client.\n\n**Claude Code:**\n\n```bash\nclaude mcp add clearfront python /absolute/path/to/clearfront/mcp_server.py\nclaude mcp list\n```\n\n**Claude Desktop**, add to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"clearfront\": {\n      \"command\": \"python\",\n      \"args\": [\"/absolute/path/to/clearfront/mcp_server.py\"]\n    }\n  }\n}\n```\n\n### Agent Skill\n\n[`skills/clearfront-osint`](skills/clearfront-osint/SKILL.md) teaches an agent\nhow to drive Clearfront: which approach fits a given request, the direct\nsubcommands, how to read the confidence ratings, and the authorized-use rules.\nIt follows the [Agent Skills](https://agentskills.io) open standard, so it works\nin Claude Code, Cursor, Codex, Copilot, VS Code, Gemini, Windsurf, Zed and the other\nskills-compatible clients.\n\n```bash\nnpx skills add scottmartinanderson/clearfront\n```\n\nInstall Clearfront itself as well (`pip install clearfront`); the skill is the\ninstructions, not the tool. Use the skill when you want the agent to decide how\nto run a sweep, and the MCP server above when you want it calling the 30 tools\ndirectly.\n\n## Docker\n\n```bash\ndocker compose up --build\ndocker compose run --rm clearfront email target@example.com --json\n```\n\nSet `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.\n\n## CLI Reference\n\n| Flag / Subcommand | Description |\n|---|---|\n| `clearfront` | Interactive AI REPL (default) |\n| `clearfront web [--port N] [--no-browser]` | Launch browser UI |\n| `clearfront email ADDRESS [-t N]` | Direct email scan |\n| `clearfront username HANDLE [-t N]` | Direct username scan |\n| `clearfront shodan QUERY [-t N]` | Shodan lookup |\n| `clearfront virustotal TARGET [-t N]` | VirusTotal lookup |\n| `clearfront censys TARGET [-t N]` | Censys lookup |\n| `clearfront ip2location IP [-t N]` | IP2Location lookup |\n| `clearfront abuseipdb IP [-t N]` | AbuseIPDB reputation check |\n| `clearfront github QUERY [-t N]` | GitHub profile/repo/email discovery |\n| `clearfront dns DOMAIN [-t N]` | DNS records + email security analysis |\n| `clearfront multi TARGETS` | Parallel multi-target investigation (max 10) |\n| `clearfront graph TARGET [-o PATH] [--format graphml\\|json\\|mermaid\\|all]` | Auto-pivot and export the entity correlation graph (GraphML/JSON/Mermaid) |\n| `clearfront history [--all] [open N] [clear]` | View/manage REPL session history |\n| `-v, --verbose` | Enable debug logging to stderr |\n| `-t, --timeout N` | Override subprocess timeout (seconds) |\n| `--api-key KEY` | Anthropic API key (overrides env var) |\n| `--parallel` | Run complementary tools concurrently |\n| `--json` | Output results as structured JSON |\n| `-o, --output FILE` | Write results to FILE instead of stdout (raw; combine with `--json` for a JSON file) |\n| `--provider {anthropic,ollama,openai}` | AI provider (default: `anthropic`) |\n| `--ollama-model MODEL` | Ollama model name (default: `llama3.2`) |\n| `--ollama-host URL` | Ollama server URL (default: `http://localhost:11434`) |\n| `--openai-base-url URL` | OpenAI-compatible endpoint base URL (env: `OPENAI_BASE_URL`) |\n| `--openai-model MODEL` | Model to request from the endpoint (env: `OPENAI_MODEL`) |\n| `--openai-api-key KEY` | API key for the endpoint (env: `OPENAI_API_KEY`) |\n| `--no-pdf` | Disable automatic PDF generation |\n\n## Contributing\n\nIssues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and coding conventions. Please read [DISCLAIMER.md](DISCLAIMER.md) before contributing.\n\n## License\n\nClearfront is open source under the [MIT License](./LICENSE).\n\nThe bundled username dataset `clearfront/tools/data/wmn-data-unique.json` is a filtered\nadaptation of the [WhatsMyName](https://github.com/WebBreacher/WhatsMyName) project\nby Micah Hoffman, used under the [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)\nlicense; that file (and adaptations of it) remains under CC BY-SA 4.0. See\n[`clearfront/tools/data/NOTICE`](./clearfront/tools/data/NOTICE).\n\n---\n\n*For authorized security research only. See [DISCLAIMER.md](DISCLAIMER.md).*\n",
  "bytes": 15561,
  "sha": "1291e0fc2078afc04bd4ee5463e2041d0d9b3dd8b81412e65b9b70f29377458c",
  "repo_slug": "scottmartinanderson/clearfront",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_sh_clearfront_clearfront_46dfecef/readme"
}