sub-alter

README

sub-alter

Production-grade OSINT CLI tool to query a commercial Domains/Subdomains Discovery dataset and enumerate domains and subdomains that match user-defined include/exclude patterns (wildcards supported as literal strings), built for cybersecurity analysts and investigation workflows.

Repository: https://github.com/haltman-io/sub-alter

---

Why this exists

During investigations, brand monitoring, vendor review, or infrastructure mapping, you often need to pivot from a known term (e.g., example.com) to discover:

• domains ending with a term (*example.com)
• domains starting with a term (example.com*)
• domains containing a term anywhere (*example.com*)
• subdomains matching patterns (e.g., aws*) while excluding noise (e.g., *portal*)

This tool provides a repeatable CLI interface with robust configuration, proxy support, and clean output suitable for piping into other tools.

---

Features

• Query a commercial domains/subdomains discovery API

• Include/exclude filters:

  • domains.include[], domains.exclude[]
  • subdomains.include[], subdomains.exclude[]

• Accepts multiple values per flag:

  • repeatable flags (-di a -di b)
  • comma-separated lists (-di a,b)

• Provider constraints enforced:

  • maximum 4 items per include/exclude array

• API key handling:

  • --api-key takes priority
  • fallback YAML config near the executable: .sub-alter.yaml
  • supports multiple keys with round-robin rotation (per request)

• Network features (baseline):

  • HTTP/HTTPS and SOCKS5 proxy support via --proxy
  • respect HTTP_PROXY, HTTPS_PROXY, NO_PROXY unless --no-proxy
  • TLS bypass via --insecure/-k (curl-style)

• Rate limiting:

  • --rate-limit/-rl global max requests/sec
  • API hard limit: 30 rps (tool rejects values > 30)

• Output:

  • ANSI colored terminal output (subtle: only content inside [] is colored), disable with --no-color/-nc
  • --output/-o/-out writes clean, deduplicated results for tooling chains

---

Screenshot / Demo

---

Data source / API

Endpoint:

• https://domains-subdomains-discovery.whoisxmlapi.com/api/v1

Required header:

• Content-Type: application/json

Request fields used by this tool

• apiKey (required)
• domains.include (optional, max 4)
• domains.exclude (optional, max 4)
• subdomains.include (optional, max 4)
• subdomains.exclude (optional, max 4)

Note: This provider API can be billed per query. This tool constructs the JSON body strictly based on user input and does not send unused properties.

---

Output format

The tool prints structured lines for easy parsing:

• Count line:

  • [domainsCount: <n>]

• Domain lines:

  • [domain: <value>]

Example:

[domainsCount: 26]
[domain: thehackerschoice.fallguysmania.com]
[domain: hackerschoice.github.io]
...

---

Output to file (--output/-o/-out)

When --output is provided:

• stdout remains normal (colored if enabled)

• the output file receives only the clean, deduplicated domain list:

  • no ANSI escape codes
  • one domain per line
  • overwrite behavior

Example:

sub-alter --api-key "$API_KEY" -di "*thc.org*" -o results.txt

results.txt:

thehackerschoice.fallguysmania.com
hackerschoice.github.io
hackerschoice.workers.dev
...

Overwrite behavior: if results.txt exists, it is overwritten.

Note: Parent directories are not created automatically. Invalid paths cause the tool to exit with an error.

---

Installation

Requirements

• Go 1.22+

Option A) 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
./sub-alter -h

Option B) Install to $GOBIN

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

If the binary is not found, ensure:

• $GOBIN or $(go env GOPATH)/bin is in your PATH.

---

Configuration: API keys (.sub-alter.yaml)

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

• .sub-alter.yaml

If it does not exist, it is created automatically with:

api_keys: []

API key resolution

1. If --api-key <KEY> is provided → used for the request.

2. Else, .sub-alter.yaml is read:

   • if api_keys is empty → tool exits with an error
   • if multiple keys exist → keys rotate round-robin (per request)

---

Usage

Flags

API

• --api-key <key> Provide API key (overrides YAML config).

Domains filters

• --domain-include <value> (alias: -di) Add to .domains.include[] (repeatable / comma-separated, max 4).
• --domain-exclude <value> (alias: -de) Add to .domains.exclude[] (repeatable / comma-separated, max 4).

