io.github.sudohnim/eidolon
Privacy-first OSINT scanner: breaches, credentials, Shodan, username sweep. Scored PDF report.
Open source Open in the app JSON README (API)
About
Privacy-first OSINT scanner: breaches, credentials, Shodan, username sweep. Scored PDF report.
Details
- Kind
- MCP servers
- Topic
- Security & identity
- Publisher
- sudohnim
- Origin
- official
- Category
- ferramentas
- Transport
- desconhecido
- Version
- 0.1.0
- Stars
- 1
- Last push
- 2026-06-26T03:42:34Z
- Repository state
- ativo
- Language
- Python
- License
- AGPL-3.0
- Added
- 2026-08-29 04:01:29
- Updated
- 2026-08-29 04:01:29
- Origin id
io.github.sudohnim/eidolon
README
<p align="center">
<img src="assets/logo.png" alt="Eidolon" width="160">
</p>
# Eidolon
Eidolon is a privacy-first approach to finding and understanding your digital footprint. The stack uses OSINT tools to gather information based on your search parameters, then a **local** LLM compiles it into a report. The LLM runs on your machine, so no data ever reaches an external service or leaves your box — you own your data.
## What it does
- Aggregates ~25 OSINT sources — breaches, leaked credentials, data brokers, account enumeration, public records, phone/email intel, exposed hosts — into a single risk report.
- Maps findings to **MITRE ATT&CK** so you see what an attacker could actually do with what's exposed.
- Flags **AI-training exposure** (which platforms may train on your data, and how to opt out).
- Risk scoring and the leaked-credential dossier are **deterministic** — built from scan state, not the LLM — so the report survives an LLM hiccup. The model only writes narrative.
- Outputs Markdown, PDF, and JSON.
## MCP-native
Eidolon runs as an [MCP](https://modelcontextprotocol.io) server, so you can drive it from any MCP client (Claude Desktop, Claude Code) — scan a target, list past scans, and read reports conversationally. It runs locally over stdio; your data never leaves the box.
Tools: `scan_target`, `scan_status`, `list_scans`, `get_report`, `reveal_credentials`. A scan takes minutes, so `scan_target` returns a `scan_id` immediately and runs in the background — poll `scan_status(scan_id)` until it reports `done`, then `get_report(scan_id)`. The leaked-credential dossier (plaintext passwords from breach dumps) is **redacted by default** and only returned when you explicitly call `reveal_credentials`.
## Requirements
Everything below is **optional** — Eidolon runs with whatever you give it and tells you, per source, what it couldn't check (no token) versus what it checked and found nothing.
- Python 3.11+ and [uv](https://docs.astral.sh/uv/) (required)
- [Ollama](https://ollama.com) for the local LLM narrative: `ollama pull llama3.1:8b` — if it's down, the report is still produced deterministically (just no written narrative).
- A running [SpiderFoot](https://github.com/smicallef/spiderfoot) instance — skipped if unreachable.
- API keys — see [`.env.example`](.env.example). Each unlocks one data source and **skips cleanly** if absent (the report says "not checked — set X"). A scan with no keys is sparse but still runs.
**New here? Start with the [Setup & Configuration guide](docs/SETUP_CHECKLIST.md)** — which keys to get, what each one costs, and what it unlocks.
## Quickstart
```bash
git clone https://github.com/sudohnim/eidolon && cd eidolon
uv sync
cp .env.example .env # fill in your keys
# scan yourself from the CLI
uv run eidolon --email you@example.com
# or run the MCP server (stdio)
uv run eidolon-mcp
```
### Use from Claude Desktop
**Option 1 — from a local clone** (loads `.env` from `cwd`):
```json
{
"mcpServers": {
"eidolon": {
"command": "uv",
"args": ["run", "eidolon-mcp"],
"cwd": "/absolute/path/to/eidolon"
}
}
}
```
**Option 2 — from PyPI via `uvx`** (recommended, no clone needed). Pass your keys in the `env` block:
```json
{
"mcpServers": {
"eidolon": {
"command": "uvx",
"args": ["--from", "eidolon-osint", "eidolon-mcp"],
"env": {
"HIBP_API_KEY": "...",
"DEHASHED_API_KEY": "...",
"OLLAMA_HOST": "http://localhost:11434"
}
}
}
}
```
**Option 3 — straight from GitHub** (pre-release / latest commit):
```json
{
"mcpServers": {
"eidolon": {
"command": "uvx",
"args": ["--from", "git+https://github.com/sudohnim/eidolon", "eidolon-mcp"],
"env": {
"HIBP_API_KEY": "...",
"DEHASHED_API_KEY": "...",
"OLLAMA_HOST": "http://localhost:11434"
}
}
}
}
```
Add only the keys you have — the rest skip cleanly. Then ask Claude to "scan my email"; it calls `scan_target`, polls `scan_status`, and reads the report.
## How it works
A LangGraph pipeline: `intake → wave 1 scans → wave 2 scans → MITRE mapping → correlation → analysis → report`. Both the CLI and the MCP server call the same `run_scan()` core; reads go through a small repository layer. See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the architecture and where it's headed (stateful history, continuous monitoring).
## Intended use
Eidolon is for scanning **yourself**, or targets you are **explicitly authorized** to assess (authorized security testing, your own footprint). It surfaces real secrets, including plaintext passwords from breach dumps. **Do not use it to profile or surveil people without their consent.** You are responsible for complying with the terms of the data sources you configure and with applicable law.
## License
[AGPL-3.0](LICENSE). If you run a modified version as a network service, you must offer users its source.