### Install dirsearch from GitHub

Source: https://github.com/maurosoria/dirsearch/blob/master/README.md

Clone the repository and install dependencies to get started with dirsearch.

```sh
git clone https://github.com/maurosoria/dirsearch.git --depth 1
cd dirsearch
python3 dirsearch.py -u https://example.com -e php,html,js
```

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

### Install Dirsearch from Source using Git and Pip

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Clone the repository and install using pip. Ensure you have Python 3.11 or higher.

```sh
git clone https://github.com/maurosoria/dirsearch.git --depth 1
cd dirsearch
python3 dirsearch.py -u https://example.com -w tests/static/wordlist.txt -q
```

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

### Dirsearch Configuration File Example

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/configuration.md

This is an example of the `config.ini` file used by Dirsearch. It shows various sections and parameters for customizing scan behavior, including general settings, advanced filtering, dictionary options, request configurations, connection details, and output formats. Comments starting with '#' explain each option.

```ini
# If you want to edit dirsearch default configurations, you can
# edit values in this file. Everything after `#` is a comment
# and won't be applied

[general]
threads = 25
async = True
recursive = False
deep-recursive = False
force-recursive = False
recursion-status = 200-399,401,403
max-recursion-depth = 0
exclude-subdirs = %%ff/,.;/,..;/,;/,./,../,%%2e/,%%2e%%2e/
random-user-agents = False
max-time = 0
target-max-time = 0
exit-on-error = False
skip-on-status = 429
#filter-threshold = 10
#subdirs = /,api/
#include-status = 200-299,401
#exclude-status = 400,500-999
#exclude-sizes = 0b,123gb
#exclude-texts = [
#  "Not found",
#  "404"
#]
#exclude-regex = "^403$"
#exclude-redirect = "*/error.html"
#exclude-response = 404.html
# Force extra wildcard calibration from the beginning. dirsearch still performs
# automatic fallback calibration when a target looks ambiguous.
auto-calibration = False

[advanced-filtering]
# Advanced opt-in filters and matchers, inspired by ffuf/wfuzz. These are not
# needed for normal discovery workflows.
matcher-mode = or
filter-mode = or
#match-status = 200-299,401,403
#filter-status = 500-599
#match-size = 100-2000
#filter-size = 0
#match-words = 10-100
#filter-words = 0
#match-lines = 2-50
#filter-lines = 0
#match-regex = "admin"
#filter-regex = "not found"
#match-header = etag: w/
#filter-header = x-cache: fallback
#match-header-regex = "etag: .+"
#filter-header-regex = "x-cache: fallback-[0-9]+"
#match-time = >100
#filter-time = >2000

[dictionary]
default-extensions = php,asp,aspx,jsp,html,htm
force-extensions = False
overwrite-extensions = False
lowercase = False
uppercase = False
capital = False
#exclude-extensions = old,log
#prefixes = .,admin
#suffixes = ~,.bak
#wordlists = /path/to/wordlist1.txt,/path/to/wordlist2.txt
#wordlist-categories = common,conf,web
wordlist-backend = auto
wordlist-max-size = 500000

[request]
http-method = get
request-backend = python
follow-redirects = False
#headers = [
#  "Header1: Value",
#  "Header2: Value"
#]
#headers-file = /path/to/headers.txt
#user-agent = MyUserAgent
#cookie = SESSIONID=123

[connection]
timeout = 7.5
delay = 0
max-rate = 0
max-retries = 1
# By disabling `scheme` variable, dirsearch will automatically identify the URI scheme
#scheme = http
#proxies = ["localhost:8080"]
#proxies-file = /path/to/proxies.txt
#replay-proxy = localhost:8000
#network-interface = eth0

[advanced]
crawl = False

[view]
full-url = False
quiet-mode = False
color = True
show-redirects-history = False
disable-cli = False
verbose = False

[output]
# Available: simple, plain, json, xml, md, csv, html, sqlite
output-formats = plain
# Supported variables for 'output-file' and 'output-sql-table':
# - {extension}: File extension of the report, for 'output-file' only (e.g. txt, json)
# - {format}: Output format (e.g. plain, simple, xml)
# - {host}: Target hostname or IP (e.g. example.com)
# - {scheme}: URI scheme (http or https)
# - {port}: Port number (e.g. 443)
# - {date}: Scan date, format: DD-MM-YYYY (e.g. 07-10-2022)
# - {datetime}: Scan datetime, format: DD-MM-YYYY_HH-MM-SS (e.g. 2025-01-23_14:32:27)
#output-file = reports/{host}/{scheme}_{port}.{extension}
#mysql-url = mysql://user:password@localhost/database
#postgres-url = postgres://user:password@localhost/database
# Table to be used for SQL output (SQLite, MySQL, PostgreSQL)
output-sql-table = {scheme}_{host}:{port}
#log-file = /path/to/dirsearch.log
#log-file-size = 50000000

