ip-thc (v1.0.0-stable)

A fast, operator-friendly CLI for querying the ip.thc.org public intelligence API (dataset advertised as ~5.14 Billion indexed domains) to perform:

• Reverse DNS lookups (IP → domains)
• Subdomain enumeration (domain → subdomains)
• CNAME relationship discovery (target domain → domains pointing to it)

Disclaimer: This tool was developed independently. The author has no affiliation with The Hacker’s Choice (THC).

---

Screenshot / Demo

---

Why ip-thc exists

When you’re doing recon at scale (red team ops, pentests, bug bounty triage, or investigative work), you often need fast enrichment from a large dataset:

• Pivot from an IP to domains hosted behind it (Reverse DNS)
• Expand scope with subdomain coverage (Subdomain Lookup)
• Identify possible hosting / SaaS / takeover surfaces via CNAME pivots (CNAME Lookup)

ip-thc is built as a stable, defensive CLI:

• Clear target ingestion (flags, lists, explicit STDIN)
• Strong operational controls (threads, rate-limit, pagination)
• Proxy support (HTTP(S) + SOCKS5) for segmented environments
• Clean output modes (raw or file output with sort+dedupe)

---

Features

Overview

$ ./ip-thc --help

 /$$    www.thc.org      /$$     /$$
|__/                    | $$    | $$
 /$$  /$$$$$$          /$$$$$$  | $$$$$$$   /$$$$$$$
| $$ /$$__  $$ /$$$$$$|_  $$_/  | $$__  $$ /$$_____/
| $$| $$  \ $$|______/  | $$    | $$  \ $$| $$      
| $$| $$  | $$          | $$ /$$| $$  | $$| $$      
| $$| $$$$$$$/          |  $$$$/| $$  | $$|  $$$$$$$
|__/| $$____/            \___/  |__/  |__/ \_______/
    | $$
    | $$   github.com/haltman-io/ip-thc (Golang version)
    |__/   [release: v1.0.0-stable]

 [!] This tool was developed independently. The author has no affiliation with The Hacker's Choice. 

ip-thc (v1.0.0-stable) - ip.thc.org API client (ReverseDNS / Subdomain / CNAME)

USAGE:
  ip-thc [mode] [targets] [options]

TARGET INPUT:
  --target <target>           Define a target (repeatable, comma-separated supported)
  -t <target>

  --target-list <file>        File with targets (one per line; repeatable, comma-separated supported)
  -tL <file>

  --stdin                     Enable reading targets from STDIN (pipe) as additional targets

MODES (select exactly one):
  --reverse-dns               Reverse DNS lookup (API: POST /api/v1/lookup)
  -rdns

  --subdomain                 Subdomain lookup (API: POST /api/v1/lookup/subdomains)
  -sub

  --cname                     CNAME lookup (API: POST /api/v1/lookup/cnames)
  -cn

OPTIONS:
  --results <n>               Max results per API request (default: 10)
  --limit <n>                 Alias for --results
  -r <n>

  --all                       Auto-pagination until next_page_state is empty

  --threads <n>               Concurrent targets (default: 1)
  --rate-limit <rps>          Max requests per second (default: 5)
  -rl <rps>

  --proxy <url>               Proxy URL: http://host:port, https://host:port, socks5://host:port
  --proxy-auth <user:pass>    Proxy auth: HTTP Basic or SOCKS5 user/pass
  --no-proxy                  Ignore proxy environment variables

  --insecure                  Disable TLS verification (curl-style)
  -k

  --output <file>             Save sorted + deduped results to file
  -o <file>

  --silent                    Print results only (also suppress banner)
  -s

  --debug                     Verbose debug logs to STDERR

  --timeout <duration>        HTTP timeout (default: 30s). Examples: 30s, 2m
  --user-agent <ua>           Override User-Agent

NOTES:
  - Multiple targets are supported:
      ip-thc -t google.com,twitter.com -sub
      ip-thc -t google.com -t twitter.com -sub
      ip-thc -tL targets1.txt,targets2.txt -sub
  - STDIN is ignored unless --stdin is explicitly provided.

Query modes (mutually exclusive)

• --reverse-dns / -rdns → POST /api/v1/lookup
• --subdomain / -sub → POST /api/v1/lookup/subdomains
• --cname / -cn → POST /api/v1/lookup/cnames

Exactly one mode must be selected.

Target ingestion (3 sources)

• --target / -t (repeatable, supports comma-separated lists)
• --target-list / -tL (repeatable, supports comma-separated file paths; one target per line)
• --stdin (explicitly enables reading piped targets from STDIN)

STDIN is ignored unless --stdin is explicitly provided.

Pagination (auto-scroll)

• API responses include next_page_state
• With --all, ip-thc continues requesting pages until next_page_state == ""

Operational controls

• --threads controls concurrency across targets

• --rate-limit controls max requests per second (global limiter shared by all workers)

• Response header handling:

  • If X-Ratelimit-Remaining < 5, the tool pauses silently for 15 seconds to avoid hard throttling

Output

