alterx

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 11, 2025 License: MIT Imports: 23 Imported by: 4

README

AlterX

Features • Installation • Usage • Running AlterX • Join Discord 


   Fast and customizable subdomain wordlist generator using DSL.

image

Features

  • Fast and Customizable
  • Automatic word enrichment
  • Pre-defined variables
  • Configurable Patterns
  • Pattern Mining - Automatically discover subdomain patterns (Go port of Regulator)
  • STDIN / List input
  • Multiple operation modes (default, discover, both)

Installation

To install alterx, you need to have Golang 1.19 installed on your system. You can download Golang from here. After installing Golang, you can use the following command to install alterx:

go install github.com/projectdiscovery/alterx/cmd/alterx@latest

Building from Source

# Clone the repository
git clone https://github.com/projectdiscovery/alterx.git
cd alterx

# Build using Makefile
make build

# Or build manually
go build ./cmd/alterx

Available Makefile targets:

make help          # Show all available targets
make build         # Build the binary
make test          # Run tests
make test-coverage # Run tests with coverage
make lint          # Run linter
make fmt           # Format code
make clean         # Clean build artifacts
make install       # Install to $GOPATH/bin

Help Menu

You can use the following command to see the available flags and options:

Fast and customizable subdomain wordlist generator using DSL.

Usage:
  ./alterx [flags]

Flags:
INPUT:
   -l, -list string[]     subdomains to use when creating permutations (stdin, comma-separated, file)
   -p, -pattern string[]  custom permutation patterns input to generate (comma-seperated, file)
   -pp, -payload value    custom payload pattern input to replace/use in key=value format (-pp 'word=words.txt')

OUTPUT:
   -es, -estimate      estimate permutation count without generating payloads
   -o, -output string  output file to write altered subdomain list
   -ms, -max-size int  Max export data size (kb, mb, gb, tb) (default mb)
   -v, -verbose        display verbose output
   -silent             display results only
   -version            display alterx version

CONFIG:
   -config string  alterx cli config file (default '$HOME/.config/alterx/config.yaml')
   -en, -enrich    enrich wordlist by extracting words from input
   -ac string      alterx permutation config file (default '$HOME/.config/alterx/permutation_v0.0.1.yaml')
   -limit int      limit the number of results to return (default 0)

UPDATE:
   -up, -update                 update alterx to latest version
   -duc, -disable-update-check  disable automatic alterx update check

Why alterx ??

what makes alterx different from any other subdomain permutation tools like goaltdns is its scripting feature . alterx takes patterns as input and generates subdomain permutation wordlist based on that pattern similar to what nuclei does with fuzzing-templates .

What makes Active Subdomain Enumeration difficult is the probability of finding a domain that actually exists. If finding possible subdomains is represented on a scale it should look something like

   Using Wordlist < generate permutations with subdomains (goaltdns) < alterx

Almost all popular subdomain permutation tools have hardcoded patterns and when such tools are run they create wordlist which contain subdomains in Millions and this decreases the feasibility of bruteforcing them with tools like dnsx . There is no actual convention to name subdomains and usually depends on person registering the subdomain. with alterx it is possible to create patterns based on results from passive subdomain enumeration results which increases probability of finding a subdomain and feasibility to bruteforce them.

Variables

alterx uses variable-like syntax similar to nuclei-templates. One can write their own patterns using these variables . when domains are passed as input alterx evaluates input and extracts variables from it .

Basic / Common Variables

{{sub}}     :  subdomain prefix or left most part of a subdomain
{{suffix}}  :  everything except {{sub}} in subdomain name is suffix
{{tld}}     :  top level domain name (ex com,uk,in etc)
{{etld}}    :  also know as public suffix (ex co.uk , gov.in etc)
Variable api.scanme.sh admin.dev.scanme.sh cloud.scanme.co.uk
{{sub}} api admin cloud
{{suffix}} scanme.sh dev.scanme.sh scanme.co.uk
{{tld}} sh sh uk
{{etld}} - - co.uk

Advanced Variables

{{sld}}  :   second-level domain  (ex for api.scanme.sh => {{sld}} is scanme)
{{root}}  :  also known as eTLD+1 i.e only root domain (ex for api.scanme.sh => {{root}} is scanme.sh)
{{subN}}  :  here N is an integer (ex {{sub1}} , {{sub2}} etc) .

// {{subN}} is advanced variable which exists depending on input
// lets say there is a multi level domain cloud.nuclei.scanme.sh
// in this case {{sub}} = cloud and {{sub1}} = nuclei`
Variable api.scanme.sh admin.dev.scanme.sh cloud.scanme.co.uk
{{sld}} scanme scanme scanme
{{root}} scanme.sh scanme.sh scanme.co.uk
{{sub1}} - dev -
{{sub2}} - - -

Patterns

pattern in simple terms can be considered as template that describes what type of patterns should alterx generate.

