# alterx: permutation patterns for subdomain wordlists, in the style of a nuclei template

> alterx is a Go tool that generates subdomain permutations from patterns rather than from a fixed wordlist, using a variable syntax borrowed from nuclei templates, so a small set of discovered subdomains can be turned into a few hundred candidates instead of a few million. It also mines patterns automatically from the input and can enrich a wordlist by extracting words from it.

**projectdiscovery/alterx** — Fast and customizable subdomain wordlist generator using DSL

- Repository: https://github.com/projectdiscovery/alterx
- Stars: 1,018 · Forks: 80
- Language: Go
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/projectdiscovery-alterx

## The problem it solves: brute force volume is the bottleneck

The README makes the argument for the tool's existence in a compact form. Active subdomain enumeration is difficult because of the probability of finding a domain that actually exists, and the project description frames the options as a scale, where a generic wordlist sits below generate permutations with subdomains, and alterx sits above that. Almost all popular subdomain permutation tools have hardcoded patterns, and when such tools are run they create wordlists containing subdomains in millions, which decreases the feasibility of bruteforcing them with tools like dnsx. The reason is simple, and the README states it, that there is no actual convention to name subdomains and it usually depends on the person registering the subdomain. So the answer is to create patterns based on results from passive subdomain enumeration, which increases the probability of finding a subdomain and the feasibility to bruteforce them.

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

## The variable syntax, which is the whole user interface

alterx uses a variable-like syntax similar to nuclei-templates, so you write your own patterns using these variables, and when domains are passed as input alterx evaluates the input and extracts variables from it. The basic variables are {{sub}}, the subdomain prefix or left most part of a subdomain, {{suffix}}, everything except {{sub}} in the subdomain name, {{tld}}, the top level domain name such as com, uk or in, and {{etld}}, the public suffix such as co.uk or gov.in. The documentation gives a worked table: for api.scanme.sh, {{sub}} is api, {{suffix}} is scanme.sh and {{tld}} is sh, while for cloud.scanme.co.uk the {{etld}} is co.uk. The advanced variables add {{sld}} for the second level domain, {{root}} for the root domain, also known as eTLD+1, and {{subN}} where N is an integer, so {{sub1}} and {{sub2}} address the levels of a multi level subdomain such as cloud.nuclei.scanme.sh.

```yaml
{{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)
```

## Pattern mining, and why it is the feature that matters most

The feature list names pattern mining, the automatic discovery of subdomain patterns, and it is a Go port of Regulator. This is the feature that turns the tool from a template engine into something you can point at a discovery result and let it work out the conventions for itself. The other features are fast and customizable, automatic word enrichment, pre-defined variables, configurable patterns, stdin or list input, and multiple operation modes of default, discover and both. The enrichment option is worth noting separately, since the -en flag enriches the wordlist by extracting words from the input, which means the tool can mine its own vocabulary from the target's subdomains rather than from a generic list. Combined with mining, the two features are the difference between generating candidates that match the target's naming and generating a million that do not.

## Installing and building it, with the Go version the README asks for

To install alterx you need Golang 1.19 installed on your system, and then the command is go install github.com/projectdiscovery/alterx/cmd/alterx@latest. Building from source is documented too, with a clone of the repository, a make build using the Makefile, or a manual go build ./cmd/alterx. The available Makefile targets are listed in full, make help to show all targets, make build for the binary, make test, make test-coverage, make lint, make fmt, make clean and make install to install to $GOPATH/bin. The Makefile itself shows how the binary is built, with the -s -w ldflags for a stripped build, and that the lint target requires golangci-lint and fails with an install hint if it is missing. There is a Dockerfile as well, based on alpine, with the OCI labels for the project and the maintainer group, adding bind-tools and ca-certificates.

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

git clone https://github.com/projectdiscovery/alterx.git
cd alterx
make build
```

## The flags, and the estimate option that saves a whole run

The help menu is the reference for what the tool can do, and the flag groups are input, output, config and update. On the input side, -l and -list take subdomains to use when creating permutations, from stdin, comma-separated or a file, and -p and -pattern take custom permutation patterns, comma-separated or a file. There is also -pp and -payload for a custom payload pattern in key=value format, for example a word pointing at a words.txt file, and the pattern flags are repeatable. On the output side, -es and -estimate estimates the permutation count without generating payloads, which is the flag that turns a runaway generation into a planning step, -o writes the altered subdomain list to a file, -ms and -max-size caps the export data size in kb, mb, gb or tb, and -limit caps the number of results. The config group holds -config for the CLI config file, -en for enrichment, -ac for the permutation config file, and the update group has -up and -duc.

```console
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)
   -limit int      limit the number of results to return (default 0)