```

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

### Install Dirsearch with PyPI

Source: https://github.com/maurosoria/dirsearch/wiki/Installation-&-Usage

Install Dirsearch using pip. Ensure you have Python 3.7 or higher.

```bash
pip3 install dirsearch
```

```bash
pip install dirsearch
```

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

### Install Dirsearch from Source with Native Rust

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Clone the repository, set up a virtual environment, install dependencies, build native components, and run Dirsearch using native backends. This method is recommended for development.

```sh
git clone https://github.com/maurosoria/dirsearch.git --depth 1
cd dirsearch
python3.14 -m venv .venv-native
. .venv-native/bin/activate
python -m pip install --upgrade pip
python -m pip install .
python scripts/build_native.py --out dist/native-wheels
python dirsearch.py -u https://example.com -w tests/static/wordlist.txt \
  --request-backend native --wordlist-backend native -q
```

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

### Clone Dirsearch with Git

Source: https://github.com/maurosoria/dirsearch/wiki/Installation-&-Usage

Recommended method for installing Dirsearch. Requires Git to be installed.

```bash
git clone https://github.com/maurosoria/dirsearch.git --depth 1
```

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

### Install Dirsearch using Docker

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Pull the Dirsearch Docker image for easy deployment. This is a convenient way to run Dirsearch without local Python environment setup.

```sh
docker pull ghcr.io/maurosoria/dirsearch:v0.5.0-rc1-async
```

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

### Install Dirsearch (Native Rust) on Ubuntu/Debian

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Installs Dirsearch and builds the native Rust engine. Requires Python 3.14+ and build tools. Creates a wordlist and runs Dirsearch with native backends.

```sh
sudo apt-get update
sudo apt-get install -y \
  git ca-certificates build-essential \
  python3.14 python3.14-venv python3.14-dev \
  cargo rustc

python3.14 -m venv ~/.venvs/dirsearch-native
. ~/.venvs/dirsearch-native/bin/activate
python -m pip install --upgrade pip
python -m pip install "git+https://github.com/maurosoria/dirsearch.git"
dirsearch-build-native

printf 'admin
login
' > /tmp/dirsearch-wordlist.txt
dirsearch -u https://example.com -w /tmp/dirsearch-wordlist.txt \
  --request-backend native --wordlist-backend native -q
```

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

### Validate Packaged Install

Source: https://github.com/maurosoria/dirsearch/blob/master/AGENTS.md

Install the project as a package to validate its installation process and console entrypoints.

```bash
python3 -m pip install .
```

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

### Install Dirsearch (Native Rust) on Windows

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Installs Dirsearch and builds the native Rust engine on Windows using winget and PowerShell. Requires Python 3.14+, Git, and MS C++ Build Tools.

```powershell
winget install --id Python.Python.3.14 -e
winget install --id Rustlang.Rustup -e
py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install "git+https://github.com/maurosoria/dirsearch.git"
dirsearch-build-native
dirsearch --version
```

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

### Install Dirsearch with Optional Database Dependencies

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Install Dirsearch from a Git repository, including optional dependencies for MySQL and PostgreSQL report generation. Use this when database reporting is required.

```sh
python -m pip install "dirsearch[db] @ git+https://github.com/maurosoria/dirsearch.git"
```

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

### Install dirsearch using pip

Source: https://github.com/maurosoria/dirsearch/blob/master/README.md

Install the latest Python stack directly from GitHub using pip for easy access to the dirsearch command.

```sh
pip3 install git+https://github.com/maurosoria/dirsearch.git
dirsearch -u https://example.com -e php,html,js
```

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

### Install Dirsearch (Native Rust) on Red Hat/Fedora

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Installs Dirsearch and builds the native Rust engine. Requires Python 3.14+ and build tools. Creates a wordlist and runs Dirsearch with native backends.

```sh
sudo dnf install -y \
  git ca-certificates gcc gcc-c++ make \
  python3.14 python3.14-devel \
  cargo rust

python3.14 -m venv ~/.venvs/dirsearch-native
. ~/.venvs/dirsearch-native/bin/activate
python -m pip install --upgrade pip
python -m pip install "git+https://github.com/maurosoria/dirsearch.git"
dirsearch-build-native

printf 'admin
login
' > /tmp/dirsearch-wordlist.txt
dirsearch -u https://example.com -w /tmp/dirsearch-wordlist.txt \
  --request-backend native --wordlist-backend native -q
