ipfinder

A command-line tool written in Rust that scans one or more CIDR ranges for a Minecraft: Java Edition server whose MOTD matches that of a chosen reference server. It fetches the reference server's MOTD over the Server List Ping protocol, then pings every host in the supplied ranges concurrently and prints the addresses whose MOTD is identical — useful for locating the machine actually serving a given hostname (for example, recovering the origin IP of a server behind a DNS name or proxy).

The scan is fully asynchronous: hosts are enumerated lazily from the merged prefixes and pinged through a bounded buffer_unordered stream, so a /16 is swept without materialising every address up front and without opening more sockets than the configured concurrency limit allows.

Overview

The reference MOTD is the fingerprint the scan searches for. ipfinder obtains it once, then looks for an exact match across the target ranges:

1. Parse and resolve the reference address. A _minecraft._tcp. SRV record is honoured when the port is the default 25565, followed by an ordinary A/AAAA lookup; if the system resolver is unavailable, it falls back to Google DNS.
2. Connect to the reference server and ping it, capturing the description field of the status response — the MOTD to match against.
3. Collect CIDR ranges from --range flags and/or a --ranges-file, merge and simplify them with iprange, and enumerate every usable host (network and broadcast addresses are excluded, matching Ipv4Net::hosts() semantics).
4. Ping each host concurrently, bounded by --concurrency, with every attempt capped by --timeout.
5. Print each IP whose MOTD equals the reference to stdout; progress and a final summary are written to stderr.

Requirements

• Rust toolchain (edition 2024, stable) — or Nix with flakes enabled
• Outbound TCP access to the probed port (25565 by default)

Installation

From source

git clone https://github.com/c2fc2f/ipfinder
cd ipfinder
cargo build --release

The compiled binary will be at target/release/ipfinder. A man page is generated during the build (under target/.../out/), and shell completions can be produced on demand — see Shell completions and man page.

With Nix

A Nix flake is provided:

nix run github:c2fc2f/ipfinder -- --help
# or
nix build
# or, to enter a development shell:
nix develop

The Nix package installs the man page and shell completions automatically.

Usage

ipfinder [OPTIONS] <ADDRESS>

<ADDRESS> is the reference server, given as host or host:port (the port defaults to 25565). At least one range must be supplied through --range, --ranges-file, or both.

Flag	Short	Description	Default
--range <CIDR>	-r	CIDR range to scan; repeat the flag for multiple ranges	(none)
--ranges-file <FILE>	-f	File with one CIDR per line (# comments allowed); - reads from stdin	(none)
--port <PORT>	-p	TCP port to probe on each host	25565
--timeout <MS>	-t	Per-host connection/ping timeout, in milliseconds	2000
--concurrency <N>	-c	Maximum number of hosts pinged concurrently	512
--verbose	-v	Increase log verbosity (repeatable)	(errors only)
--quiet	-q	Decrease log verbosity (repeatable)

Examples

Scan two OVH blocks for whichever host is currently answering at play.example.net:

ipfinder -r 51.75.0.0/16 -r 145.239.0.0/16 play.example.net

Read the ranges from a file instead (one CIDR per line):

ipfinder -f ovh.txt play.example.net

Re-scan only hosts already known to have the port open, piping the list in from stdin:

cat responders.txt | ipfinder -f - play.example.net

Probe a non-default port — note that the SRV lookup only happens on 25565, so it is skipped here:

ipfinder -r 10.0.0.0/24 -p 25566 example.com:25566

Sweep a large range faster by raising concurrency and shortening the timeout:

ipfinder -f ovh.txt -c 2048 -t 800 play.example.net

Turn up logging to see per-connection detail:

ipfinder -vv -r 51.75.0.0/16 play.example.net

A typical workflow is to sweep broad ranges with masscan to find open ports, then hand the responders to ipfinder to identify the one serving the target MOTD.

Shell completions and man page

The completion subcommand prints a completion script for the requested shell to stdout:

ipfinder completion bash > ipfinder.bash

Supported shells are bash, zsh, fish, elvish, and powershell. The man page is emitted at build time (and installed for you by the Nix package).

Implementation Notes

• MOTD matching is exact. The reference server's description is compared for structural equality against each candidate, so cosmetic differences (colour codes, extra components) will not match.
• SRV redirection is limited to the default port. A _minecraft._tcp.<host> lookup is only attempted when the port is 25565; on any other port the address is resolved directly.
• Ranges are normalised before scanning. Overlapping or adjacent prefixes are merged and simplified, and hosts are streamed lazily, so overlapping --range/--ranges-file input is deduplicated and large sweeps stay memory-light.
• Failures are silent per host. A connection that times out or a host that does not speak the protocol is simply skipped; only positive matches are printed to stdout.

License

This project is licensed under the MIT License.