// Below are some of example patterns which can be used to generate permutations
// assuming api.scanme.sh was given as input and variable {{word}} was given as input with only one value prod
// alterx generates subdomains for below patterns

"{{sub}}-{{word}}.{{suffix}}" // ex: api-prod.scanme.sh
"{{word}}-{{sub}}.{{suffix}}" // ex: prod-api.scanme.sh
"{{word}}.{{sub}}.{{suffix}}" // ex: prod.api.scanme.sh
"{{sub}}.{{word}}.{{suffix}}" // ex: api.prod.scanme.sh

Here is an example pattern config file - https://github.com/projectdiscovery/alterx/blob/main/permutations.yaml that can be easily customizable as per need.

This configuration file generates subdomain permutations for security assessments or penetration tests using customizable patterns and dynamic payloads. Patterns include dash-based, dot-based, and others. Users can create custom payload sections, such as words, region identifiers, or numbers, to suit their specific needs.

For example, a user could define a new payload section env with values like prod and dev, then use it in patterns like {{env}}-{{word}}.{{suffix}} to generate subdomains like prod-app.example.com and dev-api.example.com. This flexibility allows tailored subdomain list for unique testing scenarios and target environments.

Default pattern config file used for generation is stored in $HOME/.config/alterx/ directory, and custom config file can be also used using -ac option.

Examples

An example of running alterx on existing list of passive subdomains of tesla.com yield us 10 additional NEW and valid subdomains resolved using dnsx.

$ chaos -d tesla.com | alterx | dnsx



   ___   ____          _  __
  / _ | / / /____ ____| |/_/
 / __ |/ / __/ -_) __/>  <
/_/ |_/_/\__/\__/_/ /_/|_|

      projectdiscovery.io

[INF] Generated 8312 permutations in 0.0740s
auth-global-stage.tesla.com
auth-stage.tesla.com
digitalassets-stage.tesla.com
errlog-stage.tesla.com
kronos-dev.tesla.com
mfa-stage.tesla.com
paymentrecon-stage.tesla.com
sso-dev.tesla.com
shop-stage.tesla.com
www-uat-dev.tesla.com

Similarly -enrich option can be used to populate known subdomains as world input to generate target aware permutations.

$ chaos -d tesla.com | alterx -enrich

   ___   ____          _  __
  / _ | / / /____ ____| |/_/
 / __ |/ / __/ -_) __/>  <
/_/ |_/_/\__/\__/_/ /_/|_|

      projectdiscovery.io

[INF] Generated 662010 permutations in 3.9989s

You can alter the default patterns at run time using -pattern CLI option.

$ chaos -d tesla.com | alterx -enrich -p '{{word}}-{{suffix}}'

   ___   ____          _  __
  / _ | / / /____ ____| |/_/
 / __ |/ / __/ -_) __/>  <
/_/ |_/_/\__/\__/_/ /_/|_|

      projectdiscovery.io

[INF] Generated 21523 permutations in 0.7984s

It is also possible to overwrite existing variables value using -payload CLI options.

$ alterx -list tesla.txt -enrich -p '{{word}}-{{year}}.{{suffix}}' -pp word=keywords.txt -pp year=2023

   ___   ____          _  __
  / _ | / / /____ ____| |/_/
 / __ |/ / __/ -_) __/>  <
/_/ |_/_/\__/\__/_/ /_/|_|

      projectdiscovery.io

[INF] Generated 21419 permutations in 1.1699s

For more information, please checkout the release blog - https://blog.projectdiscovery.io/introducing-alterx-simplifying-active-subdomain-enumeration-with-patterns/

Do also check out the below similar open-source projects that may fit in your workflow:

altdns, goaltdns, gotator, ripgen, dnsgen, dmut, permdns, str-replace, dnscewl, regulator

alterx is made with ❤️ by the projectdiscovery team and distributed under MIT License.

Join Discord

Documentation

Index

Constants

View Source 
const (
	// General marker (open/close)
	General = "§"
	// ParenthesisOpen marker - begin of a placeholder
	ParenthesisOpen = "{{"
	// ParenthesisClose marker - end of a placeholder
	ParenthesisClose = "}}"
)

Variables

View Source 
var (
	DedupeResults = true // Dedupe all results (default: true)
)
View Source 
var DefaultPermutationsBin []byte

Functions

func ClusterBomb 

func ClusterBomb(payloads *IndexMap, callback func(varMap map[string]interface{}), Vector []string)

Nth Order ClusterBomb with variable length array/values

func Replace 

func Replace(template string, values map[string]interface{}) string

Replace replaces placeholders in template with values on the fly.

Types

type Config 

type Config struct {
	Patterns []string            `yaml:"patterns"`
	Payloads map[string][]string `yaml:"payloads"`
}
var DefaultConfig Config

DefaultConfig contains default patterns and payloads

func NewConfig 

func NewConfig(filePath string) (*Config, error)

NewConfig reads config from file

type DedupingWriter added in v0.1.0 

type DedupingWriter struct {
	// contains filtered or unexported fields
}