```

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

### Install Dirsearch (Native Rust) on macOS

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Installs Dirsearch and builds the native Rust engine using Homebrew. Requires Python 3.14+ and Rust.

```sh
brew install python git rust
python3.14 -m venv ~/.venvs/dirsearch-native
. ~/.venvs/dirsearch-native/bin/activate
python -m pip install --upgrade pip
python -m pip install "git+https://github.com/maurosoria/dirsearch.git"
dirsearch-build-native
```

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

### Install Dirsearch on Kali Linux

Source: https://github.com/maurosoria/dirsearch/wiki/Installation-&-Usage

Install Dirsearch on Kali Linux using apt-get. This method is deprecated.

```bash
sudo apt-get install dirsearch
```

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

### Build Native Engine from Source

Source: https://github.com/maurosoria/dirsearch/blob/master/native/README.md

Build the native engine from a source checkout using the repository helper script. Installs the built wheel and verifies the import.

```sh
python3.14 scripts/build_native.py --out dist/native-wheels
```

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

### Install Dirsearch (Python-Only) on Ubuntu/Debian

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Installs Dirsearch using pip from GitHub into a Python virtual environment. Requires Python 3.11+.

```sh
sudo apt-get update
sudo apt-get install -y git ca-certificates python3 python3-venv python3-pip
python3 -m venv ~/.venvs/dirsearch
. ~/.venvs/dirsearch/bin/activate
python -m pip install --upgrade pip
python -m pip install "git+https://github.com/maurosoria/dirsearch.git"
dirsearch --version
```

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

### Install Dirsearch (Python-Only) on Red Hat/Fedora

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Installs Dirsearch using pip from GitHub into a Python virtual environment. Requires Python 3.11+.

```sh
sudo dnf install -y git ca-certificates python3 python3-pip
python3 -m venv ~/.venvs/dirsearch
. ~/.venvs/dirsearch/bin/activate
python -m pip install --upgrade pip
python -m pip install "git+https://github.com/maurosoria/dirsearch.git"
dirsearch --version
```

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

### Dirsearch Use Wordlist Categories

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/wordlists.md

Example of how to use bundled wordlist categories, including 'all' to include all available categories.

```sh
python3 dirsearch.py -u https://target --wordlist-categories all
```

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

### Dirsearch Overwrite Extensions Example

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/wordlists.md

Illustrates how to overwrite existing extensions in wordlist entries with new ones.

```text
login.html
```

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

### Build Native Rust Extension Dependencies

Source: https://github.com/maurosoria/dirsearch/blob/master/pyinstaller/README.md

Install Rust and maturin, then build native wheels for the Rust extension. This is required for the native-rust variant.

```bash
rustup default stable

```

```bash
python3.14 -m pip install --only-binary=:all: maturin

```

```bash
python3.14 scripts/build_native.py --out dist/native-wheels

```

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

### Dirsearch Add Custom Prefixes to Wordlist

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/wordlists.md

Example of using the --prefixes flag to prepend custom strings to all wordlist entries.

```sh
python3 dirsearch.py -e php -u https://target --prefixes .,admin,_
```

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

### Dirsearch Force Extensions Example

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/wordlists.md

Shows how to force extensions to be appended to wordlist entries, even if they already have extensions. Appends a '/' to entries without extensions.

```text
admin
```

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

### Build Native Engine

Source: https://github.com/maurosoria/dirsearch/blob/master/native/README.md

Build the native engine from an installed dirsearch package. Requires Python 3.14, Rust/Cargo, Python development headers, and a C compiler.

```sh
dirsearch-build-native
```

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

### Build dirsearch PyInstaller Variants

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/building.md

Use these commands to build the async, threaded, or native-rust variants of dirsearch using PyInstaller for the current platform. Ensure Python 3.14, PyInstaller 6.20.0, and Rust (for native-rust) are installed.

```sh
pyinstaller/build.sh async
pyinstaller/build.sh threaded
pyinstaller/build.sh native-rust
```

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

### Dirsearch Add Custom Suffixes to Wordlist

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/wordlists.md

Example of using the --suffixes flag to append custom strings to all wordlist entries.

```sh
python3 dirsearch.py -e php -u https://target --suffixes ~
```

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

### Use Native Scan Path in Dirsearch

Source: https://github.com/maurosoria/dirsearch/blob/master/native/README.md

Utilize the native scan path in dirsearch for supported GET scans. This command initiates a scan using the native backend.

```sh
python3 dirsearch.py -u https://target -w db/dicc.txt --request-backend native
```

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

### Wordlist Initialization

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Demonstrates how to initialize and use the `Wordlist` class to manage a list of paths, including normalization, comment stripping, and deduplication.

```APIDOC
## Wordlists

Use `Wordlist` when paths are already concrete:

```python
from dirsearch import Wordlist

wordlist = Wordlist([
    "/admin",
    "admin",       # duplicate after normalization
    "# ignored",
    "api/users",
])

assert list(wordlist) == ["admin", "api/users"]
```

`Wordlist` strips leading slashes, ignores empty lines and comments, and
deduplicates while preserving first-seen order.

Load a file when an agent has already built a target-specific list:

```python
wordlist = Wordlist.from_file("tmp/target-paths.txt")
```

To resume or shard a generated wordlist, persist the tuple and index:

```python
state = wordlist.state(index=500)
remaining = Wordlist(state.items[state.index:])
```
```

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

### Load Wordlist from File

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Create a Wordlist instance by loading paths from a specified text file.

```python
wordlist = Wordlist.from_file("tmp/target-paths.txt")
```

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

### FuzzerConfig Initialization

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Demonstrates how to initialize FuzzerConfig with various request parameters for a library scan.

```APIDOC
## FuzzerConfig Initialization

### Description
Initializes the `FuzzerConfig` object to define the behavior of a library scan, including URL, wordlist, headers, user agent, HTTP method, timeout, redirection, TLS verification, and status code filtering.

### Method
```python
FuzzerConfig(
    url: str,
    wordlist: list[str],
    headers: dict[str, str] = None,
    user_agent: str = None,
    http_method: str = "GET",
    timeout: float = 10.0,
    follow_redirects: bool = True,
    verify_tls: bool = True,
    include_status_codes: set[int] = None,
    exclude_status_codes: set[int] = None,
    session_factory: callable = None
)
```

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from dirsearch import FuzzerConfig

