To:
tor-dev@xxxxxxxxxxxxxxxxxxxx CC:
bad-relays@xxxxxxxxxxxxxxxxxxxx Subject: [TOOL PROPOSAL & PoC] entrymap: A fast, modular scanner for Entry Guards & HSDirs (Complementing exitmap)
Dear Tor Network Health Team & Developers,
I am writing to share an open-source tool we have developed called 'entrymap', designed to complement Philipp Winter's 'exitmap'.
While exitmap has been instrumental in securing the egress boundary of the network, we recognized a tooling gap regarding active and passive audits of Entry Guards and Hidden Service
Directories (HSDirs). Ingress nodes holding Guard/HSDir flags without declared families or operating in consumer residential pools represent significant end-to-end correlation and
directory harvesting risks.
We built entrymap mirroring the exact architectural conventions of exitmap (bin/entrymap, src/entrymap.py, and modular drop-in analyzers in src/modules/) so that it slots seamlessly
into existing research workflows.
======================================================================
1. INITIAL PROOF-OF-CONCEPT (PoC) FINDINGS
======================================================================
During initial testing across the live consensus, entrymap immediately surfaced actionable network health anomalies:
A. Multi-Node Clusters with Undeclared Families (HSDir Ring)
Scanning active UK HSDir relays revealed multiple instances of single operators running several high-bandwidth relays across disparate ASNs while leaving 'MyFamily' completely empty.
- Example: Operator 'admin[]
prsv.ch' actively operating 3 distinct relays:
• 31.58.214.110 (IOMART CLOUD, AS20860)
• 163.5.89.97 (Metric Systems UK, AS216405)
• 57.129.142.30 (OVH SAS, AS16276)
All 3 relays hold both Guard and HSDir flags with ~200+ Mbps bandwidth, but zero family cross-declaration. This creates an unmitigated risk where a client's path-selection algorithm
can unknowingly pick the same entity for both their Guard and their HSDir.
B. High-Bandwidth Guards on Consumer Residential FTTP/DOCSIS
The 'residential' module automatically flags consumer IP pools where high unmetered burst rates cause local optical TDMA splitter collisions or where domestic server environments host
relays alongside exposed non-Tor services (e.g. Traefik, STUN/RustDesk, cleartext HTTP port 80).
- Example: Relay 'vRelay3' (DD86B2DCFAADD7DFC02CA74AD8BF7B01518CAF26) on YouFibre UK (AS212655) holding ~0.0391% global Guard probability with MyFamily==None on a shared residential
optical split.
======================================================================
2. MODULAR ARCHITECTURE
======================================================================
The project currently ships with 3 modular analyzers:
1. modules/residential.py: Flags consumer access networks, FTTP saturation, and uncoordinated high-throughput Guards.
2. modules/family_leak.py: Detects undeclared multi-relay operator clusters.
3. modules/sidecar.py: Passively queries third-party indexes (InternetDB) to identify co-located services (e.g. unencrypted HTTP, remote management) without sending raw probes.
4. modules/hsdir_canary.py: Audits HSDir ring distribution and flags high-risk directory candidates.
======================================================================
3. COMMUNITY TRIAL & REPOSITORY ACCESS
======================================================================
The tool is 100% open-source under the 2-Clause BSD license. We would love to offer this tool to the Tor Project for review, trial, or potential inclusion under tpo/network-health on
GitLab.
If the Network Health team is interested in testing or integrating entrymap, we would be delighted to share the repository or submit a formal merge/review request.
Thank you for everything you do to keep the Tor network safe and resilient.
Sincerely,
Adam Keeves
FrogSec Research
Leicestershire, United Kingdom