### Install DNSTwist with Full Dependencies

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Use this command to install DNSTwist along with all optional dependencies for full functionality.

```bash
pip install dnstwist[full]
```

--------------------------------

### Install DNSTwist on Fedora

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Install DNSTwist using the DNF package manager on Fedora Linux.

```bash
sudo dnf install dnstwist
```

--------------------------------

### Install DNStwist with Optional Dependencies

Source: https://context7.com/elceef/dnstwist/llms.txt

Install DNStwist using pip. The `[full]` option includes all optional dependencies for complete functionality.

```bash
pip install dnstwist[full]
```

```bash
pip install dnstwist
```

```bash
git clone https://github.com/elceef/dnstwist.git
cd dnstwist
pip install .
```

```bash
docker run -it elceef/dnstwist domain.name
```

```bash
docker build -t dnstwist:phash --build-arg phash=1 .
```

```bash
sudo apt install dnstwist
```

```bash
brew install dnstwist
```

--------------------------------

### Starting the DNStwist Web Server

Source: https://context7.com/elceef/dnstwist/llms.txt

Instructions for starting the Flask-based web server for the DNStwist REST API. Configuration can be done via environment variables or by running a Docker container.

```bash
# Run with defaults (127.0.0.1:8000)
cd webapp && python webapp.py

# Configure via environment variables
PORT=8080 HOST=0.0.0.0 THREADS=32 NAMESERVERS=1.1.1.1 python webapp.py

# Via Docker
docker run -p 8000:8000 elceef/dnstwist
```

--------------------------------

### Install DNSTwist Bare Minimum

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Install only the core DNSTwist package. Additional requirements can be added manually based on specific needs.

```bash
pip install dnstwist
```

--------------------------------

### Install DNSTwist from Git

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Clone the repository and install the latest version directly from the source code. This is useful for running the most recent development version.

```bash
git clone https://github.com/elceef/dnstwist.git
cd dnstwist
pip install .
```

--------------------------------

### Install DNSTwist on Arch Linux (AUR)

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Install DNSTwist from the Arch User Repository using an AUR helper like 'yay'.

```bash
yay -S dnstwist
```

--------------------------------

### Install DNSTwist on Debian/Ubuntu/Kali

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Install DNSTwist using the system's package manager on Debian-based systems. This command installs the tool with all extra packages.

```bash
sudo apt install dnstwist
```

--------------------------------

### Install DNSTwist on macOS with Homebrew

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Install DNSTwist on macOS using the Homebrew package manager. This command also adds the binary to your system's PATH.

```bash
brew install dnstwist
```

--------------------------------

### Programmatic Scan with dnstwist.run()

Source: https://context7.com/elceef/dnstwist/llms.txt

The `run()` function allows programmatic scanning using the same arguments as the CLI. It returns a list of dictionaries, each representing a domain permutation with its DNS data. Use `format='null'` to get a list of dicts.

```python
import dnstwist

# Basic scan - return only registered domains as a list of dicts
results = dnstwist.run(domain='example.com', registered=True, format='null')

for entry in results:
    print(entry['fuzzer'], entry['domain'], entry.get('dns_a', []))
# homoglyph  examp1e.com  ['185.53.178.5']
# addition   example0.com ['93.184.216.34']
```

```python
# JSON output format - useful for serialization
import json
results = dnstwist.run(domain='example.com', format='json')
# results is None when format is not 'null'; use format='null' for list return
```

```python
# Passive mode - generate permutations only, no DNS lookups
permutations = dnstwist.run(domain='example.com', format='list', output=dnstwist.devnull)
# Returns list of dicts: [{'fuzzer': 'addition', 'domain': 'example0.com'}, ...]
```

```python
# Scan with LSH phishing detection, geoip, and extra threads
results = dnstwist.run(
    domain='example.com',
    registered=True,
    lsh='ssdeep',
    geoip=True,
    threads=32,
    format='null'
)
for r in results:
    if r.get('ssdeep', 0) > 50:
        print(f"PHISHING ALERT: {r['domain']} - HTML similarity {r['ssdeep']}%  ")
# PHISHING ALERT: examp1e.com - HTML similarity 87%
```

```python
# Export results to JSON file
dnstwist.run(domain='example.com', format='json', output='results.json')
```

--------------------------------

### Export Scan Results to JSON

Source: https://context7.com/elceef/dnstwist/llms.txt

Run a full scan and export the results in JSON format. This example pipes the output to `jq` to select and format specific fields for registered domains.

```bash
$ dnstwist --format json example.com | jq '.[] | select(.dns_a != null) | {domain, dns_a}'
# Output:
# {
#   "domain": "examp1e.com",
#   "dns_a": ["185.53.178.5"]
# }
```

--------------------------------

### Run DNSTwist Docker Image

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Pull and run the official DNSTwist Docker image for immediate use without local installation.

```bash
docker run -it elceef/dnstwist
```

--------------------------------

### POST /api/scans

Source: https://context7.com/elceef/dnstwist/llms.txt

Starts a new asynchronous fuzzing and DNS scan session by submitting a domain to the web application.