wordlist = ["admin", "api/users"]
config = FuzzerConfig(
    url="https://example.com",
    wordlist=wordlist,
    headers={"x-scope": "authorized-test"},
    user_agent="dirsearch-agent/1.0",
    http_method="GET",
    timeout=5.0,
    follow_redirects=False,
    verify_tls=False,
    include_status_codes={200, 204, 301, 302, 401, 403},
    exclude_status_codes={404},
)
```

### Response
None

### Error Handling
None
```

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

### Build Standalone Binary with PyInstaller

Source: https://github.com/maurosoria/dirsearch/blob/master/AGENTS.md

Build the standalone binary executable for Dirsearch using PyInstaller and the provided spec file. The --clean flag ensures a fresh build.

```bash
pyinstaller --clean pyinstaller/dirsearch.spec
```

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

### Dirsearch Normal Extension Replacement

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/wordlists.md

Demonstrates the default behavior of replacing the %EXT% keyword with provided extensions.

```text
index.%EXT%
```

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

### Create FuzzerConfig from Raw Request File

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Initialize FuzzerConfig using FuzzerConfig.from_raw_request() with a file path for the raw HTTP request. Requires a scheme and wordlist.

```python
config = FuzzerConfig.from_raw_request(
    raw_file="tmp/request.txt",
    scheme="https",
    wordlist=["admin", "login"],
)
```

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

### Use Proxies from File with Dirsearch

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/usage.md

Provide Dirsearch with a file containing a list of proxies to use for scanning.

```sh
python3 dirsearch.py -e php,html,js -u https://target --proxies-file proxyservers.txt
```

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

### Local Build Commands for Dirsearch Executables

Source: https://github.com/maurosoria/dirsearch/blob/master/pyinstaller/README.md

Execute these commands to build dirsearch executables for different configurations (async, threaded, native-rust) or all available options.

```bash
./pyinstaller/build.sh async

```

```bash
./pyinstaller/build.sh threaded

```

```bash
./pyinstaller/build.sh native-rust

```

```bash
./pyinstaller/build.sh all

```

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

### Run Quick Local CLI Smoke Test

Source: https://github.com/maurosoria/dirsearch/blob/master/AGENTS.md

Execute a quick smoke test of the Dirsearch CLI locally. Requires a target URL and a wordlist file.

```bash
python3 dirsearch.py -u https://example.com -w tests/static/wordlist.txt -q
```

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

### Load Custom Template from File

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Loads a custom template definition from a specified file path. Ensure the file exists at the given location.

```python
template = WordlistTemplate.from_file("tmp/acme-api-template.txt")
```

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

### Build Dirsearch with Docker

Source: https://github.com/maurosoria/dirsearch/wiki/Installation-&-Usage

Build a Docker image for Dirsearch. More information is available in the support section.

```bash
docker build -t "dirsearch:v0.4.3" .
```

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

### FuzzerConfig from Raw Request

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Utilizes `FuzzerConfig.from_raw_request()` to initialize configuration from a raw HTTP request string or file.

```APIDOC
## FuzzerConfig from Raw Request

### Description
Initializes `FuzzerConfig` using `from_raw_request` method, which parses an existing raw HTTP request (provided as bytes or string) or from a file. This allows reusing captured requests for scanning.

### Method
```python
FuzzerConfig.from_raw_request(
    raw_request: bytes | str = None,
    raw_file: str = None,
    scheme: str,
    wordlist: list[str],
    include_status_codes: set[int] = None,
    exclude_status_codes: set[int] = None,
    headers: dict[str, str] = None,
    user_agent: str = None,
    timeout: float = 10.0,
    follow_redirects: bool = True,
    verify_tls: bool = True,
    session_factory: callable = None
)
```

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from dirsearch import DirsearchFuzzer, FuzzerConfig

raw_request = (
    b"POST /api/search?debug=true HTTP/1.1\r\n"
    b"Host: example.com\r\n"
    b"Content-Type: application/json\r\n"
    b"\r\n"
    b'{\"q\":\"admin\"}'
)

config = FuzzerConfig.from_raw_request(
    raw_request=raw_request,
    scheme="https",
    wordlist=["users", "orders"],
    include_status_codes={200, 401, 403},
)

results = DirsearchFuzzer(config).run()

# Example using raw_file
config_from_file = FuzzerConfig.from_raw_request(
    raw_file="tmp/request.txt",
    scheme="https",
    wordlist=["admin", "login"],
)
```

### Response
None

