# RealiTLScanner: finding steal-your-TLS hosts for Reality, one CIDR at a time > RealiTLScanner is XTLS's MPL-2.0 Go tool for scanning TLS servers as part of the Reality protocol's workflow, probing addresses, CIDR ranges, target lists or domains crawled from a URL and reporting the certificate domains, issuers and Geo IP codes of feasible hosts. Output lands as stdout logs or CSV, Geo IP activates through a MaxMind database file, and a Docker image runs the scanner without a Go toolchain. **XTLS/RealiTLScanner** — A TLS server scanner for Reality - Repository: https://github.com/XTLS/RealiTLScanner - Stars: 4,425 · Forks: 314 - Language: Go - License: MPL-2.0 - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/xtls-realitlscanner ## Why Reality needs a scanner The tool's description is one line, a TLS server scanner for Reality, and its place in the XTLS ecosystem follows from how Reality works, the protocol borrows the TLS handshake characteristics of an existing website so that probing connections can be forwarded to a real host. Finding that host, a server with a suitable certificate, reachable, and not one's own, is the scanner's job. The output columns make the workflow explicit, IP, ORIGIN, CERT_DOMAIN, CERT_ISSUER and GEO_CODE, so an operator scanning a range learns which servers present which certificate domains from which issuers in which countries, the raw material for choosing a Reality dest. The project is Go, MPL-2.0 licensed, and lives in the XTLS organization beside the protocol itself. ## Four input modes, one of them a crawler The usage examples cover four input shapes. A specific address, IP, IP CIDR or domain, goes through the -addr flag, with the note that infinity mode will be enabled automatically if the address is an IP or domain, turning a single target into an open-ended hunt. A list of targets divided by line breaks loads through -in with a file such as in.txt. Domains can be crawled from a URL, the documented example pointing the crawler at launchpad.net's Ubuntu archive mirrors page, which conveniently lists hundreds of mirror hostnames, each then scanned. And the -port flag sets the scan port, defaulting to 443. Verbose output through -v includes failed scans and infeasible targets, the visibility an operator needs to distinguish a dead range from a filtered one. ## Building, or pulling the Docker image flow Building requires Go 1.21 or newer and one command in the repository, go build, and the go.mod shows the current toolchain at go 1.26 with a single direct dependency, oschwald's geoip2-golang for the MaxMind database reading. The Docker path exists for hosts without Go, building the container image yourself: ```bash docker build -t realitlscanner . ``` then running it with the flags passed through the entrypoint: ```bash docker run --rm realitlscanner -addr 1.1.1.1 ``` The Dockerfile is a two-stage build, golang 1.26 alpine compiling the binary, and an alpine runtime with ca-certificates installed, the certificate store being the one runtime dependency a TLS scanner cannot skip, since it must verify the certificates it reports. ## The stdout, readable as a story The demo output shows the scanner's live log format, one line per feasible connection with structured fields, the timestamped INFO lines reporting Connected to target with feasible=true, the host IP, tls 1.3, alpn h2, the certificate's domain and its issuer, the examples showing Let's Encrypt certificates on hosts with domains from rocky-linux.tk to mirror subdomains. The log line format, with key equals value pairs and quoted strings, is structured enough to parse or grep, and the started-threads line marks the run's beginning. Reading a scan's log is reading the TLS landscape of a network range, which servers speak TLS 1.3, which ALPNs they negotiate, and whose certificates they present, in the order the scanner reaches them. ## CSV out, spreadsheet-ready Alongside the log, the scanner writes a CSV output file with the five-column header, IP, ORIGIN, CERT_DOMAIN, CERT_ISSUER, GEO_CODE, and the example rows show the variety it captures, a Nepali telecom with a wildcard certificate from GlobalSign, Moroccan and Icelandic Ubuntu mirrors with Let's Encrypt certificates, a Dutch mirror with Sectigo, and the geo codes, NP, MA, JP, NL, NZ, NO, marking the countries. One row's ORIGIN and CERT_DOMAIN differ, ubuntu.hi.no presenting alma.hi.no, exactly the mismatch Reality operators hunt for, a server whose certificate covers a different name than its address suggests. The CSV makes bulk analysis possible, sorting by issuer or country, deduplicating certificate domains, and feeding the chosen dest into the Reality configuration. ## Geo IP as a drop-in file Geo IP information is optional and file-based, place a MaxMind GeoLite2 or GeoIP2 Country Database in the executing folder with the exact name Country.mmdb, and the documentation links a ready download of the Country.mmdb file from the Loyalsoldier geoip releases, the community-maintained aggregation of MaxMind's data. The geoip2-golang dependency reads the file, and the GEO_CODE column in the CSV is the payoff, country codes attached to every scanned host without any API call or key. The exact-name requirement is the only configuration the feature has, no flag, no path setting, the file present or absent deciding whether the column fills. ## The cloud warning, and the v0.2 line The usage section carries one operational warning worth internalizing, it is recommended to run this tool locally, as running the scanner in the cloud may cause the VPS to be flagged, the provider-side risk of a host machine mass-connecting to TLS ports across IP ranges. The release history shows the project's rhythm, v0.2.1 in February 2024, then v0.2.2 and v0.2.3 five days apart in May 2026, with the repository pushed the same day as the newest tag. The source is compact, main.go, scanner.go, geo.go and utils.go beside the Dockerfile and a wireshark of dependencies, a small tool with a focused job, and the README's ninety-two words match, every flag documented by example rather than prose. ## Conclusion Use RealiTLScanner when configuring XTLS Reality and a suitable forward-referencing TLS host must be found, scanning candidate CIDRs or mirror lists for servers whose certificate domains can be borrowed. It is a network scanning tool, so run it against addresses you are authorized to probe, and heed the project's own operational warning to run it locally rather than in the cloud, since a VPS running the scanner may be flagged. Before starting, build with Go 1.21 or newer or use the Docker image, download a GeoLite2 Country database as Country.mmdb for Geo codes, and start with the help output before scanning ranges, since infinity mode changes behavior automatically by target type. ## FAQ ### What is RealiTLScanner? RealiTLScanner is XTLS's MPL-2.0 licensed Go tool for scanning TLS servers as part of setting up the Reality protocol. It probes IPs, CIDR ranges, target lists or domains crawled from a URL, reporting each feasible host's TLS version, ALPN, certificate domain, issuer and optionally its country, with results as logs and a CSV file. ### How do you run RealiTLScanner? Build it with go build requiring Go 1.21 or newer, or build the Docker image with docker build -t realitlscanner and run it with docker run. Pass targets with -addr for an IP, CIDR or domain, -in for a line-separated file, or -url to crawl domains from a page, with -port defaulting to 443 and -v for verbose output. ### How do you enable Geo IP in RealiTLScanner? Place a MaxMind GeoLite2 or GeoIP2 Country database in the executing folder named exactly Country.mmdb, downloadable from the linked Loyalsoldier geoip releases. The scanner then fills the GEO_CODE column of its CSV output with the country code of each scanned host. ## Sources - [Issues](https://github.com/XTLS/RealiTLScanner/issues) - [License: MPL-2.0](https://github.com/XTLS/RealiTLScanner/blob/main/LICENSE) - [README](https://github.com/XTLS/RealiTLScanner/blob/main/README.md) - [Releases](https://github.com/XTLS/RealiTLScanner/releases) - [XTLS/RealiTLScanner on GitHub](https://github.com/XTLS/RealiTLScanner) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xtls-realitlscanner