```APIDOC
## POST /api/scans

### Description
Submit a domain to begin an asynchronous fuzzing and DNS scan session.

### Method
POST

### Endpoint
`/api/scans`

### Parameters
#### Request Body
- **url** (string) - Required - The domain name to scan.

### Request Example
```bash
curl -s -X POST http://127.0.0.1:8000/api/scans \
  -H 'Content-Type: application/json' \
  -d '{"url": "example.com"}' | jq
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the scan session.
- **timestamp** (integer) - The Unix timestamp when the scan was initiated.

### Response Example
```json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": 1706601600
}
```
```

--------------------------------

### Starting a New Scan Session via API

Source: https://context7.com/elceef/dnstwist/llms.txt

Use a `curl` command to send a POST request to the `/api/scans` endpoint to initiate an asynchronous fuzzing and DNS scan session for a given domain.

```bash
curl -s -X POST http://127.0.0.1:8000/api/scans \
  -H 'Content-Type: application/json' \
  -d '{"url": "example.com"}' | jq
# {
#   "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
#   "timestamp": 1706601600,
```

--------------------------------

### Get Bare Permutations List from DNSTwist

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Generate only the list of domain permutations without performing any DNS lookups. Use the `--format list` argument for this purpose.

```bash
dnstwist --format list domain.name
```

--------------------------------

### Initiate or Stop Scan

Source: https://github.com/elceef/dnstwist/blob/master/webapp/webapp.html

Handles the logic for starting a new scan or stopping an existing one. It sends requests to the backend API and updates the UI accordingly. Includes input validation for the domain name.

```javascript
function actionScan() { if (!$('#url').val()) { $('#status').html('↖ You need to type in a domain name first'); return } if ($('#scan').text() == 'Scan') { last_registered = 0; $('#scan').text('⏱'); $.post({ url: '/api/scans', data: JSON.stringify({'url': $('#url').val()}), contentType: 'application/json', success: function(data) { $('#sid').val(data['id']); $('#url').val(data['domain']); $('#scan').text('Stop'); pollScan(); }, error: function(xhr, status, error) { $('#scan').text('Scan'); $('#status').html(xhr.responseJSON['message'] || 'Something went wrong'); }, }); } else { $('#scan').text('⏱'); $.post({ url: '/api/scans/' + $('#sid').val() + '/stop', contentType: 'application/json', }) .always(function() { $('#scan').text('Scan'); }); } }
```

--------------------------------

### Enable Perceptual Hashing for Visual Similarity

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

If Chromium is installed, dnstwist can capture web page screenshots, render them, and calculate pHash values for visual similarity comparison. Ensure sufficient system resources, especially memory, are available due to multi-threaded browser usage.

```bash
$ dnstwist --phash domain.name
```

--------------------------------

### Event Listeners for Scan Actions

Source: https://github.com/elceef/dnstwist/blob/master/webapp/webapp.html

Attaches click event listeners to the 'Scan' button and keypress listener to the URL input field to trigger the scan action. This provides user interaction for starting and stopping scans.

```javascript
$('#scan').click(function() { actionScan(); }); $('#url').on('keypress',function(e) { if(e.which == 13) { actionScan(); } });
```

--------------------------------

### dnstwist.run() - Basic Usage

Source: https://github.com/elceef/dnstwist/blob/master/README.md

This snippet demonstrates the basic usage of the `dnstwist.run()` function to generate domain permutations and retrieve data. The `registered=True` argument filters for registered domains, and `format='null'` is used here for demonstration, though other formats like 'list' or 'json' are available.

```APIDOC
## dnstwist.run()

### Description
Executes the dnstwist domain permutation and analysis.

### Method
```python
import dnstwist
data = dnstwist.run(domain='domain.name', registered=True, format='null')
```

### Parameters
- **domain** (string) - Required - The input domain name to generate permutations from.
- **registered** (boolean) - Optional - If True, only returns registered domains.
- **format** (string) - Optional - The output format. Examples include 'null', 'list', 'json'.

### Request Example
```python
>>> import dnstwist
>>> data = dnstwist.run(domain='domain.name', registered=True, format='null')
```

### Response
- **data** (list of dictionaries) - A list containing dictionaries, where each dictionary represents a domain permutation with its associated data.
```

--------------------------------

### Configure Web Application Settings

Source: https://context7.com/elceef/dnstwist/llms.txt

Set environment variables for the web application, including port, threads, nameservers, and session management.

```bash
# Web application specific
export PORT=8080
export HOST=0.0.0.0
export THREADS=32
export NAMESERVERS=1.1.1.1,8.8.8.8
export SESSION_TTL=3600     # session lifetime in seconds
export SESSION_MAX=10       # max concurrent scan sessions
export DOMAIN_MAXLEN=15     # max input domain label length
```

--------------------------------

### Run DNSTwist with a Dictionary File

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Provide a dictionary file to generate additional domain permutations based on common words used in phishing campaigns. Ensure the dictionary file path is correct.

```bash
dnstwist --dictionary dictionaries/english.dict domain.name
```

--------------------------------

### `dnstwist.run()` — programmatic scan

Source: https://context7.com/elceef/dnstwist/llms.txt

The `run()` function accepts the same arguments as the CLI, translated to Python keyword arguments. It returns a list of dicts, each representing a domain permutation with its resolved DNS data.

```APIDOC
## `dnstwist.run()` — programmatic scan

The `run()` function accepts the same arguments as the CLI, translated to Python keyword arguments. It returns a list of dicts, each representing a domain permutation with its resolved DNS data.

