arxhr007/Aliens_eye

Aliens Eye – AI‑OSINT Username Scanner

What it is – A Python command‑line tool that checks whether a given username exists on more than 840 social‑media, forum and other public platforms. It combines a lightweight logistic‑regression model with a set of handcrafted heuristics (HTTP status, DOM clues, OpenGraph tags, etc.) to decide if a profile is Found, Maybe or Not Found. The scanner runs asynchronously, can resume interrupted jobs, and can expose its results to LLM agents via a tiny MCP server.

Why it matters – Traditional OSINT username look‑ups rely on simple HTTP‑status checks, which miss sites that return generic pages or use JavaScript. By blending ML with 30 engineered signals, Aliens Eye improves precision/recall and can also cluster accounts that appear to belong to the same person (avatar hash, bio similarity, shared links).

Key features

• Massive coverage – 840+ sites, each defined by a JSON URL template in sites.d/.
• Hybrid detection – heuristic scoring + shipped logistic‑regression model (no heavy dependencies at runtime).
• Profile extraction – pulls display name, bio and avatar via OpenGraph/JSON‑LD or site‑specific CSS.
• Cross‑site correlation – optional --correlate groups likely‑same‑person profiles.
• Recursive expansion – follow usernames found in bios (--recurse-depth).
• Domain availability – checks if <username>.com, .io, etc. are registered.
• Watch mode – periodic rescans with webhook notifications.
• Resumable scans – checkpoint file (--resume).
• Rich terminal UI – live progress tables via rich; optional interactive TUI browser.
• MCP server – aliens_eye serve lets LLM agents query the scanner.
• Proxy/Tor support, site filtering, NSFW exclusion, and a Playwright fallback for JS‑heavy pages.
• Export formats – JSON, CSV, HTML, Markdown, PDF, plus graph files (GEXF, Mermaid, Maltego CSV).

Typical workflow

# Quick check of a single handle
aliens_eye alice

# Full‑featured scan with correlation and domain checks
aliens_eye alice --correlate --domains --format all --output results

# Run as a service for an LLM‑driven workflow
aliens_eye serve   # then call the MCP endpoint from your agent

Installation – pip install aliens-eye (extras for Playwright, training, PDF, TUI, or MCP). Docker image is also provided.

How detection works

1. Build a 30‑dimensional feature vector from the HTTP response (status buckets, timing, redirects, DOM cues, structured‑data tags, etc.).
2. Heuristic engine scores the vector.
3. The bundled logistic‑regression model votes; the two scores are blended into a probability that maps to Found / Maybe / Not Found.
4. If the model file is missing, the tool falls back to heuristics only.

Retraining – Users can collect a labeled dataset (aliens_eye train collect), fit a new model (aliens_eye train fit), and supply it with --model.

Use cases

• Open‑source intelligence investigations (tracking a handle across platforms).
• Brand monitoring – detect impersonation or squatted usernames.
• Security assessments – enumerate an employee’s public footprint.
• Feeding LLM agents with up‑to‑date OSINT data via the MCP server.

Limitations / cautions

• Accuracy depends on the quality of site templates and the ML model; false positives/negatives are reported via the selfcheck command.
• Scanning many sites quickly may hit rate limits or trigger anti‑scraping defenses; the tool includes a configurable delay but cannot guarantee compliance with every site’s TOS.
• Legal/ethical responsibility lies with the user – the repo includes a disclaimer that the tool is for legitimate research only.
• The ML model is a simple logistic regression; it is not a deep‑learning detector and may struggle on sites with heavily dynamic content unless Playwright is enabled.

Contributing – Add new site definitions to src/aliens_eye/data/sites.json or drop JSON files into sites.d/. Improve the ground‑truth set, submit model refinements, or add export plugins. Tests run with pytest; code style checked with ruff.

---

All information above is taken directly from the repository’s README; no external assumptions have been added.