### Error Handling
None
```

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

### Build Dirsearch Docker Images Locally

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Builds Dirsearch Docker images locally for async and native Rust stacks.

```bash
docker build --build-arg DIRSEARCH_STACK=async -t dirsearch:v0.5.0-rc1-async .
docker build --build-arg DIRSEARCH_STACK=native-rust -t dirsearch:v0.5.0-rc1-native-rust .
```

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

### Build Docker Release Images

Source: https://github.com/maurosoria/dirsearch/blob/master/AGENTS.md

Build the Docker release images using Docker Compose. Ensure the network mode is set to 'host' to match the GitHub workflow.

```bash
docker compose -f - build dirsearch
```

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

### Dirsearch CLI Usage

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/options.md

Basic usage syntax for the Dirsearch command-line tool, including mandatory and optional arguments.

```text
Usage: dirsearch.py [-u|--url] target [-e|--extensions] extensions [options]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit

  Mandatory:
    -u URL, --url=URL   Target URL(s), can use multiple flags
    -l PATH, --urls-file=PATH
                        URL list file
    --stdin             Read URL(s) from STDIN
    --cidr=CIDR         Target CIDR
    --raw=PATH          Load raw HTTP request from file (use '--scheme' flag
                        to set the scheme)
    --nmap-report=PATH  Load targets from nmap report (Ensure the inclusion of
                        the -sV flag during nmap scan for comprehensive
                        results)
    -s SESSION_FILE, --session=SESSION_FILE
                        Session file
    --session-id=ID     Load session by numeric id (use --list-sessions to see
                        ids)
    --config=PATH       Path to configuration file (Default:
                        'DIRSEARCH_CONFIG' environment variable, otherwise
                        'config.ini')

  Dictionary Settings:
    -w WORDLISTS, --wordlists=WORDLISTS
                        Wordlist files or directories contain wordlists
                        (separated by commas)
    --wordlist-categories=WORDLIST_CATEGORIES
                        Comma-separated wordlist category names (e.g.
                        common,conf,web). Use 'all' to include all bundled
                        categories
    --wordlist-backend=BACKEND
                        Wordlist generation backend: auto, python, native
                        (default: auto)
    --wordlist-status   Show resolved wordlist files and generated entry
                        count, then exit
    --wordlist-max-size=COUNT
                        Maximum generated wordlist entries before aborting
                        (default: 500000)
    -e EXTENSIONS, --extensions=EXTENSIONS
                        Extension list, separated by commas (e.g. php,asp)
    -f, --force-extensions
                        Add extensions to the end of every wordlist entry. By
                        default dirsearch only replaces the %EXT% keyword with
                        extensions
    --overwrite-extensions
                        Overwrite other extensions in the wordlist with your
                        extensions (selected via `-e`)
    --exclude-extensions=EXTENSIONS
                        Exclude extension list, separated by commas (e.g.
                        asp,jsp)
    --prefixes=PREFIXES
                        Add custom prefixes to all wordlist entries (separated
                        by commas)
    --suffixes=SUFFIXES
                        Add custom suffixes to all wordlist entries, ignore
                        directories (separated by commas)
    -U, --uppercase     Uppercase wordlist
    -L, --lowercase     Lowercase wordlist
    -C, --capital       Capital wordlist