```python
import dnstwist

# Basic scan - return only registered domains as a list of dicts
results = dnstwist.run(domain='example.com', registered=True, format='null')

for entry in results:
    print(entry['fuzzer'], entry['domain'], entry.get('dns_a', []))
# homoglyph  examp1e.com  ['185.53.178.5']
# addition   example0.com ['93.184.216.34']

# JSON output format - useful for serialization
import json
results = dnstwist.run(domain='example.com', format='json')
# results is None when format is not 'null'; use format='null' for list return

# Passive mode - generate permutations only, no DNS lookups
permutations = dnstwist.run(domain='example.com', format='list', output=dnstwist.devnull)
# Returns list of dicts: [{'fuzzer': 'addition', 'domain': 'example0.com'}, ...]

# Scan with LSH phishing detection, geoip, and extra threads
results = dnstwist.run(
    domain='example.com',
    registered=True,
    lsh='ssdeep',
    geoip=True,
    threads=32,
    format='null'
)
for r in results:
    if r.get('ssdeep', 0) > 50:
        print(f"PHISHING ALERT: {r['domain']} - HTML similarity {r['ssdeep']}% ")
# PHISHING ALERT: examp1e.com - HTML similarity 87%

# Export results to JSON file
dnstwist.run(domain='example.com', format='json', output='results.json')
```
```

--------------------------------

### Running DNSTwist Programmatically

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

This snippet shows how to use the `dnstwist.run()` function to generate domain permutations and retrieve data. The arguments mirror the command-line options.

```APIDOC
## Running DNSTwist Programmatically

### Description
This function allows you to programmatically generate domain permutations and retrieve the results as a list of dictionaries. It accepts arguments similar to the command-line interface.

### Method
`dnstwist.run()`

### Parameters
- **domain** (string) - Required - The input domain name to generate permutations for.
- **registered** (boolean) - Optional - If True, only returns registered domains.
- **format** (string) - Optional - The output format. Use 'null' to get a structured list of dictionaries.

### Request Example
```python
import dnstwist
data = dnstwist.run(domain='domain.name', registered=True, format='null')
```

### Response
- **data** (list of dictionaries) - A list where each dictionary contains information about a generated domain permutation.
```

--------------------------------

### DNS Scanning with Scanner Class

Source: https://context7.com/elceef/dnstwist/llms.txt

Use the `Scanner` class to process a queue of domain permutations, enriching them with DNS records, GeoIP information, banners, and scores. Ensure necessary modules like `dnspython` and `geoip` are available if options are enabled.

```python
import queue
import threading
import dnstwist

# Set up fuzzer
fuzz = dnstwist.Fuzzer('example.com')
fuzz.generate()

# Load jobs into queue
jobs = queue.Queue()
for domain in fuzz.domains:
    jobs.put(domain)

# Configure and start scanner threads
threads = []
for _ in range(16):
    worker = dnstwist.Scanner(jobs)
    worker.url = dnstwist.UrlParser('example.com')
    worker.option_extdns = dnstwist.MODULE_DNSPYTHON  # use dnspython if available
    worker.option_geoip = dnstwist.MODULE_GEOIP        # enable GeoIP if available
    worker.option_banners = True                        # grab HTTP/SMTP banners
    worker.option_mxcheck = True                        # detect rogue MX hosts
    worker.useragent = dnstwist.USER_AGENT_STRING
    worker.start()
    threads.append(worker)

jobs.join()
for w in threads:
    w.stop()
for w in threads:
    w.join()

# Retrieve results
for p in fuzz.permutations(registered=True):
    print(p)
# {'fuzzer': 'homoglyph', 'domain': 'examp1e.com', 'dns_a': ['185.53.178.5'],
#  'dns_mx': ['mail.examp1e.com'], 'geoip': 'United States',
#  'banner_http': 'nginx/1.18.0', 'mx_spy': True}
```

--------------------------------

### Run DNSTwist with Custom TLDs

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Use a dictionary file containing a list of Top-Level Domains (TLDs) to check for the existence of domains with specific TLDs.

```bash
dnstwist --tld dictionaries/common_tlds.dict domain.name
```

--------------------------------

### Download Plain Domain List

Source: https://context7.com/elceef/dnstwist/llms.txt

Download a plain list of discovered domains. Requires a scan ID.

```bash
curl -s http://127.0.0.1:8000/api/scans/$SID/list
```

--------------------------------

### Querying WHOIS Data with Whois Class

Source: https://context7.com/elceef/dnstwist/llms.txt

Use the `Whois` class to perform WHOIS lookups for domain registrar and creation date information. The `creation_date` can be used for recency checks to identify potentially malicious domains.

```python
from dnstwist import Whois, domain_tld

whois = Whois()

# Full WHOIS query for a domain
result = whois.whois('examp1e.com')
print(result)
# {
#   'text': '...raw whois response...',
#   'registrar': 'GoDaddy.com, LLC',
#   'creation_date': datetime.datetime(2021, 6, 15, 0, 0)
# }

# Use creation_date for recency checks
if result['creation_date']:
    from datetime import datetime, timedelta
    age = datetime.now() - result['creation_date']
    if age < timedelta(days=90):
        print(f"WARNING: Domain registered only {age.days} days ago - likely malicious")
# WARNING: Domain registered only 47 days ago - likely malicious

