dirsearch - Web path discovery
=========



[](https://github.com/maurosoria/dirsearch/releases)
[](https://github.com/sponsors/maurosoria)
[](https://discord.gg/2N22ZdAJRj)
[](https://twitter.com/_dirsearch)
> An advanced web path brute-forcer
**dirsearch** is being actively developed by [@maurosoria](https://twitter.com/_maurosoria) and [@shelld3v](https://twitter.com/shells3c_)
*Reach to our [Discord server](https://discord.gg/2N22ZdAJRj) to communicate with the team at best*
Table of Contents
------------
- [Supported Platforms](#supported-platforms)
- [Installation & Usage](#installation--usage)
- [Standalone Binaries](#standalone-binaries)
- [Wordlists](#wordlists-important)
- [Options](#options)
- [Configuration](#configuration)
- [How to use](#how-to-use)
- [Session Management](#session-management)
- [Support Docker](#support-docker)
- [Building from Source](#building-from-source)
- [CI/CD & GitHub Workflows](#cicd--github-workflows)
- [References](#references)
- [Tips](#tips)
- [Contribution](#contribution)
- [License](#license)
Supported Platforms
------------
dirsearch runs on multiple platforms and can be used either via Python or standalone binaries:
| Platform | Python | Standalone Binary |
|----------|--------|-------------------|
| **Linux** (x86_64) | Python 3.9+ | `dirsearch-linux-amd64` |
| **Windows** (x64) | Python 3.9+ | `dirsearch-windows-x64.exe` |
| **macOS** (Intel) | Python 3.9+ | `dirsearch-macos-intel` |
| **macOS** (Apple Silicon) | Python 3.9+ | `dirsearch-macos-silicon` |
Standalone binaries are self-contained executables that don't require Python installation.
Installation & Usage
------------
**Requirement: python 3.9 or higher**
Choose one of these installation options:
- Install with **git**: `git clone https://github.com/maurosoria/dirsearch.git --depth 1` (**RECOMMENDED**)
- Install with ZIP file: [Download here](https://github.com/maurosoria/dirsearch/archive/master.zip)
- Install with Docker: `docker build -t "dirsearch:v0.4.3" .` (more information can be found [here](https://github.com/maurosoria/dirsearch#support-docker))
- Install with PyPi: `pip3 install dirsearch` or `pip install dirsearch`
- Install with Kali Linux: `sudo apt-get install dirsearch` (deprecated)
Standalone Binaries
------------
Pre-built standalone binaries are available for all major platforms. These don't require Python to be installed.
**Download from [Releases](https://github.com/maurosoria/dirsearch/releases)**
| Platform | Binary Name | Architecture |
|----------|-------------|--------------|
| Linux | `dirsearch-linux-amd64` | x86_64 |
| Windows | `dirsearch-windows-x64.exe` | x64 |
| macOS Intel | `dirsearch-macos-intel` | x86_64 |
| macOS Apple Silicon | `dirsearch-macos-silicon` | ARM64 |
**Usage:**
```sh
# Linux/macOS - make executable first
chmod +x dirsearch-linux-amd64
./dirsearch-linux-amd64 -u https://target
# Windows
dirsearch-windows-x64.exe -u https://target
```
**Note:** Standalone binaries include bundled `db/` wordlists and `config.ini`. Session files are stored in `$HOME/.dirsearch/sessions/` when using bundled builds.
Wordlists (IMPORTANT)
---------------
**Summary:**
- Wordlist is a text file, each line is a path.
- About extensions, unlike other tools, dirsearch only replaces the `%EXT%` keyword with extensions from **-e** flag.
- For wordlists without `%EXT%` (like [SecLists](https://github.com/danielmiessler/SecLists)), **-f | --force-extensions** switch is required to append extensions to every word in wordlist, as well as the `/`.
- To apply your extensions to wordlist entries that have extensions already, use **-O** | **--overwrite-extensions** (Note: some extensions are excluded from being overwritted such as *.log*, *.json*, *.xml*, ... or media extensions like *.jpg*, *.png*)
- To use multiple wordlists, you can separate your wordlists with commas. Example: `wordlist1.txt,wordlist2.txt`.
- Bundled wordlist categories live in `db/categories/` and can be selected with **--wordlist-categories**. Available: `extensions`, `conf`, `vcs`, `backups`, `db`, `logs`, `keys`, `web`, `common` (use `all` to include everything).
----
### Recursion
- Recursive brute-force is brute-forcing continuously the after of found directories. For example, if dirsearch finds `admin/`, it will brute-force `admin/*` (`*` is where it brute forces). To enable this feature, use **-r** (or **--recursive**) flag
```
python3 dirsearch.py -e php,html,js -u https://target -r
```
- You can set the max recursion depth with **--max-recursion-depth**, and status codes to recurse with **--recursion-status**
```
python3 dirsearch.py -e php,html,js -u https://target -r --max-recursion-depth 3 --recursion-status 200-399
```
- There are 2 more options: **--force-recursive** and **--deep-recursive**
- **Force recursive**: Brute force recursively all found paths, not just paths end with `/`
- **Deep recursive**: Recursive brute-force all depths of a path (`a/b/c` => add `a/`, `a/b/`)
- If there are sub-directories that you do not want to brute-force recursively, use `--exclude-subdirs`
```
python3 dirsearch.py -e php,html,js -u https://target -r --exclude-subdirs image/,media/,css/
```
----
### Threads
The thread number (**-t | --threads**) reflects the number of separated brute force processes. And so the bigger the thread number is, the faster dirsearch runs. By default, the number of threads is 25, but you can increase it if you want to speed up the progress.
In spite of that, the speed still depends a lot on the response time of the server. And as a warning, we advise you to keep the threads number not too big because it can cause DoS (Denial of Service).
```
python3 dirsearch.py -e php,htm,js,bak,zip,tgz,txt -u https://target -t 20
```
----
### Asynchronous
You can switch to asynchronous mode by `--async`, let dirsearch use coroutines instead of threads to handle concurrent requests.
In theory, asynchronous mode offers better performance and lower CPU usage since it doesn't require switching between different thread contexts. Additionally, pressing CTRL+C will immediately pause progress without needing to wait for threads to suspend.
----
### Prefixes / Suffixes
- **--prefixes**: Add custom prefixes to all entries
```
python3 dirsearch.py -e php -u https://target --prefixes .,admin,_
```
Wordlist:
```
tools
```
Generated with prefixes:
```
tools
.tools
admintools
_tools
```
- **--suffixes**: Add custom suffixes to all entries
```
python3 dirsearch.py -e php -u https://target --suffixes ~
```
Wordlist:
```
index.php
internal
```
Generated with suffixes:
```
index.php
internal
index.php~
internal~
```
----
### Blacklist
Inside the `db/` folder, there are several "blacklist files". Paths in those files will be filtered from the scan result if they have the same status as mentioned in the filename.
Example: If you add `admin.php` into `db/403_blacklist.txt`, whenever you do a scan that `admin.php` returns 403, it will be filtered from the result.
----
### Filters
Use **-i | --include-status** and **-x | --exclude-status** to select allowed and not allowed response status-codes
For more advanced filters: **--exclude-sizes**, **--exclude-texts**, **--exclude-regexps**, **--exclude-redirects** and **--exclude-response**
```
python3 dirsearch.py -e php,html,js -u https://target --exclude-sizes 1B,243KB
```
```
python3 dirsearch.py -e php,html,js -u https://target --exclude-texts "403 Forbidden"
```
```
python3 dirsearch.py -e php,html,js -u https://target --exclude-regexps "^Error$"
```
```
python3 dirsearch.py -e php,html,js -u https://target --exclude-redirects "https://(.*).okta.com/*"
```
```
python3 dirsearch.py -e php,html,js -u https://target --exclude-response /error.html
```
----
### Raw request
dirsearch allows you to import the raw request from a file. The content would be something looked like this:
```http
GET /admin HTTP/1.1
Host: admin.example.com
Cache-Control: max-age=0
Accept: */*
```
Since there is no way for dirsearch to know what the URI scheme is, you need to set it using the `--scheme` flag. By default, dirsearch automatically detects the scheme.
----
### Wordlist formats
Supported wordlist formats: uppercase, lowercase, capitalization
#### Lowercase:
```
admin
index.html
```
#### Uppercase:
```
ADMIN
INDEX.HTML
```
#### Capital:
```
Admin
Index.html
```
----
### Exclude extensions
Use **-X | --exclude-extensions** with an extension list will remove all paths in the wordlist that contains the given extensions
`python3 dirsearch.py -u https://target -X jsp`
Wordlist:
```
admin.php
test.jsp
```
After:
```
admin.php
```
----
### Scan sub-directories
- From an URL, you can scan a list of sub-directories with **--subdirs**.
```
python3 dirsearch.py -e php,html,js -u https://target --subdirs /,admin/,folder/
```
----
### Proxies
dirsearch supports SOCKS and HTTP proxy, with two options: a proxy server or a list of proxy servers.
```
python3 dirsearch.py -e php,html,js -u https://target --proxy 127.0.0.1:8080
```
```
python3 dirsearch.py -e php,html,js -u https://target --proxy socks5://10.10.0.1:8080
```
```
python3 dirsearch.py -e php,html,js -u https://target --proxylist proxyservers.txt
```
----
### Reports
Supported report formats: **simple**, **plain**, **json**, **xml**, **md**, **csv**, **html**, **sqlite**, **mysql**, **postgresql**
```
python3 dirsearch.py -e php -l URLs.txt --format plain -o report.txt
```
```
python3 dirsearch.py -e php -u https://target --format html -o target.json
```
----
### More example commands
```
cat urls.txt | python3 dirsearch.py --stdin
```
```
python3 dirsearch.py -u https://target --max-time 360
```
```
python3 dirsearch.py -u https://target --auth admin:pass --auth-type basic
```
```
python3 dirsearch.py -u https://target --header-list rate-limit-bypasses.txt
```
**There are more to discover, try yourself!**
{{ metadata['command'] | e | replace('[', '[') }}
{{ metadata['date'] | e }}