sub-alter

OSINT CLI for domain and subdomain discovery using pattern-based filters

sub-alter is a production-grade OSINT command-line tool maintained by a member of Haltman.io. It queries a commercial domains/subdomains discovery dataset to enumerate domains and subdomains that match user-defined include/exclude patterns.

The tool is designed for investigations where analysts need to pivot from a known term (brand, domain fragment, provider name) and discover related assets using wildcard-style literal patterns, while excluding noise.

Typical use cases:

  • Brand and trademark monitoring

  • Vendor and third-party footprint discovery

  • Infrastructure mapping and OSINT enrichment

  • Security investigations requiring controlled enumeration

The focus is repeatable CLI usage, explicit API control, and clean output suitable for piping into other tools.

Wildcard Domain Search

Installation

Requirements

  • Go 1.22+

  • Valid Domains/Subdomains Discovery API key (WhoisXML)

Build from source (recommended)

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

Run:

./sub-alter -h

Install into $GOBIN

go install github.com/haltman-io/sub-alter/cmd/sub-alter@latest

Verify:

sub-alter -h

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

Configuration

API key configuration (required)

An API key is required to query the provider.

Option 1 — CLI flag (highest priority)

sub-alter --api-key YOUR_API_KEY -di "*example.com*"

Option 2 — YAML config file (recommended)

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

.sub-alter.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, keys are rotated round-robin per request

  • If no key is available, execution aborts with an error

Usage

Basic domain discovery

sub-alter -di "*example.com*"

This searches for domains containing example.com anywhere.

Domain include / exclude filters

sub-alter -di "example.com" -de "test.example.com"

Notes:

  • Include and exclude lists are enforced by the provider

  • Maximum 4 items per include/exclude array

Subdomain include / exclude filters

sub-alter -si "aws*" -se "*portal*" -se "*beta*"

Use case:

  • Discover subdomains starting with aws

  • Exclude common noise like portals or beta environments

Wildcard Subdomain Enum

Mixed filters (domains + subdomains)

sub-alter -di "google.com" -di "twitter.com" -se "*portal*"

Output to file (clean & deduplicated)

sub-alter -di "*example.com*" -o results.txt

Behavior:

  • File is overwritten if it exists

  • One domain per line

  • No ANSI colors

  • Deduplicated output

Possible Problems / Important Notes

Provider limits

  • API hard limit: 30 requests per second

  • The tool rejects values above this limit

sub-alter -di "*example.com*" -rl 10

Include / exclude constraints

  • Each include/exclude array supports max 4 items

  • Exceeding this limit causes the tool to exit with an error

Proxy and TLS behavior

Supported proxy schemes:

  • http://

  • https://

  • socks5://

Example:

sub-alter -di "*example.com*" --proxy socks5://127.0.0.1:9050

Disable TLS verification (dangerous):

sub-alter -di "*example.com*" -k

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

API cost awareness

  • This provider may bill per request

  • The tool sends only fields explicitly requested via flags

  • Avoid unnecessary wildcard searches in large investigations

External References

Updated on
reverse-whois
brave-search