# Query against a specific WHOIS server
result = whois.whois('examp1e.de', server='whois.denic.de')
```

--------------------------------

### Run DNSTwist with Custom Nameservers

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Specify external DNS or DNS-over-HTTPS servers to use for lookups. This is recommended if your local DNS server cannot handle a high volume of requests.

```bash
dnstwist --nameservers <dns_server_ip> domain.name
```

--------------------------------

### Generate Permutations Only (No DNS Lookups)

Source: https://context7.com/elceef/dnstwist/llms.txt

Create a list of all domain variants without performing any DNS lookups. This is useful for generating a comprehensive list of potential typosquatting domains.

```bash
$ dnstwist --format list example.com
# exmaple.com
# exapmle.com
# examlpe.com
# example0.com
# ...
```

--------------------------------

### Configure HTTP/HTTPS Proxy

Source: https://context7.com/elceef/dnstwist/llms.txt

Set environment variables for proxy configuration. Lower-case variables are preferred.

```bash
# Proxy (standard environment variables, lower-case preferred)
export https_proxy=http://proxy.corp:8080
export http_proxy=http://proxy.corp:8080
```

--------------------------------

### Generate Domain Permutations with Fuzzer Class

Source: https://context7.com/elceef/dnstwist/llms.txt

The `Fuzzer` class handles domain permutation logic. Instantiate it with a domain, optionally provide word/TLD dictionaries, call `generate()`, and access results via `permutations()`.

```python
from dnstwist import Fuzzer

# Basic permutation generation
with Fuzzer('example.com') as fuzz:
    fuzz.generate()
    all_perms = fuzz.permutations()
    print(f"Total permutations: {len(all_perms)}")
    # Total permutations: 1842
```

```python
# With dictionary and TLD files
with open('dictionaries/english.dict') as f:
    words = f.read().splitlines()
with open('dictionaries/common_tlds.dict') as f:
    tlds = f.read().splitlines()

with Fuzzer('example.com', dictionary=words, tld_dictionary=tlds) as fuzz:
    fuzz.generate()
    # Select specific fuzzers only
    fuzz.generate(fuzzers=['homoglyph', 'hyphenation', 'tld-swap'])
    for p in fuzz.permutations():
        print(p['fuzzer'], p['domain'])
    # homoglyph   exаmple.com
    # hyphenation ex-ample.com
    # tld-swap    example.net
```

```python
# After scanning, filter registered domains
registered = fuzz.permutations(registered=True)
unregistered = fuzz.permutations(unregistered=True)
# With full DNS records
all_dns = fuzz.permutations(dns_all=True)
# With Unicode display (decoded from punycode)
unicode_display = fuzz.permutations(unicode=True)
```

--------------------------------

### Select Specific Fuzzing Algorithms

Source: https://context7.com/elceef/dnstwist/llms.txt

Run only a specified subset of fuzzing algorithms instead of the full default set. This allows for targeted analysis using specific permutation methods.

```bash
$ dnstwist --fuzzers "homoglyph,hyphenation" example.com
# homoglyph    exаmple.com    (Cyrillic 'а')
# hyphenation  ex-ample.com
# hyphenation  exa-mple.com
```

--------------------------------

### TLD Swap for Alternative Top-Level Domains

Source: https://context7.com/elceef/dnstwist/llms.txt

Check for the existence of a domain under various common alternative top-level domains (TLDs) using a provided dictionary file.

```bash
$ dnstwist --tld dictionaries/common_tlds.dict example.com
# tld-swap    example.net    93.184.216.34
# tld-swap    example.org    93.184.216.34
# tld-swap    example.xyz    104.21.44.130
```

--------------------------------

### Passive Mode with List Format

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Demonstrates how to use DNSTwist in a passive mode to only generate domain permutations and redirect output to null.

```APIDOC
## Passive Mode with List Format

### Description
This example shows how to configure `dnstwist.run()` to operate in a passive mode, producing only a list of domain permutations and redirecting the output to `dnstwist.devnull`.

### Method
`dnstwist.run()`

### Parameters
- **domain** (string) - Required - The input domain name.
- **format** (string) - Required - Set to 'list' to get only domain permutations.
- **output** (file-like object) - Required - Set to `dnstwist.devnull` to discard output.

### Request Example
```python
dnstwist.run(domain='domain.name', format='list', output=dnstwist.devnull)
```

### Response
This operation does not return data directly but performs an action (generating permutations and discarding output).
```

--------------------------------

### Build Local Docker Images

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Build custom Docker images for DNSTwist locally. The second command builds an image with phash support enabled.

```bash
docker build -t dnstwist .
docker build -t dnstwist:phash --build-arg phash=1 .
```

--------------------------------

### Download Results as CSV

Source: https://context7.com/elceef/dnstwist/llms.txt

Download scan results in CSV format. Requires a scan ID.

```bash
curl -s http://127.0.0.1:8000/api/scans/$SID/csv -o results.csv
```

--------------------------------

### Visual Similarity with Perceptual Hash (pHash)

Source: https://context7.com/elceef/dnstwist/llms.txt

Use a headless Chromium browser to take screenshots of each resolved domain and compare them visually to the original using perceptual hashing. This helps detect visual phishing attempts.

```bash
$ dnstwist --phash example.com
# homoglyph    examp1e.com    185.53.178.5    PHASH:91%
```

```bash
# Save screenshots as PNG files for manual review
$ dnstwist --phash --screenshots /tmp/screenshots/ example.com
# Saves files like: /tmp/screenshots/0000a3f1_examp1e.com.png
```

--------------------------------

### Visual similarity with perceptual hash (pHash)

Source: https://context7.com/elceef/dnstwist/llms.txt

Use a headless Chromium browser to take screenshots of each resolved domain and compare them visually to the original using perceptual hashing.

```APIDOC
## Visual similarity with perceptual hash (pHash)

