Skip to content

Commit 1d459b4

Browse files
maurosoriamaurosoria
authored
Merge pull request #1548 decompress-readme-docs
Move README docs into docs
2 parents d2619a5 + 5e42123 commit 1d459b4

11 files changed

Lines changed: 1033 additions & 932 deletions

File tree

‎README.md‎

Lines changed: 41 additions & 932 deletions
Large diffs are not rendered by default.

‎docs/building.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Building
2+
3+
## Building from Source
4+
5+
You can build standalone executables using PyInstaller. This creates a single binary file that includes all dependencies.
6+
7+
Requirements:
8+
9+
- Python 3.9-3.14
10+
- PyInstaller 6.20.0+
11+
- Dependencies from `requirements.txt` and `requirements/db.txt`
12+
13+
## Quick Build
14+
15+
```sh
16+
pip install -r requirements.txt -r requirements/db.txt
17+
pip install pyinstaller==6.20.0
18+
pyinstaller pyinstaller/dirsearch.spec
19+
./dist/dirsearch --version
20+
```
21+
22+
## Manual Build on Linux or macOS
23+
24+
```sh
25+
pyinstaller \
26+
--onefile \
27+
--name dirsearch \
28+
--paths=. \
29+
--collect-submodules=lib \
30+
--add-data "db:db" \
31+
--add-data "config.ini:." \
32+
--add-data "lib/report:lib/report" \
33+
--hidden-import=requests \
34+
--hidden-import=httpx \
35+
--hidden-import=urllib3 \
36+
--hidden-import=jinja2 \
37+
--hidden-import=colorama \
38+
--strip \
39+
--clean \
40+
dirsearch.py
41+
```
42+
43+
## Manual Build on Windows
44+
45+
```powershell
46+
pyinstaller `
47+
--onefile `
48+
--name dirsearch `
49+
--paths=. `
50+
--collect-submodules=lib `
51+
--add-data "db;db" `
52+
--add-data "config.ini;." `
53+
--add-data "lib/report;lib/report" `
54+
--hidden-import=requests `
55+
--hidden-import=httpx `
56+
--hidden-import=urllib3 `
57+
--hidden-import=jinja2 `
58+
--hidden-import=colorama `
59+
--clean `
60+
dirsearch.py
61+
```
62+
63+
Windows uses `;` instead of `:` as the path separator in `--add-data`.
64+
65+
## Build Output
66+
67+
- Linux/macOS: `dist/dirsearch`
68+
- Windows: `dist/dirsearch.exe`
69+
70+
The binary includes:
71+
72+
- All Python dependencies
73+
- `db/` directory with wordlists and blacklists
74+
- `config.ini` default configuration
75+
- `lib/report/` Jinja2 templates for reports
76+
77+
## GitHub Workflows
78+
79+
dirsearch uses GitHub Actions for continuous integration and automated builds.
80+
81+
| Workflow | Trigger | Description |
82+
|----------|---------|-------------|
83+
| Inspection (CI) | Push, PR | Runs tests, linting, and codespell on Python 3.9/3.11/3.14 across Ubuntu and Windows |
84+
| PyInstaller Linux | Manual, Workflow call | Builds `dirsearch-linux-amd64` binary |
85+
| PyInstaller Windows | Manual, Workflow call | Builds `dirsearch-windows-x64.exe` binary |
86+
| PyInstaller macOS Intel | Manual, Workflow call | Builds `dirsearch-macos-intel` binary |
87+
| PyInstaller macOS Silicon | Manual, Workflow call | Builds `dirsearch-macos-silicon` binary |
88+
| PyInstaller Draft Release | Manual | Builds all platforms and creates a draft GitHub release |
89+
| Docker Image | Push, PR | Builds and tests Docker image |
90+
| CodeQL Analysis | Push, PR, Schedule | Security scanning with GitHub CodeQL |
91+
| Semgrep Analysis | Push, PR | Static analysis with Semgrep |
92+
93+
## Running Workflows Manually
94+
95+
PyInstaller builds can be triggered manually from the GitHub Actions tab:
96+
97+
1. Go to Actions and select a workflow, such as PyInstaller Linux.
98+
2. Click Run workflow.
99+
3. Download artifacts from the completed run.
100+
101+
## Creating a Release
102+
103+
To create a release with all platform binaries:
104+
105+
1. Go to Actions > PyInstaller Draft Release.
106+
2. Click Run workflow.
107+
3. Enter the tag, such as `v5.0.0`.
108+
4. Select the target branch.
109+
5. Optionally mark it as a prerelease.
110+
6. Review and publish the draft release.
111+
112+
## Build Matrix
113+
114+
The CI workflow tests on:
115+
116+
- Python versions: 3.9, 3.11, 3.14
117+
- Operating systems: Ubuntu latest and Windows latest