• Default prints one result per line
• --output/-o saves sorted + deduplicated results to a file

Proxy / TLS options

• --proxy supports:

  • http://host:port
  • https://host:port
  • socks5://host:port (and socks5h://host:port)

• --proxy-auth user:pass for HTTP Basic proxy auth or SOCKS5 auth

• --no-proxy ignores environment proxy variables

• --insecure/-k disables TLS verification (curl-style)

Silent mode

• --silent/-s suppresses the banner and prints only results (no decorations)

Hidden easter egg

• --thc prints a greets message and exits (not listed in help)

---

API reference (upstream docs)

• Reverse DNS lookup: https://ip.thc.org/docs/API/reverse-dns-lookup
• Subdomain lookup: https://ip.thc.org/docs/API/subdomain-lookup
• CNAME lookup: https://ip.thc.org/docs/API/cname-lookup

---

Installation

Requirements

• Go 1.22+
• Network access to ip.thc.org (unless you route through a proxy)

---

Build from source

git clone https://github.com/haltman-io/ip-thc.git
cd ip-thc

go mod download
go build -o ./ip-thc ./cmd/ip-thc

Run:

./ip-thc --help

---

Install into $GOBIN (recommended)

Go installs binaries into:

• $GOBIN if set, otherwise
• $GOPATH/bin (commonly ~/go/bin)

Option A — go install (best)

From the repository root:

go install ./cmd/ip-thc

Now ip-thc should be available on your PATH if $GOBIN (or $GOPATH/bin) is in PATH.

Verify:

command -v ip-thc
ip-thc --help

Option B — build + move to $GOBIN

go build -o ip-thc ./cmd/ip-thc
mv ip-thc "${GOBIN:-$HOME/go/bin}/ip-thc"

Ensure your PATH includes the bin directory:

export PATH="${GOBIN:-$HOME/go/bin}:$PATH"

---

Usage

Help

ip-thc --help

Reverse DNS (IP → domains)

ip-thc -rdns -t 1.1.1.1

All pages:

ip-thc -rdns -t 1.1.1.1 --all

Subdomains (domain → subdomains)

ip-thc -sub -t example.com

Multiple targets (comma-separated):

ip-thc -sub -t google.com,twitter.com

Multiple targets (repeat flag):

ip-thc -sub -t google.com -t twitter.com

CNAME lookup (target domain → domains pointing to it)

ip-thc -cn -t github.io

---

Targets from file(s)

Single list:

ip-thc -sub -tL targets.txt

Multiple files:

ip-thc -sub -tL targets1.txt -tL targets2.txt

Multiple files (comma-separated):

ip-thc -sub -tL targets1.txt,targets2.txt

---

Targets from STDIN (pipeline)

STDIN must be explicitly enabled:

cat targets.txt | ip-thc --stdin -sub

Pipeline + extra targets combined:

cat targets.txt | ip-thc --stdin -sub -t example.com

---

Output to file (sorted + deduped)

ip-thc -sub -t example.com --all -o subdomains.txt

The file will contain unique entries, sorted lexicographically.

---

Rate limiting & operational safety

Client-side rate-limit

Default:

• --rate-limit 5 (requests per second)

Tune it:

ip-thc -sub -t example.com --rate-limit 2

Server hints

If the server sends:

• X-Ratelimit-Remaining < 5

ip-thc will pause silently for 15 seconds to reduce the chance of hitting hard limits.

You should still use conservative settings when running at scale. Don’t abuse public services.

---

Proxy usage

HTTP proxy (no auth)

ip-thc -sub -t example.com --proxy http://127.0.0.1:8080

HTTP proxy with auth

ip-thc -sub -t example.com --proxy http://127.0.0.1:8080 --proxy-auth user:pass

SOCKS5 proxy

ip-thc -sub -t example.com --proxy socks5://127.0.0.1:9050

SOCKS5 proxy with auth

ip-thc -sub -t example.com --proxy socks5://127.0.0.1:9050 --proxy-auth user:pass

Ignore proxy environment variables

ip-thc -sub -t example.com --proxy http://127.0.0.1:8080 --no-proxy

---

TLS bypass

Disable TLS verification (curl -k style):

ip-thc -sub -t example.com -k

Use only when you fully understand the risk (MITM visibility, etc.).

---

Debugging

Enable debug logs to STDERR:

ip-thc -sub -t example.com --debug

Debug includes:

• Request path + request JSON
• HTTP status + truncated response payload
• Worker/target execution traces

---

Exit codes

• 0 → success (no fatal errors)
• 1 → completed but at least one target failed
• 2 → invalid arguments / configuration / initialization errors

---

Security & ethics

This tool is intended for:

• authorized security assessments,
• lawful investigation,
• defensive research,
• and legitimate bug bounty activity.

You are responsible for complying with:

• applicable laws,
• scope boundaries,
• and the upstream service’s acceptable use policies.

---

License

This project is licensed under the Unlicense, see the LICENSE file for details.

---

Acknowledgements

• Public intelligence API: ip.thc.org
• Inspired by the operational needs of offensive and investigative practitioners