Use a headless Chromium browser to take screenshots of each resolved domain and compare them visually to the original using perceptual hashing.

```bash
$ dnstwist --phash example.com
# homoglyph    examp1e.com    185.53.178.5    PHASH:91%

# Save screenshots as PNG files for manual review
$ dnstwist --phash --screenshots /tmp/screenshots/ example.com
# Saves files like: /tmp/screenshots/0000a3f1_examp1e.com.png
```
```

--------------------------------

### Download Plain Domain List

Source: https://context7.com/elceef/dnstwist/llms.txt

Download a plain list of discovered domains from a scan session.

```APIDOC
## GET /api/scans/<id>/list — download plain domain list

### Description
Download a plain list of discovered domains from a scan session.

### Method
GET

### Endpoint
/api/scans/<id>/list

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the scan session.

### Response
#### Success Response (200)
- The response body will contain a plain text list of discovered domains, one per line.
```

--------------------------------

### Extend Permutations with a Dictionary File

Source: https://context7.com/elceef/dnstwist/llms.txt

Use a custom dictionary file to generate additional domain permutations. This extends the default fuzzing algorithms with words from the specified dictionary.

```bash
$ dnstwist --dictionary dictionaries/english.dict example.com
# Adds variants like: login-example.com, example-secure.com, myexample.com, ...
```

--------------------------------

### WHOIS Registration Date Lookup

Source: https://context7.com/elceef/dnstwist/llms.txt

Query WHOIS databases to retrieve the registrar and creation date for registered domain permutations. This provides historical registration information.

```bash
$ dnstwist --whois --registered example.com
# addition    example1.com    93.184.216.34    REGISTRAR:MarkMonitor    CREATED:2018-03-01
```

--------------------------------

### Proxy support

Source: https://context7.com/elceef/dnstwist/llms.txt

HTTP connections automatically use proxy settings from environment variables.

```APIDOC
## Proxy support

HTTP connections automatically use proxy settings from environment variables.

```bash
$ https_proxy=http://proxy.corp:8080 dnstwist --lsh example.com
# using proxy: http://proxy.corp:8080
```
```

--------------------------------

### Download Results as JSON

Source: https://context7.com/elceef/dnstwist/llms.txt

Download scan results in JSON format. Requires a scan ID.

```bash
curl -s http://127.0.0.1:8000/api/scans/$SID/json -o results.json
```

--------------------------------

### Run DNSTwist for Registered Domains

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Execute DNSTwist to generate domain permutations and filter for only those that are currently registered. Useful for reducing output when dealing with many permutations.

```bash
dnstwist --registered domain.name
```

--------------------------------

### Configure DNS Resolution Timeouts and Retries

Source: https://context7.com/elceef/dnstwist/llms.txt

Set environment variables to control DNS query timeouts and retry counts.

```bash
# DNS resolution timeouts and retries
export REQUEST_TIMEOUT_DNS=2.5      # seconds per DNS query
export REQUEST_RETRIES_DNS=2        # retry count
export REQUEST_TIMEOUT_HTTP=5       # seconds per HTTP fetch
export REQUEST_TIMEOUT_SMTP=5       # seconds per SMTP probe
export WEBDRIVER_PAGELOAD_TIMEOUT=12.0  # headless browser page load timeout
```

--------------------------------

### Perceptual Hashing with PHash

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Utilizes Chromium's headless mode to capture screenshots and calculate perceptual hashes (pHash) for visual similarity comparison.

```APIDOC
## Perceptual Hashing with PHash

### Description
If Chromium is installed, this feature captures web page screenshots, renders them, and calculates pHash values to evaluate visual similarity, expressed as a percentage.

### Method
Command-line invocation with `--phash` flag.

### Parameters
- **`--phash`**: Enables perceptual hashing.
- **`--screenshots`**: (Optional) Specifies a directory to save captured screenshots in PNG format.

### Usage Example
```bash
$ dnstwist --phash domain.name
$ dnstwist --phash --screenshots /tmp/domain domain.name
```
```

--------------------------------

### Splitting Domain into Components with domain_tld()

Source: https://context7.com/elceef/dnstwist/llms.txt

The `domain_tld()` function parses a fully qualified domain name into its subdomain, second-level domain, and top-level domain (TLD) components. It handles multi-part TLDs correctly.

```python
from dnstwist import domain_tld

sub, domain, tld = domain_tld('mail.example.co.uk')
print(sub)     # mail
print(domain)  # example
print(tld)     # co.uk

