ALIENS EYE

AI-OSINT Username Scanner

Advanced AI-Powered Social Media Username Finder

Scan 840+ platforms with ML-blended detection

Highlights

• 840+ platforms scanned asynchronously in seconds
• ML + heuristic detection — a trained model blended with 30 structural signals (HTTP status, DOM shape, keywords, fingerprints) instead of naive status-code checks
• Profile extraction — display name, bio, and avatar pulled from each hit (OpenGraph / JSON-LD / per-site CSS)
• Cross-site correlation — cluster profiles that look like the same person by avatar hash, bio, shared links, and name (--correlate)
• Recursive expansion — follow linked usernames out of bios and re-scan them (--recurse-depth N)
• Domain check — is <username>.{com,io,net,…} registered and live? (--domains)
• Watch mode — re-scan on an interval and alert on changes, optionally to a webhook (--watch 6h --notify <url>)
• Resumable scans — checkpoint progress and continue after an interruption (--resume file.jsonl)
• Modern terminal UI — live progress, sorted result tables, summary panels (powered by rich); plus an interactive browser (aliens_eye tui, optional extra)
• MCP server — expose scanning to LLM agents (aliens_eye serve, optional extra)
• Proxy & Tor support — --proxy socks5://... or just --tor
• Site filtering — --site github,reddit, --exclude-site, --no-nsfw, plus drop-in sites.d/ plugin site maps
• Calibrated self-check — aliens_eye selfcheck reports precision / recall / F1 / FPR per site
• Reproducible evaluation — record a frozen response corpus once, then replay it for identical metrics run to run (aliens_eye corpus record / selfcheck --corpus)
• Ablations and baselines — aliens_eye eval ablate scores detector configurations with bootstrap confidence intervals; eval external compares against Sherlock / Maigret / WhatsMyName rules on the same stored responses
• Retrainable + active learning — retrain with aliens_eye train, or hand-label uncertain hits with aliens_eye label
• Reports in JSON, CSV, HTML, Markdown, PDF, and graph formats (GEXF, Mermaid, Maltego CSV)
• Playwright fallback for JavaScript-heavy pages (optional extra)

Install

pip install aliens-eye

Optional extras:

pip install "aliens-eye[browser]"   # Playwright fallback for hard pages
python -m playwright install chromium

pip install "aliens-eye[train]"     # scikit-learn, for retraining the ML model
pip install "aliens-eye[correlate]" # Pillow, for avatar-image matching in --correlate
pip install "aliens-eye[pdf]"       # reportlab, for --format pdf
pip install "aliens-eye[tui]"       # textual, for the interactive `tui` browser
pip install "aliens-eye[serve]"     # mcp, for the `serve` MCP server

Or with Docker:

docker build -t aliens-eye .
docker run --rm -it aliens-eye username

From source:

git clone https://github.com/arxhr007/Aliens_eye.git
cd Aliens_eye
pip install -e .

Usage

# Interactive prompts
aliens_eye

# Single username
aliens_eye username

# Multiple usernames
aliens_eye username1 username2

# Advanced scan level (prefix/suffix variations)
aliens_eye username -l advanced

# Only scan specific sites
aliens_eye username --site github,reddit,gitlab

# Skip NSFW sites
aliens_eye username --no-nsfw

# Route through Tor (needs a local Tor daemon)
aliens_eye username --tor

# Any HTTP or SOCKS proxy
aliens_eye username --proxy socks5://127.0.0.1:1080

# Export everything
aliens_eye username --format all --output results

# Heuristics only, no ML
aliens_eye username --no-ml

# Non-interactive preset: quick / full / aggressive
aliens_eye username --profile quick

# Plain output for scripts and CI (no colors/progress)
aliens_eye username --plain

# View results from a previous scan
aliens_eye -r results/username_advanced_20260611_120000.json

# Correlate hits into "likely same person" clusters + check domains
aliens_eye username --correlate --domains

# Follow linked usernames out of found bios and re-scan them
aliens_eye username --recurse-depth 1

# Export a graph of the results (import into Gephi / Maltego / Mermaid)
aliens_eye username --correlate --format gexf,mermaid,maltego

# Investigator PDF with embedded avatars
aliens_eye username --format pdf

# Watch for changes every 6 hours and POST them to a webhook
aliens_eye username --watch 6h --notify https://hooks.example/aliens

# Resume an interrupted scan
aliens_eye username --resume scan.jsonl

# Compare two saved reports
aliens_eye diff results/old.json results/new.json

# Validate detection accuracy (precision / recall / F1 per site)
aliens_eye selfcheck --negatives 2 --report json

# Record a frozen response corpus, then evaluate against it reproducibly
aliens_eye corpus record --out corpus/v1 --split all --negatives 4
aliens_eye corpus stats corpus/v1
aliens_eye selfcheck --split holdout --corpus corpus/v1 --report json

# Compare detector configurations over that corpus, with confidence intervals
aliens_eye eval ablate --corpus corpus/v1 --split holdout

# Compare against Sherlock / Maigret / WhatsMyName rules (fetch their data yourself)
aliens_eye eval external --corpus corpus/v1 --sherlock data.json --whatsmyname wmn-data.json