DedupingWriter wraps an io.Writer with transparent deduplication using dedupe utils

func NewDedupingWriter added in v0.1.0 

func NewDedupingWriter(w io.Writer, seed ...string) *DedupingWriter

NewDedupingWriter creates a new DedupingWriter with optional blacklist/seed The seed parameter allows pre-populating items to skip

func (*DedupingWriter) Close added in v0.1.0 

func (dw *DedupingWriter) Close() error

Close flushes any remaining data and closes the writer

func (*DedupingWriter) Count added in v0.1.0 

func (dw *DedupingWriter) Count() int

Count returns the number of unique items written

func (*DedupingWriter) Write added in v0.1.0 

func (dw *DedupingWriter) Write(p []byte) (int, error)

Write implements io.Writer interface

type IndexMap 

type IndexMap struct {
	// contains filtered or unexported fields
}

func NewIndexMap 

func NewIndexMap(values map[string][]string) *IndexMap

NewIndexMap returns type such that elements of map can be retrieved by a fixed index

func (*IndexMap) Cap 

func (o *IndexMap) Cap() int

func (*IndexMap) GetNth 

func (o *IndexMap) GetNth(n int) []string

func (*IndexMap) KeyAtNth 

func (o *IndexMap) KeyAtNth(n int) string

KeyAtNth returns key present at Nth position

type Input 

type Input struct {
	TLD        string   // only TLD (right most part of subdomain) ex: `.uk`
	ETLD       string   // Simply put public suffix (ex: co.uk)
	SLD        string   // Second-level domain (ex: scanme)
	Root       string   // Root Domain (eTLD+1) of Subdomain
	Sub        string   // Sub or LeftMost prefix of subdomain
	Suffix     string   // suffix is everything except `Sub` (Note: if domain is not multilevel Suffix==Root)
	MultiLevel []string // (Optional) store prefix of multi level subdomains
}

Input contains parsed/evaluated data of a URL

func NewInput 

func NewInput(inputURL string) (*Input, error)

NewInput parses URL to Input Vars

func (*Input) GetMap 

func (i *Input) GetMap() map[string]interface{}

GetMap returns variables map of input

type Mutator 

type Mutator struct {
	Options *Options

	Inputs []*Input // all processed inputs
	// contains filtered or unexported fields
}

Mutator

func New 

func New(opts *Options) (*Mutator, error)

New creates and returns new mutator instance from options

func (*Mutator) DryRun 

func (m *Mutator) DryRun() int

DryRun executes payloads without storing and returns number of payloads created this value is also stored in variable and can be accessed via getter `PayloadCount`

func (*Mutator) EstimateCount 

func (m *Mutator) EstimateCount() int

EstimateCount estimates number of payloads that will be created without actually executing/creating permutations

func (*Mutator) Execute 

func (m *Mutator) Execute(ctx context.Context) <-chan string

Execute calculates all permutations using input wordlist and patterns and writes them to a string channel

func (*Mutator) ExecuteWithWriter 

func (m *Mutator) ExecuteWithWriter(Writer io.Writer) error

ExecuteWithWriter executes Mutator and writes results directly to type that implements io.Writer interface

func (*Mutator) PayloadCount 

func (m *Mutator) PayloadCount() int

PayloadCount returns total estimated payloads count

func (*Mutator) SaveRules added in v0.1.0 

func (m *Mutator) SaveRules(filename string) error

SaveRules saves pattern mining result to a file

func (*Mutator) Time 

func (m *Mutator) Time() string

Time returns time taken to create permutations in seconds

type Options 

type Options struct {
	// list of Domains to use as base
	Domains []string
	// list of words to use while creating permutations
	// if empty DefaultWordList is used
	Payloads map[string][]string
	// list of pattersn to use while creating permutations
	// if empty DefaultPatterns are used
	Patterns []string
	// Limits output results (0 = no limit)
	Limit int
	// Enrich when true alterx extra possible words from input
	// and adds them to default payloads word,number
	Enrich bool
	// MaxSize limits output data size
	MaxSize int
	// Mode specifies the operation mode: "default" (default), "discover" (pattern mining only), "both" (combined)
	// Empty string defaults to "default" mode for backwards compatibility
	Mode string
	// MinDistance is the minimum levenshtein distance for clustering
	MinDistance int
	// MaxDistance is the maximum levenshtein distance for clustering
	MaxDistance int
	// PatternThreshold is the threshold for pattern quality filtering
	PatternThreshold int
	// QualityRatio is the maximum ratio of synthetic/observed for pattern validation
	QualityRatio float64
	// NgramsLimit limits the number of n-grams to process (0 = no limit)
	NgramsLimit int
	// MaxLength is the maximum pattern length
	MaxLength int
}

Mutator Options

func (*Options) Validate added in v0.1.0 

func (v *Options) Validate() error

Source Files

View all Source files

Directories

Path Synopsis
cmd
alterx command
internal
dank
patternmining
runner

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.