ip-thc (v1.0.0-stable)

A fast, operator-friendly CLI for querying the ip.thc.org public intelligence API (dataset advertised as ~4.7B 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

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
cmd/ip-thc		cmd/ip-thc
docs/screenshots		docs/screenshots
internal		internal
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod
go.sum		go.sum

License

haltman-io/ip-thc

Folders and files

Latest commit

History

Repository files navigation

ip-thc (v1.0.0-stable)

Screenshot / Demo

Why ip-thc exists

Features

Overview

Query modes (mutually exclusive)

Target ingestion (3 sources)

Pagination (auto-scroll)

Operational controls

Output

Proxy / TLS options

Silent mode

Hidden easter egg

API reference (upstream docs)

Installation

Requirements

Build from source

Install into $GOBIN (recommended)

Option A — go install (best)

Option B — build + move to $GOBIN

Usage

Help

Reverse DNS (IP → domains)

Subdomains (domain → subdomains)

CNAME lookup (target domain → domains pointing to it)

Targets from file(s)

Targets from STDIN (pipeline)

Output to file (sorted + deduped)

Rate limiting & operational safety

Client-side rate-limit

Server hints

Proxy usage

HTTP proxy (no auth)

HTTP proxy with auth

SOCKS5 proxy

SOCKS5 proxy with auth

Ignore proxy environment variables

TLS bypass

Debugging

Exit codes

Security & ethics

License

Acknowledgements

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Option A — `go install` (best)

Packages