# Rebuild the ground-truth splits from those projects account lists
aliens_eye eval groundtruth --sherlock data.json --whatsmyname wmn-data.json

# Interactively label uncertain hits into a training set
aliens_eye label results/username_basic_20260611_120000.json --out labeled.csv

# Interactive terminal browser (needs [tui])
aliens_eye tui username

# Run the MCP server for LLM agents (needs [serve])
aliens_eye serve

Custom platforms: drop a { "site_name": "https://site/{}" } JSON file into ./sites.d/ (or the user config dir's sites.d/) and it is merged automatically; --sites-dir DIR adds another location.

How detection works

Every response is converted into a 30-dimensional feature vector: HTTP status buckets, username placement (path/title/meta/canonical), error and profile keywords, DOM structure (images, forms, profile/error CSS classes), structured-data signals (og:type, JSON-LD Person), response timing, redirect counts, and per-site fingerprint matches learned from previous scans.

Two judges then vote:

1. Heuristic engine — weighted scoring over the features
2. ML model — logistic regression trained on labeled scans of real (and deliberately fake) accounts, shipped with the package and running in pure Python (no sklearn needed at runtime)

The blended probability maps to Found / Maybe / Not Found with a confidence percentage. The loaded model supplies both the blend weight and the thresholds — the shipped model uses 0.9 * ml + 0.1 * heuristic, Found above 0.620, Not Found below 0.360. If a model file is missing or invalid, the scanner silently falls back to heuristics with the defaults in core/detector.py (0.4 ML weight, 0.6 / 0.35 thresholds). See WORKING.md for the full table.

Treat Found/Maybe as leads to verify, not as findings. The shipped model was fit on 1,455 samples from 286 platforms and evaluated on 142 platforms it never saw: precision 0.65, recall 0.51, false-positive rate 9% (F1 0.57). It favours fewer false leads over catching every account, and on held-out platforms no configuration -- including this one -- is statistically distinguishable from a plain HTTP-status check on F1.

Retraining the model

pip install "aliens-eye[train]"

# 1. Scan ground-truth accounts + random non-existent usernames to build a dataset
#    (reads the train split only; the eval holdout is never touched)
aliens_eye train collect --out dataset.csv --negatives 4

# 2. Fit and export the model
aliens_eye train fit --data dataset.csv --out model.json

# 3. Score it on platforms it never trained on
aliens_eye selfcheck --split holdout --model model.json --report json

# 4. Use it
aliens_eye username --model model.json

Ground truth is split site-disjoint into data/selfcheck.json (train, 30 sites) and data/eval_holdout.json (holdout, 13 sites). Scoring --split train measures fit, not generalization, and will read high.

Using it as a library

aliens_eye.api is the stable surface for building other tools on Aliens Eye. It returns plain dicts shaped like the JSON report and prints nothing by default.

import asyncio
from aliens_eye import api

async def main():
    sites = api.load_sites(exclude_nsfw=True)
    report = await api.scan(
        "someone",
        sites=sites,
        on_result=lambda user, r: print(r["site"], r["status"]),  # optional progress hook
    )
    correlation = await api.correlate(report)
    print(len(correlation["clusters"]), "clusters")

asyncio.run(main())

It can also read a profile link back into a site and username, and fetch a page whose address came from somewhere you don't control:

api.match_profile_url("https://www.instagram.com/_someone_/")
# [ProfileMatch(site='instagram', username='_someone_')]

page = await api.fetch_page("https://example.com/")   # public http(s) addresses only

Everything outside aliens_eye.api is internal and may change between minor releases.

Configuration

Aliens Eye merges a JSON config file with CLI flags (CLI wins). Search order without --config: ./config.json, then the platform config dir (e.g. ~/.config/aliens_eye/config.json on Linux, %LOCALAPPDATA%\aliens_eye on Windows).

{
  "concurrent": 50,
  "timeout": 10.0,
  "retries": 2,
  "rate_limit_delay": 0.2,
  "output_dir": "results",
  "output_formats": ["json", "csv", "html", "md"],
  "use_playwright": false,
  "proxy": null,
  "use_ml": true,
  "exclude_nsfw": false,
  "level": "basic"
}

Outputs

Results are saved with timestamped filenames:

• username_level_YYYYMMDD_HHMMSS.json — full detail including per-site feature analysis
• .csv — flat rows for spreadsheets
• .html — styled standalone report
• .md — Markdown summary of Found/Maybe hits

Architecture

The package lives under src/aliens_eye/: core/ (scanner, detector, analyzer, http, exporter, fingerprints), ml/ (inference, training, dataset collection), utils/ (rich console layer), and data/ (sites.json, trained model, ground-truth sets). For internals and flowcharts, see WORKING.md.

Contributing

Issues and PRs welcome — adding sites to src/aliens_eye/data/sites.json, expanding the ground-truth set in selfcheck.json, or improving the model all directly improve detection. Run pytest and ruff check src tests before submitting.

Disclaimer

This tool is for educational purposes and legitimate OSINT research only. You are responsible for complying with laws and site terms of service.