sub, domain, tld = domain_tld('example.com')
print(sub)     # (empty string)
print(domain)  # example
print(tld)     # com
```

--------------------------------

### Run DNSTwist with GeoIP Lookup

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Perform real-time GeoIP lookups to determine the approximate country location of IPv4 addresses associated with the generated domain permutations. Ensure the GeoLite2 database is accessible.

```bash
dnstwist --geoip domain.name
```

--------------------------------

### Save Screenshots with Perceptual Hashing

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

It is possible to save captured screenshots in PNG format to a specified location when using the --phash option.

```bash
$ dnstwist --phash --screenshots /tmp/domain domain.name
```

--------------------------------

### Enable TLSH Algorithm for Fuzzy Hashing

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

By default, ssdeep is used as the LSH algorithm. TLSH is also available and can be enabled using the 'tlsh' argument.

```bash
$ dnstwist --lsh tlsh domain.name
```

--------------------------------

### dnstwist.run() - Passive Mode

Source: https://github.com/elceef/dnstwist/blob/master/README.md

This snippet shows how to use `dnstwist.run()` in a passive mode to generate only domain permutations. It combines the `format='list'` with output redirection to `dnstwist.devnull` to achieve this.

```APIDOC
## dnstwist.run() - Passive Mode

### Description
Generates only domain permutations in a passive operating mode.

### Method
```python
data = dnstwist.run(domain='domain.name', format='list', output=dnstwist.devnull)
```

### Parameters
- **domain** (string) - Required - The input domain name.
- **format** (string) - Required - Set to 'list' for permutation-only output.
- **output** (file-like object) - Required - Set to `dnstwist.devnull` for passive mode.

### Request Example
```python
>>> dnstwist.run(domain='domain.name', format='list', output=dnstwist.devnull)
```

### Response
- **data** (list) - A list of generated domain permutations.
```

--------------------------------

### Specify URL for Fuzzy Hashing

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

When phishing sites are served from a specific URL, provide a full or partial URL as an argument. Use --lsh-url to override the URL from which the original web page is fetched.

```bash
$ dnstwist --lsh https://domain.name/owa/
```

```bash
$ dnstwist --lsh --lsh-url https://different.domain/owa/ domain.name
```

--------------------------------

### Export DNSTwist Results to CSV

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Export the generated domain permutations and their DNS records to CSV format. The output is piped to 'column' for better terminal readability.

```bash
dnstwist --format csv domain.name | column -t -s,
```

--------------------------------

### `Fuzzer` class — generate domain permutations

Source: https://context7.com/elceef/dnstwist/llms.txt

The `Fuzzer` class handles all permutation logic. Instantiate it with a domain and optional word/TLD dictionaries, call `generate()`, then access the results via `permutations()`.

```APIDOC
## `Fuzzer` class — generate domain permutations

The `Fuzzer` class handles all permutation logic. Instantiate it with a domain and optional word/TLD dictionaries, call `generate()`, then access the results via `permutations()`.

```python
from dnstwist import Fuzzer

# Basic permutation generation
with Fuzzer('example.com') as fuzz:
    fuzz.generate()
    all_perms = fuzz.permutations()
    print(f"Total permutations: {len(all_perms)}")
    # Total permutations: 1842

# With dictionary and TLD files
with open('dictionaries/english.dict') as f:
    words = f.read().splitlines()
with open('dictionaries/common_tlds.dict') as f:
    tlds = f.read().splitlines()

with Fuzzer('example.com', dictionary=words, tld_dictionary=tlds) as fuzz:
    fuzz.generate()
    # Select specific fuzzers only
    fuzz.generate(fuzzers=['homoglyph', 'hyphenation', 'tld-swap'])
    for p in fuzz.permutations():
        print(p['fuzzer'], p['domain'])
    # homoglyph   exаmple.com
    # hyphenation ex-ample.com
    # tld-swap    example.net

# After scanning, filter registered domains
registered = fuzz.permutations(registered=True)
unregistered = fuzz.permutations(unregistered=True)
# With full DNS records
all_dns = fuzz.permutations(dns_all=True)
# With Unicode display (decoded from punycode)
unicode_display = fuzz.permutations(unicode=True)
```
```

--------------------------------

### Retrieve Discovered Domains

Source: https://context7.com/elceef/dnstwist/llms.txt

Fetch the list of registered permutations found so far. Requires a scan ID.

```bash
curl -s http://127.0.0.1:8000/api/scans/$SID/domains | jq '.[] | {fuzzer, domain, dns_a}'
```

--------------------------------

### Export DNSTwist Results to JSON

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Export the generated domain permutations and their DNS records to JSON format. The output is piped to 'jq' for pretty-printing and manipulation.

```bash
dnstwist --format json domain.name | jq
```

--------------------------------

### Basic Domain Scan for Registered Permutations

Source: https://context7.com/elceef/dnstwist/llms.txt

Perform a basic scan to find all domain permutations and filter for only those that have active DNS records. The output is colorized in the terminal.

```bash
$ dnstwist --registered example.com
# Output (colorized in terminal):
# addition     example0.com      93.184.216.34
# homoglyph    examp1e.com       185.53.178.5
# transposition exmaple.com      52.20.1.100
# ...
```

--------------------------------

### Proxy Support for HTTP Connections

Source: https://context7.com/elceef/dnstwist/llms.txt

HTTP connections automatically use proxy settings from environment variables. Ensure the `https_proxy` environment variable is set to your proxy server address.

```bash
$ https_proxy=http://proxy.corp:8080 dnstwist --lsh example.com
# using proxy: http://proxy.corp:8080
```

--------------------------------

### Enable Fuzzy Hashing for HTML Similarity

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Use the --lsh argument to enable fuzzy hashing. This fetches and compares normalized HTML content for similarity. It's recommended to use this for detecting similar HTML source code.

```bash
$ dnstwist --lsh domain.name
```

--------------------------------

### Initialize Scan on Page Load

Source: https://github.com/elceef/dnstwist/blob/master/webapp/webapp.html

Checks for a scan ID in the URL hash on page load and fetches domains if found. This allows resuming a previous scan.

```javascript
window.onload = function() { if (window.location.hash) { $('#sid').val(window.location.hash.substring(1)); fetchDomains(); } }
```

--------------------------------

### Configure GeoIP Database Location

Source: https://context7.com/elceef/dnstwist/llms.txt

Set the environment variable for the GeoLite2 MMDB file path.

```bash
# GeoIP database location
export GEOLITE2_MMDB=/path/to/GeoLite2-Country.mmdb
```

--------------------------------

### Python API for dnstwist - Basic Usage

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

To consume dnstwist data within your code, use the dnstwist.run() function. The arguments are translated internally from command-line usage. The returned data is a list of dictionaries.

```python
>>> import dnstwist
>>> data = dnstwist.run(domain='domain.name', registered=True, format='null')
```

--------------------------------

### HTML Similarity with ssdeep (LSH)

Source: https://context7.com/elceef/dnstwist/llms.txt

Fetch content from each registered permutation's web server and compute fuzzy hash similarity against the original page using the ssdeep algorithm. A high percentage indicates likely phishing content.

```bash
$ dnstwist --lsh example.com
# homoglyph    examp1e.com    185.53.178.5    SSDEEP:87%
```

```bash
# Use TLSH algorithm instead
$ dnstwist --lsh tlsh example.com
# homoglyph    examp1e.com    185.53.178.5    TLSH:92%
```

```bash
# Compare against a specific URL path (e.g., OWA login page)
$ dnstwist --lsh https://example.com/owa/auth/logon.aspx
# Fetches original from /owa/auth/logon.aspx and compares all permutations at the same path
```

```bash
# Override the source URL while scanning a different domain
$ dnstwist --lsh --lsh-url https://mail.example.com/owa/ example.com
```

--------------------------------

### Fuzzy Hashing with LSH

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Enables fuzzy hashing to detect similar HTML source code among generated domains using the `--lsh` argument.

```APIDOC
## Fuzzy Hashing with LSH