```

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

### Import Raw HTTP Request

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/usage.md

Import a raw HTTP request from a file. Use `--scheme` if the URI scheme cannot be inferred.

```http
GET /admin HTTP/1.1
Host: admin.example.com
Cache-Control: max-age=0
Accept: */*
```

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

### Scan with Custom Wordlist

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/usage.md

Use a custom wordlist for directory brute-forcing along with specific file extensions.

```sh
python3 dirsearch.py -e php,html,js -u https://target -w /path/to/wordlist
```

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

### Execute Linux/macOS PyInstaller Binary

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Make the PyInstaller-built binary executable and run it with a target URL. This is for direct execution on Linux and macOS systems.

```sh
chmod +x dirsearch-v0.5.0-rc1-linux-x64-async
./dirsearch-v0.5.0-rc1-linux-x64-async -u https://target
```

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

### Build All dirsearch PyInstaller Variants

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/building.md

This command builds all three default-stack variants (async, threaded, native-rust) for dirsearch using PyInstaller on the current platform. Requires Python 3.14, PyInstaller 6.20.0, and Rust for native-rust builds.

```sh
pyinstaller/build.sh all
```

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

### Create FuzzerConfig from Raw HTTP Request

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Use FuzzerConfig.from_raw_request() to initialize a scan from a pre-existing raw HTTP request. Accepts bytes or str for the raw_request and requires a scheme.

```python
from dirsearch import DirsearchFuzzer, FuzzerConfig

raw_request = (
    b"POST /api/search?debug=true HTTP/1.1\r\n"
    b"Host: example.com\r\n"
    b"Content-Type: application/json\r\n"
    b"\r\n"
    b'{"q":"admin"}'
)

config = FuzzerConfig.from_raw_request(
    raw_request=raw_request,
    scheme="https",
    wordlist=["users", "orders"],
    include_status_codes={200, 401, 403},
)

results = DirsearchFuzzer(config).run()
```

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

### Pull and Run Dirsearch Docker Image

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Pulls the latest async prerelease Docker image and runs it against a target URL with specified extensions.

```bash
docker pull ghcr.io/maurosoria/dirsearch:v0.5.0-rc1-async
docker run -it --rm ghcr.io/maurosoria/dirsearch:v0.5.0-rc1-async -u target -e php,html,js,zip
```

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

### Perform a Minimal Scan

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Execute a basic scan against a target URL using a predefined list of paths. By default, 404 responses are excluded.

```python
from dirsearch import DirsearchFuzzer, FuzzerConfig

config = FuzzerConfig(
    url="https://example.com",
    wordlist=["admin", "login.php", "api/users"],
)

results = DirsearchFuzzer(config).run()

for result in results:
    print(result.status, result.path, result.url, result.length)
```

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

### Enable Recursive Scanning

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/usage.md

Enable recursive brute-force scanning for discovered directories.

```sh
python3 dirsearch.py -e php,html,js -u https://target -r
```

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

### Admin and Auth Wordlist Generation

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Use admin/auth route families with a small target-specific subject list. Includes PHP extensions and is limited to 20,000 entries.

```python
template = WordlistTemplate(
    [
        *WordlistTemplate.from_builtin("admin").lines,
        *WordlistTemplate.from_builtin("auth").lines,
    ],
    placeholders={"SUBJECT": ["users", "billing", "settings"]},
)
wordlist = Wordlist.from_template(template, extensions=("php",), max_entries=20_000)
```

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

### Generate Wordlist from Template

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Creates a wordlist by defining a template with placeholders and their corresponding values. Use this when you need to generate paths based on structured route shapes.

```python
from dirsearch import Wordlist, WordlistTemplate

template = WordlistTemplate(
    [
        "api/%API_VERSION%/%SUBJECT%",
        "%CRUD_OP%_%SUBJECT%.%EXT%",
    ],
    placeholders={
        "SUBJECT": ["users", "orders"],
        "CRUD_OP": ["list", "search"],
    },
)

wordlist = Wordlist.from_template(
    template,
    extensions=("json",),
    max_entries=1000,
)
```

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

### Configure Dirsearch Fuzzer Request

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Instantiate FuzzerConfig with basic request parameters like URL, wordlist, headers, user agent, HTTP method, timeout, and status code inclusions/exclusions.

```python
config = FuzzerConfig(
    url="https://example.com",
    wordlist=wordlist,
    headers={"x-scope": "authorized-test"},
    user_agent="dirsearch-agent/1.0",
    http_method="GET",
    timeout=5.0,
    follow_redirects=False,
    verify_tls=False,
    include_status_codes={200, 204, 301, 302, 401, 403},
    exclude_status_codes={404},
)
```

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

### Execute Windows PyInstaller Binary

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Run the PyInstaller-built executable on Windows with a target URL. This is for direct execution on Windows systems.

```sh
dirsearch-v0.5.0-rc1-windows-x64-async.exe -u https://target
```

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

### FuzzerConfig with Session Factory

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Shows how to provide a custom `requests.Session` using `session_factory` for authenticated scans or custom configurations.

```APIDOC
## FuzzerConfig with Session Factory

### Description
Configures `FuzzerConfig` to use a custom session created by a `session_factory` function. This is useful for setting up authentication, proxies, or other custom `requests.Session` behaviors.

### Method
```python
DirsearchFuzzer(
    FuzzerConfig(
        url: str,
        wordlist: list[str],
        session_factory: callable
    )
).run()
```

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import requests
from dirsearch import DirsearchFuzzer, FuzzerConfig

def session_factory():
    session = requests.Session()
    session.headers.update({"authorization": "Bearer TOKEN"})
    session.proxies.update({"https": "http://127.0.0.1:8080"})
    return session

results = DirsearchFuzzer(
    FuzzerConfig(
        url="https://example.com",
        wordlist=["admin", "api/users"],
        session_factory=session_factory,
        include_status_codes={200, 401, 403},
    )
).run()
```

### Response
None

### Error Handling
None
```

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

### Vue.js Initialization and Configuration

Source: https://github.com/maurosoria/dirsearch/blob/master/lib/report/templates/html_report_template.html

Initializes a Vue.js application for the HTML report. It sets up data properties for search queries, sort columns, and resource data, and defines methods for URL joining, size formatting, and status color coding.

```javascript
window.onload = function () {
  var app = new Vue({
    el: '#app',
    delimiters: ['[[', ']]'],
    data: {
      lengthExcludeSearchQuery: null,
      statusExcludeSearchQuery: null,
      searchQuery: null,
      resources: {{ results | tojson }},
      sortColumn: null,
      columns: [
        {name: 'url', text: 'URL', order: -1},
        {name: 'status', text: 'Status', order: -1},
        {name: 'contentLength', text: 'Content Length', order: -1},
        {name: 'contentType', text: 'Content Type', order: -1},
        {name: 'redirect', text: 'Redirect', order: -1},
      ]
    },
    methods: {
      joinUrl: function(url, redirect){
        return new URL(redirect, url).href;
      },
      getReadableSize: function(bytes){
        if (!bytes) return '0 B'
        const base = 1024
        const units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']
        const i = Math.floor(Math.log(bytes) / Math.log(base))
        return `${Math.round(bytes / Math.pow(base, i))} ${units[i]}`
      },
      getStatusColorClass: function(statusCode){
        if (statusCode <= 199) return "";
        if (statusCode <= 299) return "text-success";
        if (statusCode <= 399) return "text-info";
        if (statusCode <= 499) return "text-warning";
        if (statusCode <= 599) return "text-danger";
      }
    },
    computed: {
      results: function(){
        arr = this.resources
        if(this.searchQuery){
          arr = arr.filter((result)=>{
            return search(this, result)
          });
        }
        if(this.statusExcludeSearchQuery){
          arr = arr.filter((result)=>{
            return statusExcludeSearch(this, result)
          });
        }
        if(this.lengthExcludeSearchQuery){
          arr = arr.filter((result)=>{
            return lengthExcludeSearch(this, result)
          });
        }
        return sort(this, arr);
      }
    }
  });
}
```

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

### Quick Web Wordlist Generation

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Use a compact baseline wordlist combining common and web categories for broad scans. Limited to 100,000 entries.

```python
template = WordlistTemplate(["%CATEGORY:common%", "%CATEGORY:web%"])
wordlist = Wordlist.from_template(template, max_entries=100_000)
```

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

### Listing Available Dirsearch Sessions

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/sessions.md

View all available sessions that can be resumed using the --list-sessions flag. This command displays session paths, target URLs, progress, and other relevant details.

```sh
python3 dirsearch.py --list-sessions
```

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

### Dirsearch Wordlist Transformations (Uppercase)

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/wordlists.md

Demonstrates the uppercase transformation for wordlist entries.

```text
ADMIN
INDEX.HTML
```

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

### Backup and Secret Exposure Wordlist Generation

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Use fixed sensitive extensions for backup, database, logs, keys, and version control systems. Limited to 100,000 entries.

```python
template = WordlistTemplate([
    *WordlistTemplate.from_builtin("backups").lines,
    *WordlistTemplate.from_builtin("db").lines,
    *WordlistTemplate.from_builtin("logs").lines,
    "%CATEGORY:keys%",
    "%CATEGORY:vcs%",
])
wordlist = Wordlist.from_template(template, max_entries=100_000)
```

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

### Scan from Standard Input with Dirsearch

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/usage.md

Pipe a list of URLs from standard input to Dirsearch for scanning.

```sh
cat urls.txt | python3 dirsearch.py --stdin
```

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

### Run Smoke Tests on Dirsearch Docker Image

Source: https://github.com/maurosoria/dirsearch/blob/master/AGENTS.md

Executes basic smoke tests on a built Dirsearch Docker image, including checking version, help output, and performing a minimal scan. Mounts a wordlist file for the scan.

```sh
docker run --rm dirsearch:test-STACK --version
```

```sh
docker run --rm dirsearch:test-STACK --help
```

```sh
docker run --rm \
  -v "$PWD/tests/static/wordlist.txt:/tmp/wordlist.txt:ro" \
  dirsearch:test-STACK \
  -u https://example.com -w /tmp/wordlist.txt -e html -q
```

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

### Dirsearch Wordlist Transformations (Capital)

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/wordlists.md

Demonstrates the capitalization transformation for wordlist entries.

```text
Admin
Index.html
```

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

### Build Dirsearch Docker Image for a Specific Stack

Source: https://github.com/maurosoria/dirsearch/blob/master/AGENTS.md

Builds a Dirsearch Docker image for a specified stack (e.g., threaded, async, native-rust) using docker compose. Ensure host networking is enabled for dependency resolution during the build process.

```sh
docker compose -f - build dirsearch <<'YAML'
services:
  dirsearch:
    image: dirsearch:test-STACK
    build:
      context: .
      dockerfile: Dockerfile
      network: host
      args:
        DIRSEARCH_STACK: STACK
YAML
```

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

### Scan with File Extensions

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/usage.md

Scan for specific file extensions like PHP, HTML, and JavaScript.

```sh
python3 dirsearch.py -e php,html,js -u https://target
```

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

### Create a Wordlist from a List

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Initialize a Wordlist object with a list of paths. The Wordlist normalizes paths by stripping leading slashes, ignores comments and empty lines, and removes duplicates while preserving the order of the first occurrence.

```python
from dirsearch import Wordlist

wordlist = Wordlist([
    "/admin",
    "admin",       # duplicate after normalization
    "# ignored",
    "api/users",
])

assert list(wordlist) == ["admin", "api/users"]
```

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

### Dirsearch Wordlist Transformations (Lowercase)

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/wordlists.md

Demonstrates the lowercase transformation for wordlist entries.

```text
admin
index.html
```

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

### Listing Dirsearch Sessions with Custom Directory

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/sessions.md

Specify a custom directory to search for sessions using the --sessions-dir flag in conjunction with --list-sessions. This allows for flexible management of session storage locations.

```sh
python3 dirsearch.py --list-sessions --sessions-dir /path/to/sessions
```

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

### Command and Date Metadata

Source: https://github.com/maurosoria/dirsearch/blob/master/lib/report/templates/html_report_template.html

Displays the command used to run dirsearch and the date/time the report was generated. These are placeholders that will be filled with actual values during report generation.

```html
**Command:** ``{{ metadata['command'] | e | replace('[', '`[`') }}``  
**Time:**

{{ metadata['date'] | e }}
```

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

### Handle Wordlist Limit Error

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Demonstrates how to handle potential `WordlistLimitError` when generating a large wordlist from a template. This allows for graceful error handling and prompts the agent to refine the template.

```python
try:
    wordlist = Wordlist.from_template(template, max_entries=50_000)
except WordlistLimitError:
    # Ask the agent to narrow subjects, categories, or extensions.
    raise
```

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

### Dirsearch Template Wordlist Placeholders

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/wordlists.md

Lists common placeholders supported in template wordlists for dynamic path generation.

```text
%SUBJECT%
%CRUD_OP%
%AUTH_OP%
%ADMIN_OP%
%ENV%
%DATE%
%API_VERSION%
%CATEGORY:name%
%EXT%
```

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

### Authenticate with Basic Auth using Dirsearch

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/usage.md

Perform authenticated scans using basic authentication. Provide username and password.

```sh
python3 dirsearch.py -u https://target --auth admin:pass --auth-type basic
```

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

### Build dirsearch Portable Variants

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/building.md

Build portable folder archives for dirsearch. Specify the target platform and the desired stack variant (async or native-rust). These builds use CPython from python-build-standalone.

```python
python3 scripts/build_portable.py --target linux-x64 --stack async
python3 scripts/build_portable.py --target linux-x64 --stack native-rust
```

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

### Basic dirsearch scans

Source: https://github.com/maurosoria/dirsearch/blob/master/README.md

Perform basic web path discovery scans with dirsearch. Use the -e flag to specify file extensions and -w for a custom wordlist. The -r flag enables recursive scanning.

```sh
python3 dirsearch.py -u https://target
```

```sh
python3 dirsearch.py -u https://target -e php,html,js
```

```sh
python3 dirsearch.py -u https://target -e php,html,js -w /path/to/wordlist
```

```sh
python3 dirsearch.py -u https://target -r --max-recursion-depth 3
```

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

### Import Dirsearch API Components

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Import necessary classes and exceptions from the dirsearch library for API usage.

```python
from dirsearch import (
    DirsearchFuzzer,
    FuzzerConfig,
    Wordlist,
    WordlistLimitError,
    WordlistTemplate,
)
```

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

### Scan Sub-Directories with Dirsearch

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/usage.md

Scan a list of sub-directories from a given URL. Specify extensions to search for.

```sh
python3 dirsearch.py -e php,html,js -u https://target --subdirs /,admin/,folder/
```

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

### Run Legacy Unit/Integration Tests

Source: https://github.com/maurosoria/dirsearch/blob/master/AGENTS.md

Use the legacy test runner script for executing unit and integration tests. This is the test runner used by CI.

```bash
python3 testing.py
```

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

### Configure Dirsearch with Custom Session Factory

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Provide a custom session_factory to FuzzerConfig for authenticated scans or scans requiring specific proxies. The fuzzer manages the session lifecycle.

```python
import requests
from dirsearch import DirsearchFuzzer, FuzzerConfig

def session_factory():
    session = requests.Session()
    session.headers.update({"authorization": "Bearer TOKEN"})
    session.proxies.update({"https": "http://127.0.0.1:8080"})
    return session

results = DirsearchFuzzer(
    FuzzerConfig(
        url="https://example.com",
        wordlist=["admin", "api/users"],
        session_factory=session_factory,
        include_status_codes={200, 401, 403},
    )
).run()
```

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

### Execute Portable Linux Archive

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/installation.md

Extract the portable archive and run the Dirsearch executable from the extracted directory on Linux. This method bundles CPython and dependencies.

```sh
tar -xzf dirsearch-v0.5.0-rc1-linux-x64-async-portable.tar.gz
./dirsearch-v0.5.0-rc1-linux-x64-async-portable/dirsearch -u https://target
```

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

### Minimal Scan

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/python-api.md

Performs a basic scan using DirsearchFuzzer with a predefined configuration. It returns a list of FuzzerResult objects, excluding 404 responses by default.

```APIDOC
## Minimal Scan

Performs a basic scan using `DirsearchFuzzer` with a predefined configuration. It returns a list of `FuzzerResult` objects, excluding `404` responses by default.

```python
from dirsearch import DirsearchFuzzer, FuzzerConfig

config = FuzzerConfig(
    url="https://example.com",
    wordlist=["admin", "login.php", "api/users"],
)

results = DirsearchFuzzer(config).run()

for result in results:
    print(result.status, result.path, result.url, result.length)
```

Each `FuzzerResult` contains:

- `url`: absolute requested URL.
- `path`: wordlist path used for the request.
- `status`: HTTP status code.
- `length`: response length from `content-length` or body size.
- `content_type`: response MIME type without parameters.
- `redirect`: `location` header, if present.
- `elapsed`: request duration in seconds.
- `headers`: response headers as a mapping.
- `body`: raw response bytes.
```

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

### Generate HTML Report with Dirsearch

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/usage.md

Generate an HTML report of scan results to a specified file. Target a URL and include desired extensions.

```sh
python3 dirsearch.py -e php -u https://target --output-formats html --output-file target.html
```

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

### Dirsearch Preview Wordlist Status

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/wordlists.md

Command to preview resolved wordlist files and the count of generated entries without initiating a scan.

```sh
python3 dirsearch.py -u https://target --wordlist-status
```

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

### Basic Dirsearch Scan

Source: https://github.com/maurosoria/dirsearch/blob/master/docs/usage.md

Perform a simple directory brute-force scan against a target URL.

```sh
python3 dirsearch.py -u https://target
```