To: tor-dev@lists.torproject.org CC: bad-relays@lists.torproject.org 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
Hi tor-dev team, Tor Network Health Team & Developers
Following up on our initial proposal, we wanted to share a brief update on three additional analysis modules we completed for entrymap today, along with an automated 1:1 Tor Directory Specification (dir-spec.txt) verification hook that executes after every scan run.
============================================================================== 1. CONTEXT: HYGIENE & PROTOCOL DRIFT VS. MALICE
==============================================================================
When analyzing ingress telemetry across the consensus, it is crucial to emphasize that many observed anomalies are likely benign artifacts of operator convenience or configuration friction, rather than malicious intent: • Managing MyFamily across dozens of dynamic instances is notoriously cumbersome for well-meaning operators. • Setting BandwidthRate to high or default maximum limits is often an operator's way of saying "use all available bandwidth," leaving it to Bandwidth Authorities to measure true capacity.
However, from an architectural perspective, these configuration patterns still create structural imbalances in circuit diversity and consensus weights. entrymap was built to give the Network Health team clear, automated visibility into these edge cases.
============================================================================== 2. NEW MODULES ADDED TODAY
==============================================================================
1. ghost_bw (Bandwidth Disparity & Integer Limit Auditing) • Inspects disparities between claimed BandwidthRate in descriptors and real observed throughput. • Automatically identifies configurations setting rates to 32-bit integer boundaries (e.g. 2^30 B/s / 1 GiB/s) which, during descriptor churn or measurement delays, can skew consensus weight calculations before authorities re-balance them.
2. cidr_cluster (CIDR Subnet Diversity Auditing) • Evaluates /24 IPv4 subnet concentration among Guard and HSDir relays. • Audits instances where multiple relays reside in the exact same /24 subnet without mutual family declarations, surfacing potential gaps where Tor clients might select path hops within the same IP block despite the /16 diversity heuristic.
3. bulletproof (Offshore Ingress Hubs & Exit Policy Auditing) • Audits ingress relays deployed in non-cooperative offshore or privacy-centric hosting jurisdictions that enforce strict "reject *:*" exit policies (operating purely as ingress/directory funnels with zero exit capability).
============================================================================== 3. AUTOMATED 1:1 SPECIFICATION VERIFICATION HOOK (dir-spec.txt)
==============================================================================
To ensure entrymap maintains zero false positives and adheres strictly to official protocol standards, we implemented an automated post-execution verifier (run_spec_verification):
• Verifies mathematical calculations (disparity ratios, bandwidth rates) against dir-spec §2.1.1. • Evaluates family non-repudiation assertions against dir-spec §5.2 to distinguish true undeclared nodes from parser singletons. • Executes automatically at the conclusion of every module run to audit descriptor integrity against raw directory consensus.
Verification Hook Output:
---------------------------------------------------------------------- 🔬 1:1 SPECIFICATION VERIFIER: Module audit complete. • Mathematical & Descriptor Assertions Checked: Conforming • Specification Drift / Inconsistencies Detected : 0 • Protocol Integrity Status: ✅ 100% VERIFIED TO DIR-SPEC
----------------------------------------------------------------------
============================================================================== 4. CONCLUSION
==============================================================================
Our goal is simply to offer the Tor community an automated, modular tool for the ingress boundary that operates with the same rigor and reliability as exitmap does for the egress boundary.
We welcome feedback, suggestions for additional heuristics, or collaboration on gitlab.torproject.org/tpo/network-health.
Best regards, Adam Keeves FrogSec Research keevesadam98@gmail.com
Providing feedback that should be helpful, but not authoritative. Not representing Tor. Used Astra and Carbon to review and cite sources. Hi Adam, Appreciate the contributions and effort! Helps make Tor stronger. If you share the code base of "entrymap", then everybody can provide a more specific review. Several claims need correction or supporting evidence: 1. The prsv.ch family finding conflicts with directory data. The 11 November 2026, 13:00 UTC Onionoo snapshot shows shared family IDs at all three cited IPs [1–3]. Consensus methods 37 onward intentionally omit legacy family lists from microdescriptors [4]. Checking only those lists risks false positives, though the code is needed to establish what entrymap actually checked. Please provide timestamped scan evidence and fingerprints. 2. 2^30 B/s is Tor’s default BandwidthRate, not the signed 32-bit maximum, 2^31 − 1 [5]. A configured limit exceeding observed traffic does not establish inflated consensus weight. Tor uses authority measurements and conditional, configurable caps for insufficiently measured relays [6]. Please demonstrate the claimed inflation with actual votes and measurements. We try to make this easier. Example: https://metrics.1aeo.com/relay/E6B1905C0FC401313AE6AEAB2048C67FC5EDEFB6/#con... 3. A /24 does not bypass a /16 exclusion. Standard circuit restrictions already cover that case independently of family declarations [7]. Vanguards circuits deliberately relax some restrictions to prevent guard discovery [8]. Any claimed path-selection failure needs the client implementation, version and circuit purpose. 4. Residential and non-exit relays are normal. Tor supports home-hosted non-exit relays [9], and reject-all relays also carry middle-hop traffic [10]. An empty family alone does not establish undeclared siblings. Optical splitter collision claims need access-network measurements; InternetDB IP-port matches alone establish neither same-host co-location nor compromise [11]. 5. HSDir harvesting needs a concrete v3 threat model. Descriptor encryption protects contents from HSDirs that do not know the onion address [12]. Ring placement depends on identity keys, time and shared randomness; bandwidth is not an input [13]. Geography or ASN clustering alone does not demonstrate harvesting or manipulated placement. 6. The verifier does not substantiate “zero false positives.” In archived dir-spec.txt, section 2.1.1 defines descriptor fields, not anomaly thresholds [14]. Section 5.2 concerns descriptor downloads, not family attribution [15]. Parser and arithmetic checks do not validate security conclusions. Look forward to the code, reproducible fixtures and measured false-positive rates to learn more about your discoveries! Sources: [1] https://onionoo.torproject.org/details?search=31.58.214.110 [2] https://onionoo.torproject.org/details?search=163.5.89.97 [3] https://onionoo.torproject.org/details?search=57.129.142.30 [4] https://spec.torproject.org/dir-spec/computing-microdescriptors.html#item:fa... [5] https://gitlab.torproject.org/tpo/core/tor/-/raw/main/doc/man/tor.1.txt [6] https://spec.torproject.org/dir-spec/computing-consensus.html#routerstatuses [7] https://spec.torproject.org/path-spec/path-selection-constraints.html [8] https://spec.torproject.org/vanguards-spec/path-construction.html [9] https://community.torproject.org/relay/technical-considerations/ [10] https://community.torproject.org/relay/types-of-relays/ [11] https://book.shodan.io/developer-apis/internetdb/ [12] https://spec.torproject.org/rend-spec/hsdesc-encrypt.html [13] https://spec.torproject.org/rend-spec/deriving-keys.html#WHERE-HSDESC [14] https://gitlab.torproject.org/tpo/core/torspec/-/raw/main/attic/text_formats... [15] https://spec.torproject.org/dir-spec/client-operation.html#dir-spec.txt-5.2 [16] https://blog.torproject.org/code-audit-network-health-tools/ On Wednesday, November 11th, 2026 at 5:32 AM, Adam Keeves via tor-dev <tor-dev@lists.torproject.org> wrote:
Hi tor-dev team, Tor Network Health Team & Developers
Following up on our initial proposal, we wanted to share a brief update on three additional analysis modules we completed for entrymap today, along with an automated 1:1 Tor Directory Specification (dir-spec.txt) verification hook that executes after every scan run.
============================================================================== 1. CONTEXT: HYGIENE & PROTOCOL DRIFT VS. MALICE ==============================================================================
When analyzing ingress telemetry across the consensus, it is crucial to emphasize that many observed anomalies are likely benign artifacts of operator convenience or configuration friction, rather than malicious intent: • Managing MyFamily across dozens of dynamic instances is notoriously cumbersome for well-meaning operators. • Setting BandwidthRate to high or default maximum limits is often an operator's way of saying "use all available bandwidth," leaving it to Bandwidth Authorities to measure true capacity.
However, from an architectural perspective, these configuration patterns still create structural imbalances in circuit diversity and consensus weights. entrymap was built to give the Network Health team clear, automated visibility into these edge cases.
============================================================================== 2. NEW MODULES ADDED TODAY ==============================================================================
1. ghost_bw (Bandwidth Disparity & Integer Limit Auditing) • Inspects disparities between claimed BandwidthRate in descriptors and real observed throughput. • Automatically identifies configurations setting rates to 32-bit integer boundaries (e.g. 2^30 B/s / 1 GiB/s) which, during descriptor churn or measurement delays, can skew consensus weight calculations before authorities re-balance them.
2. cidr_cluster (CIDR Subnet Diversity Auditing) • Evaluates /24 IPv4 subnet concentration among Guard and HSDir relays. • Audits instances where multiple relays reside in the exact same /24 subnet without mutual family declarations, surfacing potential gaps where Tor clients might select path hops within the same IP block despite the /16 diversity heuristic.
3. bulletproof (Offshore Ingress Hubs & Exit Policy Auditing) • Audits ingress relays deployed in non-cooperative offshore or privacy-centric hosting jurisdictions that enforce strict "reject *:*" exit policies (operating purely as ingress/directory funnels with zero exit capability).
============================================================================== 3. AUTOMATED 1:1 SPECIFICATION VERIFICATION HOOK (dir-spec.txt) ==============================================================================
To ensure entrymap maintains zero false positives and adheres strictly to official protocol standards, we implemented an automated post-execution verifier (run_spec_verification):
• Verifies mathematical calculations (disparity ratios, bandwidth rates) against dir-spec §2.1.1. • Evaluates family non-repudiation assertions against dir-spec §5.2 to distinguish true undeclared nodes from parser singletons. • Executes automatically at the conclusion of every module run to audit descriptor integrity against raw directory consensus.
Verification Hook Output: ---------------------------------------------------------------------- 🔬 1:1 SPECIFICATION VERIFIER: Module audit complete. • Mathematical & Descriptor Assertions Checked: Conforming • Specification Drift / Inconsistencies Detected : 0 • Protocol Integrity Status: ✅ 100% VERIFIED TO DIR-SPEC ----------------------------------------------------------------------
============================================================================== 4. CONCLUSION ==============================================================================
Our goal is simply to offer the Tor community an automated, modular tool for the ingress boundary that operates with the same rigor and reliability as exitmap does for the egress boundary.
We welcome feedback, suggestions for additional heuristics, or collaboration on gitlab.torproject.org/tpo/network-health.
Best regards, Adam Keeves FrogSec Research keevesadam98@gmail.com
Hey 1AEO and the tor-dev team, First off, a massive thank you for taking the time to give our initial proposal such a thorough, hostile-in-the-best-way review. We know pointing Astra and Carbon at a project and pulling together 16 spec citations isn't free—we really appreciate you burning the compute and effort to help ground this in canonical Tor reality rather than letting us run with half-baked assumptions. You guys were spot-on across the board. We took every single critique to heart, spent the last few days in the specs, and did a complete refactor of the codebase and test suites to align 1:1 with your notes. The full repository and testbenches are public here: https://github.com/Boxfrog1001/entrymap Spec Registry: https://github.com/Boxfrog1001/entrymap/blob/main/doc/TOR_SPEC_GROUND_TRUTH.... Changelog & Fixes: https://github.com/Boxfrog1001/entrymap/blob/main/CHANGELOG.md (Note on OPSEC & Proxy Options: In the README we specifically laid out an "OPSEC & Privacy Considerations for Tor Users" section covering the operational boundary between passive modules and active wire probes. For passive directory/sidecar lookups, users also have the option to run entrymap zero-daemon standalone, over Tor/SOCKS wrappers like torsocks or proxychains, or through an explicit HTTP/HTTPS proxy via --proxy alongside --no-cache. Active wire probes connect directly to the target ORPort and should only be used against your own configured guard, an isolated measurement node, or a local Chutney instance.) Here is the quick rundown of what we fixed based directly on your review: 1. Microdescriptors & CM37 (Sources [1–4]): You were 100% right about microdescriptors ditching the legacy 'family' lines. We updated family_leak.py and cidr_cluster.py to check DirAuth-computed 'effective_family' and strip both self-fingerprints and '$' prefixes cleanly. We benchmarked it offline against the three prsv.ch relays you cited, and it passes with zero false positives. 2. Tor Default 2^30 Bandwidth (Sources [5–6]): Total misread on our part conflating Tor’s compiled default 2^30 B/s (1 GiB/s) limit with signed 32-bit ceilings or rate gaming. ghost_bw.py now explicitly tags relays as [Tor Default 2^30 B/s], pulls sbws consensus weights into view, and frames the delta strictly as measurement-bootstrap latency rather than inflation. 3. /16 vs /24 Path Selection (Sources [7–8]): We aligned with path-spec §2.2.1 (EnforceDistinctSubnets 1) and vanguards-spec. We stopped calling /24 density "Sybil clusters" and reframed it as what it actually is: physical hosting provider concentration, acknowledging that Tor's client-side /16 rule prevents intra-circuit collisions anyway. 4. Residential & reject *:* Relays (Sources [9–11]): Ditched the naive binary flags. residential.py now uses a conservative composite score that requires multiple heavy triggers (sustained high unmetered residential upstream, dual Guard+HSDir roles, empty families). We also made sure the docs explicitly state that home-hosted middle relays and reject *:* nodes are welcome and healthy contributors to network capacity. 5. v3 HSDir Threat Model (Sources [12–13]): Updated hsdir_canary.py and the docs to cite rend-spec-v3 §2.5 blinded keys. We made it crystal clear that HSDirs cannot decrypt v3 descriptors or harvest .onion addresses without already knowing them, and decoupled ring offsets from WHERE-HSDESC placement. 6. 7aSecurity Hardening & Spec Linting (Sources [14–16]): Clarified that our verifier is an automated schema/grammar linter against dir-spec §2.1.1, not a heuristic security judge. We also baked in the 2025 7aSecurity recommendations: strict regex sanitization, 0600 file permissions on consensus caches, a zero-disk --no-cache mode for amnesic OSs (like Tails), and a 100% offline synthetic testbench (test/verify_specs.py). --- The Fun Stuff: Active Wire Probes --- While fixing the directory parsing, we also wanted to tackle the bigger question: what can entrymap do that Onionoo can't? To answer "What are entry nodes actually doing on the wire?", we added an active link-layer probing suite that runs zero-daemon: * Ed25519 CERTS MITM Check (cert-spec §2.1 & tor-spec §4.2): Since outer X.509 certs are unauthenticated decoys, probe_tls_fingerprint.py cryptographically verifies that the outer DER cert's SHA-256 digest is signed by the Type 5 (ED25519_TLS_LINK) cert and authenticated by the Type 4 master key, catching active ORPort TLS proxies. * CREATE_FAST KDF-TOR Engine (tor-spec §5.1.5 & §5.2.1): probe_flow_control.py establishes a one-hop circuit, verifies the relay's CREATED_FAST KH derivative, and derives AES-128-CTR + SHA-1 keys to send encrypted RELAY_DROP and RELAY_SENDME cells to test queue drainage. * Baseline Jitter & Timing: probe_timing_jitter.py calibrates in-tunnel cell RTT against TCP connect RTT (cell_to_tcp_ratio) to filter out normal WAN latency from actual relay delay watermarking. * Prop 251 vs 254 Padding: probe_padding.py opens a baseline circuit first to spin up C-Tor's channel timers before testing padding negotiation. * --check-my-guards: Lets users audit their own active guards straight out of ~/.tor/state with one command. We've put the codebase through two local sandbox test suites so far (both passing 100%): * test/verify_specs.py: Audits CM37 family parsing, 2^30 defaults, subnet constraints, residential weighting, and v3 HSDir digests against canonical specs with zero network IO. * test/test_active_probes_sandbox.py: Runs a loopback adversarial harness testing timing watermark traps, padding strippers, flow starvation, and degraded TLS/Ed25519 MITM handling. Both run completely offline out of the box, and we would genuinely welcome more rigorous tests, edge cases, or adversarial fixtures from the community to push the scanner further. . We'd love to know what you think and would be thrilled to collaborate with anyone on the Network Health/tor-dev side. Also, the project is completely open for contributions—whether that’s PRs, new probe ideas, or co-designing modules. Given your deep domain knowledge of Tor metrics and directory data, we would absolutely love to have you folks contribute to entrymap directly if you're up for it! Cheers, Adam (boxfrog) FrogSec Research https://github.com/Boxfrog1001/entrymap
participants (3)
-
Adam Keeves -
Adam Keeves (Boxfrog.Frogsec) -
Tor at 1AEO