### Description
This feature enables the detection of similar HTML source code across generated domains. It fetches HTTP content, normalizes HTML, and compares fuzzy hashes. The similarity is expressed as a percentage.

### Method
Command-line invocation with `--lsh` flag.

### Parameters
- **`--lsh`**: Enables fuzzy hashing.
- **`--lsh-url`**: (Optional) Specifies a URL to fetch the original web page from.
- **`tlsh`**: (Optional) Use TLSH as the LSH algorithm instead of the default ssdeep.

### Usage Example
```bash
$ dnstwist --lsh domain.name
$ dnstwist --lsh https://domain.name/owa/
$ dnstwist --lsh --lsh-url https://different.domain/owa/ domain.name
$ dnstwist --lsh tlsh domain.name
```
```

--------------------------------

### Save output to a file

Source: https://context7.com/elceef/dnstwist/llms.txt

Redirect results to a file rather than stdout.

```APIDOC
## Save output to a file

Redirect results to a file rather than stdout.

```bash
$ dnstwist --format json --output results.json example.com
```
```

--------------------------------

### HTML similarity with ssdeep (LSH)

Source: https://context7.com/elceef/dnstwist/llms.txt

Fetch content from each registered permutation's web server and compute fuzzy hash similarity against the original page. A high percentage indicates likely phishing content.

```APIDOC
## HTML similarity with ssdeep (LSH)

Fetch content from each registered permutation's web server and compute fuzzy hash similarity against the original page. A high percentage indicates likely phishing content.

```bash
$ dnstwist --lsh example.com
# homoglyph    examp1e.com    185.53.178.5    SSDEEP:87%

# Use TLSH algorithm instead
$ dnstwist --lsh tlsh example.com
# homoglyph    examp1e.com    185.53.178.5    TLSH:92%

# Compare against a specific URL path (e.g., OWA login page)
$ dnstwist --lsh https://example.com/owa/auth/logon.aspx
# Fetches original from /owa/auth/logon.aspx and compares all permutations at the same path

# Override the source URL while scanning a different domain
$ dnstwist --lsh --lsh-url https://mail.example.com/owa/ example.com
```
```

--------------------------------

### Use Custom DNS or DNS-over-HTTPS Nameservers

Source: https://context7.com/elceef/dnstwist/llms.txt

Specify custom DNS resolvers, including DNS-over-HTTPS (DoH) endpoints, for domain lookups. This allows for using alternative or privacy-focused DNS services.

```bash
# IPv4 nameservers (comma-separated)
$ dnstwist --nameservers 1.1.1.1,8.8.8.8 example.com
```

--------------------------------

### Python API for dnstwist - Passive Mode

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

For completely passive operation producing only domain permutations, combine the list format with output redirection to the null device. Note that dnstwist.run() spawns daemon threads.

```python
>>> dnstwist.run(domain='domain.name', format='list', output=dnstwist.devnull)
```

--------------------------------

### Run DNSTwist with Specific Fuzzing Algorithms

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

Control which fuzzing algorithms are used by providing a comma-separated list to the `--fuzzers` argument. This allows for targeted analysis.

```bash
dnstwist --fuzzers "homoglyph,hyphenation" domain.name
```

--------------------------------

### Proxy Support

Source: https://github.com/elceef/dnstwist/blob/master/docs/README.md

DNSTwist automatically utilizes proxy servers for HTTP connections when specific environment variables are detected.

```APIDOC
## Proxy Support