Subdomains filters

• --subdomain-include <value> (alias: -si) Add to .subdomains.include[] (repeatable / comma-separated, max 4).
• --subdomain-exclude <value> (alias: -se) Add to .subdomains.exclude[] (repeatable / comma-separated, max 4).

Proxy / TLS

• --proxy <url> Proxy URL: http://, https://, socks5://
• --no-proxy Ignore HTTP_PROXY/HTTPS_PROXY/NO_PROXY.
• --insecure (alias: -k) Skip TLS certificate verification.

Rate limit / concurrency

• --rate-limit <rps> (alias: -rl) Max requests per second, must be 1..30 (API limit).
• --threads <n> Worker threads baseline flag (validated; current tool makes a single request per execution).

Output & logging

• --output <path> (aliases: -o, -out) Write clean, deduplicated domain results to file (overwrite).
• --silent (alias: -s) / --quiet (alias: -q) Hide banner (results only).
• --verbose (alias: -v) / --debug Debug logs (stderr).
• --no-color (alias: -nc) Disable ANSI colors.

---

Examples

1) Simple domain search

sub-alter --api-key "$API_KEY" -di "*example.com"

2) Multiple domain include terms

sub-alter --api-key "$API_KEY" -di google.com,twitter.com
sub-alter --api-key "$API_KEY" -di google.com -di twitter.com

3) Subdomain include + exclude

sub-alter --api-key "$API_KEY" -si "aws*" -se "*portal*" -se "*beta*"

4) Mixed filters (domains include + subdomains exclude)

sub-alter --api-key "$API_KEY" -di google.com -di twitter.com -se "*portal*"

5) Write clean output to file

sub-alter --api-key "$API_KEY" -di "*thc.org*" -o results.txt

6) Proxy usage

HTTP proxy:

sub-alter --api-key "$API_KEY" -di "*example.com*" --proxy http://127.0.0.1:8080

SOCKS5 proxy:

sub-alter --api-key "$API_KEY" -di "*example.com*" --proxy socks5://127.0.0.1:9050

Ignore environment proxies:

sub-alter --api-key "$API_KEY" -di "*example.com*" --no-proxy

7) TLS bypass (dangerous)

sub-alter --api-key "$API_KEY" -di "*example.com*" -k

Warning: --insecure/-k disables TLS verification. Use only when you understand the implications.

---

Error handling

The tool maps provider HTTP errors to direct user-facing messages:

• 400 Bad Request: missing/invalid request fields
• 401 Unauthorized: missing/invalid API key
• 403 Forbidden: restricted access / credits issue / wrong key
• 408 Request Timeout: provider timeout
• 410 Gone: API version deprecated
• 422 Unprocessable Entity: invalid parameters / search term
• 429 Too Many Requests: provider throttling
• 5XX: provider internal error (contact provider support)

---

Security & privacy notes

• Intended for authorized investigations and cybersecurity assessment workflows.
• API keys are sensitive credentials. Do not hardcode or commit them.
• Output file contains only domain strings (deduplicated) to support safe downstream tooling.

---

Contributing

Development setup

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

Project layout

• cmd/sub-alter/ — CLI entrypoint
• internal/cli/ — flags, validation, usage
• internal/api/ — HTTP client and request/response models
• internal/ratelimit/ — rate limiter utilities
• internal/output/ — banner, colors, formatting/printer
• internal/util/ — helpers (YAML keys, output file writer, etc.)

Guidelines

• Keep code/comments/logging in English
• Keep dependencies minimal
• Preserve stable output format unless necessary (document changes)
• Add tests where feasible

Pull Requests

• Provide clear summary and rationale
• Include before/after output snippets if formatting changes
• Update documentation when behavior changes

---

Vulnerability Reporting (Security)

If you discover a security issue in this repository:

1. Do not open a public GitHub issue.

2. Send a report with:

   • a clear description of the issue
   • impact assessment
   • reproduction steps / PoC (if applicable)
   • suggested remediation

3. Contact:

   • Create a private advisory (recommended) via GitHub Security Advisories (if enabled), or
   • Email the maintainers: security@haltman.io

---

License

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

---

Build & run

go build -o sub-alter ./cmd/sub-alter
./sub-alter -h