Inside
Architecture
Aliens Eye is one Python package, aliens_eye, under src/. This page maps it for
anyone reading or changing the code. The repository's
WORKING.md has the original working notes.
#A scan, end to end
fetch_url is the only point where the scanner touches the network. The
frozen corpus replaces just
that function, which is why replayed evaluations run exactly the code a live scan
does.
#Modules
#Entry points
| Module | Role |
|---|---|
cli.py |
The aliens_eye command: argument parsing, the interactive prompts, every subcommand. |
api.py |
The stable library surface: load_sites, scan, correlate, match_profile_url, profile_url, fetch_page. |
mcp_server.py |
The MCP server (serve). |
tui/app.py |
The Textual terminal UI (tui). |
catalog.py |
sites subcommands: catalog statistics, validation, imports from Maigret and Sherlock. |
selfcheck.py |
Accuracy against accounts known to exist and not to exist. |
#Scanning (core/)
| Module | Role |
|---|---|
scanner.py |
Loads and filters sites; the async worker pool; proxy and SOCKS connectors. |
http.py |
Fetching with retries, backoff, Retry-After, size caps. |
rate_limit.py |
Spacing between requests to the same host. |
sites.py, site_rules.py |
Structured catalog entries and their per-site rules. |
variations.py |
Variations for each level, usernames from emails, names and phones, scan cost. |
analyzer.py |
Parsing pages (selectolax) into features and profile details. |
features.py |
The feature schema shared by heuristics, training and inference. |
detector.py |
Heuristic scoring, the ML blend and the thresholds. |
control.py |
Whether a page is the one a site shows for a user who does not exist. |
fingerprints.py |
Per-site page signatures kept between scans. |
browser.py |
The Playwright fallback. |
explain.py |
The evidence behind each verdict, for --explain. |
checkpoint.py |
Resumable scans. |
#After the scan (core/)
| Module | Role |
|---|---|
correlate.py |
Clustering profiles by avatar, name, bio and links. |
expand.py, urlmatch.py |
Usernames linked from profiles; which site and user a profile URL belongs to. |
domains.py |
DNS and HTTP checks of <username>.<tld>. |
watch.py, watch_state.py |
Watch mode and what it remembers between scans. |
netguard.py |
Fetching URLs someone else chose without being steered to a private address. |
exporter.py, pdf_report.py |
JSON, CSV, HTML, Markdown, graph and PDF reports. |
report.py |
Loading, validating and comparing saved reports. |
#Measuring and training
| Package | Role |
|---|---|
corpus/ |
Recording live responses once (record.py), storing them (store.py), replaying them (replay.py). |
eval/ |
Ablations (ablate.py), other tools' rules as baselines (external.py), ground truth from other projects (groundtruth.py). |
ml/ |
Pure-Python inference (inference.py), dataset collection (collect.py, expanded.py), training (train.py), labelling (label.py). |
#Data (data/)
| File | Holds |
|---|---|
sites.json |
The standard catalog. |
extended_sites.json |
The extended catalog, with sources, rules, aliases and disabled entries. |
community_sites.json |
Pinned community site data the extended catalog is built from. |
model.json |
The shipped model: scaler statistics, coefficients, blend weight, thresholds. |
keywords.json |
Profile and error words, in several languages. |
selfcheck.json, eval_holdout.json |
The train and holdout ground truth. |
nsfw_sites.json, site_profiles.json |
Adult-site list; per-site profile selectors. |
seed_dataset.csv |
The labelled dataset the shipped model was trained on. |
#Scripts
scripts/verify_catalog.py checks every catalog site live and disables broken ones
(Sites and catalogs);
scripts/train_expanded.py trains candidates on the extended catalog
(Training the model).
#Dependencies
aiohttp and aiohttp-socks for HTTP and SOCKS, Brotli for compressed responses,
selectolax for parsing, rich for the terminal and platformdirs for the config
and cache directories. Everything else is an optional extra.
Edit this page on GitHub
Aliens Eye 2.10.0 · MIT licence · made by Aaron Thomas