reverse-whois

Reverse WHOIS CLI for domain discovery using indexed WHOIS data

reverse-whois is a production-grade command-line tool maintained by a member of Haltman.io to perform Reverse WHOIS queries using a commercial WHOIS data provider (WhoisXML API).

The tool allows analysts to start from a search term (brand, organization name, email fragment, unique string, etc.) and enumerate domains whose WHOIS records contain that term, across:

  • Current WHOIS records

  • Historic WHOIS records (optional)

This capability is commonly required during:

  • Threat intelligence investigations

  • Brand and vendor footprint discovery

  • OSINT enrichment

  • M&A, legal, and compliance due diligence

  • Infrastructure attribution and clustering

The focus is on repeatable CLI usage, pipeline-friendly output, and explicit operational controls (API keys, rate limits, proxies).

Basic usage

Installation

Requirements

  • Go 1.22+

  • Valid WhoisXML API key

Build from source (recommended)

git clone https://github.com/haltman-io/reverse-whois.git
cd reverse-whois
go mod tidy
go build -o reverse-whois ./cmd/reverse-whois

Run:

./reverse-whois -h

Install into $GOBIN

go install github.com/haltman-io/reverse-whois/cmd/reverse-whois@latest

Verify:

reverse-whois -h

If the binary is not found, ensure $GOBIN (or $(go env GOPATH)/bin) is in your PATH.

Configuration

API key configuration (required)

This tool requires an API key from WhoisXML.

API keys can be provided in two ways.

Option 1 — CLI flag (highest priority)

reverse-whois --api-key YOUR_API_KEY -t example.com

Option 2 — YAML config file (recommended)

On first run, the tool looks for a file next to the executable:

.reverse-whois.yaml

If it does not exist, it is created automatically:

api_keys: []

Populate it with one or more keys:

api_keys:
  - KEY_1
  - KEY_2

Behavior:

  • If multiple keys are present, the tool rotates keys round-robin per request

  • If no key is provided and the file is empty, execution aborts with an error

Usage

Basic usage (current WHOIS, purchase mode)

reverse-whois -t example.com

This performs:

  • searchType = current

  • mode = purchase (default)

Historic WHOIS search

reverse-whois -t example.com --history

Use when you need to identify previously registered or transferred domains.

Preview mode (count only)

Preview mode returns only the number of matching domains, without listing them.

reverse-whois -t example.com --preview

Output example:

[example.com] [preview] [current] [domainsCount: 42]

Preview

Target input methods

Supported input sources:

  • --target / -t (repeatable, comma-separated)

  • --target-list / -tL (files with one term per line)

  • stdin / pipeline

Examples:

reverse-whois -t example.com,corp-name

reverse-whois -tL targets.txt

cat targets.txt | reverse-whois

Excluding terms

Exclude up to 4 terms from the results (API constraint):

reverse-whois -t example.com -e freeexample.org

reverse-whois -t example.com -e a,b,c,d

If more than 4 exclude terms are provided, the tool exits with an error.

Output to file

reverse-whois -t example.com --output results.txt

Behavior:

  • File is overwritten if it exists

  • No ANSI colors

  • Deduplicated results

  • Purchase mode: one domain per line

  • Preview mode: term<TAB>count

Possible Problems / Important Notes

API rate limits

  • Hard provider limit: 30 requests/second

  • Tool enforces this limit and rejects higher values

Example:

reverse-whois -t example.com -rl 10

Concurrency behavior

  • --threads controls worker count

  • --rate-limit is global, not per-thread

reverse-whois -t example.com --threads 5 -rl 10

Proxy and TLS handling

Supported proxies:

  • http://

  • https://

  • socks5://

Example:

reverse-whois -t example.com --proxy socks5://127.0.0.1:9050

Disable TLS verification (dangerous):

reverse-whois -t example.com -k

Use --insecure/-k only in controlled lab environments.

Common API errors

You may encounter:

  • 401 Unauthorized — invalid or missing API key

  • 403 Forbidden — account or credit issue

  • 429 Too Many Requests — rate limit exceeded

  • 422 Unprocessable Entity — invalid search term

The tool prints provider error messages directly to assist troubleshooting.

External References

Updated on
search-leaks
sub-alter