```

## The configuration file, and what the repository layout reveals

The default paths are inside the user's config directory, with the CLI config at $HOME/.config/alterx/config.yaml and the permutation config at $HOME/.config/alterx/permutation_v0.0.1.yaml, which tells you the pattern format is versioned independently of the tool, so a pattern file written for one version keeps working. The repository layout matches the architecture of the tool, with algorithm and mutator and replacer logic in the top level Go files, algo.go, mutator.go, replacer.go, config.go, inputs.go and util.go, a dedupe_writer.go with its own test, the cmd/ directory for the CLI, an internal/ directory, a static/ directory, an examples/ directory with a main.go, and permutations.yaml in the root as a reference pattern set. The dependencies are ProjectDiscovery's own, with fasttemplate doing the templating, goflags for the CLI, gologger for logging and utils, plus yaml.v3, testify and golang.org/x/net. The module targets go 1.25.0.

## Where this sits against the alternatives, and the honest limitation

The README compares itself to goaltdns directly, and the differentiator it names is the scripting feature, since alterx takes patterns as input and generates the wordlist from that pattern, similar to how nuclei works with its fuzzing-templates. That is a real difference in kind rather than degree, because a pattern file is a small artefact you can review and share, while a hardcoded wordlist is a large opaque artefact you cannot. The limitation follows the same shape. alterx only produces candidates, and the README is explicit that the brute force step itself is done by another tool, dnsx, so alterx is one stage of a pipeline rather than a scanner. The scale of the win is also bounded by the input: the tool can only mine conventions from subdomains it has already been given, so a target where passive enumeration found three names gives you three names' worth of patterns and nothing more.

## Conclusion

alterx suits a security engineer working on an authorised scope who has a handful of discovered subdomains and wants a targeted candidate list rather than a generic wordlist, and who is comfortable writing a small pattern file. It is the wrong tool if you have no input to derive patterns from, because the whole value is in the relationship between the observed subdomains and the generated ones, and a poor fit for a large surface where a general wordlist and mass resolution is the actual strategy. Before adopting it, read the permutation config file, since a default configuration exists and your patterns have to match the naming conventions of the target, and note that the tool generates a list rather than resolving it, so the resolution step is a separate tool in your workflow.

## FAQ

### What is alterx?

It is a fast and customizable subdomain wordlist generator using a DSL, written in Go by ProjectDiscovery. Instead of generating millions of permutations from a generic wordlist, it takes patterns as input and generates candidates from those patterns, in a way the README compares to how nuclei works with fuzzing-templates.

### How do I install alterx?

You need Golang 1.19 installed, then run go install github.com/projectdiscovery/alterx/cmd/alterx@latest. To build from source, clone the repository and run make build, or go build ./cmd/alterx manually, and the Makefile also offers make test, make test-coverage, make lint, make fmt, make clean and make install.

### Which variables can I use in alterx patterns?

alterx uses nuclei-template style variables. The basic ones are {{sub}}, {{suffix}}, {{tld}} and {{etld}}, and the advanced ones are {{sld}}, {{root}} and {{subN}} where N is an integer for the levels of a multi level subdomain. When input domains are supplied, alterx evaluates the input and extracts the variables from it.

### Does alterx scan or resolve the subdomains it generates?

No, it generates a candidate list. The README describes the brute force step as being done with another tool such as dnsx, and alterx's own role is producing a smaller, higher probability list from the patterns.

### What do the main alterx flags do?

On input, -l and -list take subdomains from stdin, comma-separated or a file, -p and -pattern take custom permutation patterns, and -pp takes a payload pattern in key=value format. On output, -es estimates the permutation count without generating payloads, -o writes the list to a file, -ms caps the export size and -limit caps the number of results. The config group includes -config, -en for enrichment and -ac for the permutation config file.

## Sources

- [Issues](https://github.com/projectdiscovery/alterx/issues)
- [License: MIT](https://github.com/projectdiscovery/alterx/blob/main/LICENSE)
- [projectdiscovery/alterx on GitHub](https://github.com/projectdiscovery/alterx)
- [README](https://github.com/projectdiscovery/alterx/blob/main/README.md)
- [Releases](https://github.com/projectdiscovery/alterx/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/projectdiscovery-alterx