### Description
For all HTTP connections, proxies are automatically used if environment variables named `$<scheme>_proxy` (case-insensitive) are detected. Lowercase variables are preferred if both cases exist.

### Configuration
Set environment variables such as `http_proxy`, `https_proxy`, etc. For example:

```bash
export http_proxy='http://127.0.0.1:3128'
export https_proxy='http://127.0.0.1:3128'
```
```

--------------------------------

### Enable Debug Output

Source: https://context7.com/elceef/dnstwist/llms.txt

Set the DEBUG environment variable to 1 to enable debug output to stderr.

```bash
# Debug output to stderr
export DEBUG=1
```

--------------------------------

### Save Output to a File

Source: https://context7.com/elceef/dnstwist/llms.txt

Redirect results to a file instead of standard output. This is useful for storing scan results for later analysis or processing.

```bash
$ dnstwist --format json --output results.json example.com
```

--------------------------------

### HTTP and SMTP Banner Grabbing

Source: https://context7.com/elceef/dnstwist/llms.txt

Retrieve server banners from HTTP port 80 and SMTP port 25 on discovered hosts. This helps identify the web server software and mail transfer agent.

```bash
$ dnstwist --banners example.com
# various    examplecom.com    52.20.1.100    HTTP:nginx/1.18.0    SMTP:mail.examplecom.com
```

--------------------------------

### Download Results as CSV

Source: https://context7.com/elceef/dnstwist/llms.txt

Download the results of a scan session in CSV format.

```APIDOC
## GET /api/scans/<id>/csv — download results as CSV

### Description
Download the results of a scan session in CSV format.

### Method
GET

### Endpoint
/api/scans/<id>/csv

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the scan session.

### Response
#### Success Response (200)
- The response body will contain the scan results in CSV format.
```

--------------------------------

### Download Results as JSON

Source: https://context7.com/elceef/dnstwist/llms.txt

Download the results of a scan session in JSON format.

```APIDOC
## GET /api/scans/<id>/json — download results as JSON

### Description
Download the results of a scan session in JSON format.

### Method
GET

### Endpoint
/api/scans/<id>/json

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the scan session.

### Response
#### Success Response (200)
- The response body will contain the scan results in JSON format.
```

--------------------------------

### Export Scan Results to CSV

Source: https://context7.com/elceef/dnstwist/llms.txt

Generate scan results in CSV format and use `column` to format the output into a readable table. This displays fuzzer type, domain, and DNS A/MX records.

```bash
$ dnstwist --format csv example.com | column -t -s,
# fuzzer        domain            dns_a           dns_mx
# addition      example0.com      93.184.216.34   mail.example0.com
# homoglyph     examp1e.com       185.53.178.5
```

--------------------------------

### Retrieve Discovered Domains

Source: https://context7.com/elceef/dnstwist/llms.txt

Fetch the list of registered permutations found so far (or when complete).

```APIDOC
## GET /api/scans/<id>/domains — retrieve discovered domains

### Description
Fetch the list of registered permutations found so far (or when complete).

### Method
GET

### Endpoint
/api/scans/<id>/domains

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the scan session.

### Response
#### Success Response (200)
- **fuzzer** (string) - The type of fuzzing technique used.
- **domain** (string) - The discovered domain name.
- **dns_a** (array of strings) - A list of IP addresses associated with the domain.

### Response Example
```json
[ { "fuzzer": "homoglyph", "domain": "examp1e.com", "dns_a": ["185.53.178.5"] }, { "fuzzer": "addition",  "domain": "example1.com", "dns_a": ["52.20.1.100"] } ]
```
```

--------------------------------

### Format Class

Source: https://context7.com/elceef/dnstwist/llms.txt

The Format class serializes a list of Permutation dictionaries into various output formats, including JSON, CSV, and plain lists.

```APIDOC
## Format Class

### Description
Converts a list of `Permutation` dicts into various output formats like JSON, CSV, and plain lists.

### Usage Example
```python
from dnstwist import Format, Fuzzer

fuzz = Fuzzer('example.com')
fuzz.generate()
# Assume domains have been scanned and enriched by Scanner...
domains = fuzz.permutations(registered=True)

fmt = Format(domains)

# JSON output
print(fmt.json(indent=2))

# CSV output
print(fmt.csv())

# Plain domain list
print(fmt.list())

# Colorized CLI output
print(fmt.cli())
```

### JSON Output Example
```json
[
  {
    "domain": "examp1e.com",
    "dns_a": ["185.53.178.5"],
    "fuzzer": "homoglyph"
  }
]
```

### CSV Output Example
```csv
fuzzer,domain,dns_a,dns_mx
homoglyph,examp1e.com,185.53.178.5,mail.examp1e.com
```

### List Output Example
```
examp1e.com
example0.com
```
```