‎docs/configuration.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Configuration
2+
3+
By default, `config.ini` inside the dirsearch directory is used as the configuration file. You can select another file with `--config` or the `DIRSEARCH_CONFIG` environment variable.
4+
5+
```ini
6+
# If you want to edit dirsearch default configurations, you can
7+
# edit values in this file. Everything after `#` is a comment
8+
# and won't be applied
9+
10+
[general]
11+
threads = 25
12+
async = False
13+
recursive = False
14+
deep-recursive = False
15+
force-recursive = False
16+
recursion-status = 200-399,401,403
17+
max-recursion-depth = 0
18+
exclude-subdirs = %%ff/,.;/,..;/,;/,./,../,%%2e/,%%2e%%2e/
19+
random-user-agents = False
20+
max-time = 0
21+
target-max-time = 0
22+
exit-on-error = False
23+
skip-on-status = 429
24+
#filter-threshold = 10
25+
#subdirs = /,api/
26+
#include-status = 200-299,401
27+
#exclude-status = 400,500-999
28+
#exclude-sizes = 0b,123gb
29+
#exclude-texts = [
30+
# "Not found",
31+
# "404"
32+
#]
33+
#exclude-regex = "^403$"
34+
#exclude-redirect = "*/error.html"
35+
#exclude-response = 404.html
36+
37+
[dictionary]
38+
default-extensions = php,asp,aspx,jsp,html,htm
39+
force-extensions = False
40+
overwrite-extensions = False
41+
lowercase = False
42+
uppercase = False
43+
capital = False
44+
#exclude-extensions = old,log
45+
#prefixes = .,admin
46+
#suffixes = ~,.bak
47+
#wordlists = /path/to/wordlist1.txt,/path/to/wordlist2.txt
48+
#wordlist-categories = common,conf,web
49+
wordlist-backend = auto
50+
wordlist-max-size = 500000
51+
52+
[request]
53+
http-method = get
54+
follow-redirects = False
55+
#headers = [
56+
# "Header1: Value",
57+
# "Header2: Value"
58+
#]
59+
#headers-file = /path/to/headers.txt
60+
#user-agent = MyUserAgent
61+
#cookie = SESSIONID=123
62+
63+
[connection]
64+
timeout = 7.5
65+
delay = 0
66+
max-rate = 0
67+
max-retries = 1
68+
# By disabling `scheme` variable, dirsearch will automatically identify the URI scheme
69+
#scheme = http
70+
#proxies = ["localhost:8080"]
71+
#proxies-file = /path/to/proxies.txt
72+
#replay-proxy = localhost:8000
73+
#network-interface = eth0
74+
75+
[advanced]
76+
crawl = False
77+
78+
[view]
79+
full-url = False
80+
quiet-mode = False
81+
color = True
82+
show-redirects-history = False
83+
disable-cli = False
84+
verbose = False
85+
86+
[output]
87+
# Available: simple, plain, json, xml, md, csv, html, sqlite
88+
output-formats = plain
89+
# Supported variables for 'output-file' and 'output-sql-table':
90+
# - {extension}: File extension of the report, for 'output-file' only (e.g. txt, json)
91+
# - {format}: Output format (e.g. plain, simple, xml)
92+
# - {host}: Target hostname or IP (e.g. example.com)
93+
# - {scheme}: URI scheme (http or https)
94+
# - {port}: Port number (e.g. 443)
95+
# - {date}: Scan date, format: DD-MM-YYYY (e.g. 07-10-2022)
96+
# - {datetime}: Scan datetime, format: DD-MM-YYYY_HH-MM-SS (e.g. 2025-01-23_14:32:27)
97+
#output-file = reports/{host}/{scheme}_{port}.{extension}
98+
#mysql-url = mysql://user:password@localhost/database
99+
#postgres-url = postgres://user:password@localhost/database
100+
# Table to be used for SQL output (SQLite, MySQL, PostgreSQL)
101+
output-sql-table = {scheme}_{host}:{port}
102+
#log-file = /path/to/dirsearch.log
103+
#log-file-size = 50000000
104+
```

‎docs/index.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# dirsearch Documentation
2+
3+
dirsearch is an advanced web path brute-forcer. This documentation is split into focused pages so the repository README can stay concise and the docs can later become the base for a documentation site.
4+
5+
## User Documentation
6+
7+
- [Installation](installation.md): supported platforms, Python installation, standalone binaries, and Docker usage.
8+
- [Usage Guide](usage.md): common command examples, recursion, filtering, proxies, raw requests, reports, and practical tips.
9+
- [Wordlists](wordlists.md): extension handling, bundled categories, templates, prefixes, suffixes, and wordlist transformations.
10+
- [CLI Options](options.md): complete command-line option reference.
11+
- [Configuration](configuration.md): `config.ini` behavior and reference.
12+
- [Sessions](sessions.md): saving, listing, and resuming interrupted scans.
13+
- [Python API](python-api.md): using dirsearch from Python automation.
14+
15+
## Maintainer Documentation
16+
17+
- [Building](building.md): PyInstaller builds, standalone binaries, and GitHub Actions workflows.
18+
- [References](references.md): external articles, tutorials, and videos.

‎docs/installation.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Installation
2+
3+
## Supported Platforms
4+
5+
dirsearch runs on multiple platforms and can be used either via Python or standalone binaries.
6+
7+
| Platform | Python | Standalone Binary |
8+
|----------|--------|-------------------|
9+
| Linux (x86_64) | Python 3.9-3.14 | `dirsearch-linux-amd64` |
10+
| Windows (x64) | Python 3.9-3.14 | `dirsearch-windows-x64.exe` |
11+
| macOS (Intel) | Python 3.9-3.14 | `dirsearch-macos-intel` |
12+
| macOS (Apple Silicon) | Python 3.9-3.14 | `dirsearch-macos-silicon` |
13+
14+
Standalone binaries are self-contained executables that do not require a Python installation.
15+
16+
## Install from Source
17+
18+
Requirement: Python 3.9 or higher.
19+
20+
```sh
21+
git clone https://github.com/maurosoria/dirsearch.git --depth 1
22+
cd dirsearch
23+
python3 dirsearch.py -u https://example.com -w tests/static/wordlist.txt -q
24+
```
25+
26+
## Other Install Methods
27+
28+
- ZIP archive: [Download the master branch](https://github.com/maurosoria/dirsearch/archive/master.zip).
29+
- PyPI: `pip3 install dirsearch` or `pip install dirsearch`.
30+
- Docker: `docker build -t "dirsearch:v5.0.0" .`.
31+
- Kali Linux: `sudo apt-get install dirsearch` (deprecated).
32+
33+
## Standalone Binaries
34+
35+
Pre-built standalone binaries are available for all major platforms. Download them from [Releases](https://github.com/maurosoria/dirsearch/releases).
36+
37+
| Platform | Binary Name | Architecture |
38+
|----------|-------------|--------------|
39+
| Linux | `dirsearch-linux-amd64` | x86_64 |
40+
| Windows | `dirsearch-windows-x64.exe` | x64 |
41+
| macOS Intel | `dirsearch-macos-intel` | x86_64 |
42+
| macOS Apple Silicon | `dirsearch-macos-silicon` | ARM64 |
43+
44+
Linux and macOS usage:
45+
46+
```sh
47+
chmod +x dirsearch-linux-amd64
48+
./dirsearch-linux-amd64 -u https://target
49+
```
50+
51+
Windows usage:
52+
53+
```sh
54+
dirsearch-windows-x64.exe -u https://target
55+
```
56+
57+
Standalone binaries include bundled `db/` wordlists and `config.ini`. Session files are stored in `$HOME/.dirsearch/sessions/` when using bundled builds.
58+
59+
## Docker
60+
61+
Install Docker on Linux:
62+
63+
```sh
64+
curl -fsSL https://get.docker.com | bash
65+
```
66+
67+
Docker may require superuser permissions.
68+
69+
Build the image:
70+
71+
```sh
72+
docker build -t "dirsearch:v5.0.0" .
73+
```
74+
75+
Run dirsearch from the image:
76+
77+
```sh
78+
docker run -it --rm "dirsearch:v5.0.0" -u target -e php,html,js,zip
79+
```

0 commit comments

Comments
 (0)