Skip to content

Commit 8552b1e

Browse files
maurosoriamaurosoria
authored
Merge pull request #1519 from maurosoria/claude/improve-readme-structure-uppWU
Restructure README with collapsible sections and platform support
2 parents 5c9d58a + 086035a commit 8552b1e

1 file changed

Lines changed: 284 additions & 28 deletions

File tree

‎README.md‎

Lines changed: 284 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -22,34 +22,36 @@ dirsearch - Web path discovery
2222

2323
Table of Contents
2424
------------
25-
* [Installation](#installation--usage)
26-
* [Wordlists](#wordlists-important)
27-
* [Options](#options)
28-
* [Configuration](#configuration)
29-
* [How to use](#how-to-use)
30-
* [Simple usage](#simple-usage)
31-
* [Pausing progress](#pausing-progress)
32-
* [Recursion](#recursion)
33-
* [Threads](#threads)
34-
* [Asynchronous](#asynchronous)
35-
* [Prefixes / Suffixes](#prefixes--suffixes)
36-
* [Blacklist](#blacklist)
37-
* [Filters](#filters)
38-
* [Raw request](#raw-request)
39-
* [Wordlist formats](#wordlist-formats)
40-
* [Exclude extensions](#exclude-extensions)
41-
* [Scan sub-directories](#scan-sub-directories)
42-
* [Proxies](#proxies)
43-
* [Reports](#reports)
44-
* [More example commands](#more-example-commands)
45-
* [Support Docker](#support-docker)
46-
* [Install Docker Linux](#install-docker-linux)
47-
* [Build Image dirsearch](#build-image-dirsearch)
48-
* [Using dirsearch](#using-dirsearch)
49-
* [References](#references)
50-
* [Tips](#tips)
51-
* [Contribution](#contribution)
52-
* [License](#license)
25+
- [Supported Platforms](#supported-platforms)
26+
- [Installation & Usage](#installation--usage)
27+
- [Standalone Binaries](#standalone-binaries)
28+
- [Wordlists](#wordlists-important)
29+
- [Options](#options)
30+
- [Configuration](#configuration)
31+
- [How to use](#how-to-use)
32+
- [Session Management](#session-management)
33+
- [Support Docker](#support-docker)
34+
- [Building from Source](#building-from-source)
35+
- [CI/CD & GitHub Workflows](#cicd--github-workflows)
36+
- [References](#references)
37+
- [Tips](#tips)
38+
- [Contribution](#contribution)
39+
- [License](#license)
40+
41+
42+
Supported Platforms
43+
------------
44+
45+
dirsearch runs on multiple platforms and can be used either via Python or standalone binaries:
46+
47+
| Platform | Python | Standalone Binary |
48+
|----------|--------|-------------------|
49+
| **Linux** (x86_64) | Python 3.9+ | `dirsearch-linux-amd64` |
50+
| **Windows** (x64) | Python 3.9+ | `dirsearch-windows-x64.exe` |
51+
| **macOS** (Intel) | Python 3.9+ | `dirsearch-macos-intel` |
52+
| **macOS** (Apple Silicon) | Python 3.9+ | `dirsearch-macos-silicon` |
53+
54+
Standalone binaries are self-contained executables that don't require Python installation.
5355

5456

5557
Installation & Usage
@@ -66,6 +68,33 @@ Choose one of these installation options:
6668
- Install with Kali Linux: `sudo apt-get install dirsearch` (deprecated)
6769

6870

71+
Standalone Binaries
72+
------------
73+
74+
Pre-built standalone binaries are available for all major platforms. These don't require Python to be installed.
75+
76+
**Download from [Releases](https://github.com/maurosoria/dirsearch/releases)**
77+
78+
| Platform | Binary Name | Architecture |
79+
|----------|-------------|--------------|
80+
| Linux | `dirsearch-linux-amd64` | x86_64 |
81+
| Windows | `dirsearch-windows-x64.exe` | x64 |
82+
| macOS Intel | `dirsearch-macos-intel` | x86_64 |
83+
| macOS Apple Silicon | `dirsearch-macos-silicon` | ARM64 |
84+
85+
**Usage:**
86+
```sh
87+
# Linux/macOS - make executable first
88+
chmod +x dirsearch-linux-amd64
89+
./dirsearch-linux-amd64 -u https://target
90+
91+
# Windows
92+
dirsearch-windows-x64.exe -u https://target
93+
```
94+
95+
**Note:** Standalone binaries include bundled `db/` wordlists and `config.ini`. Session files are stored in `$HOME/.dirsearch/sessions/` when using bundled builds.
96+
97+
6998
Wordlists (IMPORTANT)
7099
---------------
71100
**Summary:**
@@ -75,6 +104,9 @@ Wordlists (IMPORTANT)
75104
- 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*)
76105
- To use multiple wordlists, you can separate your wordlists with commas. Example: `wordlist1.txt,wordlist2.txt`.
77106

107+
<details>
108+
<summary><strong>Wordlist Examples (click to expand)</strong></summary>
109+
78110
**Examples:**
79111

80112
- *Normal extensions*:
@@ -117,10 +149,15 @@ login.jsp
117149
login.jspa
118150
```
119151

152+
</details>
153+
120154

121155
Options
122156
-------
123157

158+
<details>
159+
<summary><strong>Full Options List (click to expand)</strong></summary>
160+
124161
```
125162
Usage: dirsearch.py [-u|--url] target [-e|--extensions] extensions [options]
126163
@@ -290,10 +327,15 @@ Options:
290327
--log=PATH Log file
291328
```
292329

330+
</details>
331+
293332

294333
Configuration
295334
---------------
296335

336+
<details>
337+
<summary><strong>Configuration File Reference (click to expand)</strong></summary>
338+
297339
By default, `config.ini` inside your dirsearch directory is used as the configuration file but you can select another file via `--config` flag or `DIRSEARCH_CONFIG` environment variable.
298340

299341
```ini
@@ -371,6 +413,8 @@ autosave-report-folder = reports/
371413
# log-file-size = 50000000
372414
```
373415

416+
</details>
417+
374418

375419
How to use
376420
---------------
@@ -392,6 +436,9 @@ python3 dirsearch.py -e php,html,js -u https://target
392436
python3 dirsearch.py -e php,html,js -u https://target -w /path/to/wordlist
393437
```
394438

439+
<details>
440+
<summary><strong>More Usage Examples (click to expand)</strong></summary>
441+
395442
---
396443
### Pausing progress
397444
dirsearch allows you to pause the scanning progress with CTRL+C, from here, you can save the progress (and continue later), skip the current target, or skip the current sub-directory.
@@ -619,9 +666,84 @@ python3 dirsearch.py -u https://target --header-list rate-limit-bypasses.txt
619666

620667
**There are more to discover, try yourself!**
621668

669+
</details>
670+
671+
672+
Session Management
673+
---------------
674+
675+
dirsearch supports saving and resuming scan sessions, allowing you to pause a long-running scan and continue it later.
676+
677+
### Session Format
678+
679+
Sessions are stored in **JSON format** (directory-based structure) for human readability and easy inspection. Legacy `.pickle`/`.pkl` session files are no longer supported.
680+
681+
**Session directory structure:**
682+
```
683+
session_name/
684+
├── meta.json # Version, timestamps, output history
685+
├── controller.json # Scan state (URLs, directories, progress)
686+
├── dictionary.json # Wordlist state and position
687+
└── options.json # Command-line options used
688+
```
689+
690+
### Saving a Session
691+
692+
When you pause a scan with **CTRL+C**, you'll be prompted to save the session:
693+
694+
```
695+
python3 dirsearch.py -u https://target -e php
696+
# Press CTRL+C during scan
697+
# Select "save" and provide a session name
698+
```
699+
700+
### Resuming a Session
701+
702+
Resume a saved session with the **-s** / **--session** flag:
703+
704+
```
705+
python3 dirsearch.py -s sessions/my_session
706+
```
707+
708+
### Listing Available Sessions
709+
710+
View all resumable sessions with **--list-sessions**:
711+
712+
```
713+
python3 dirsearch.py --list-sessions
714+
```
715+
716+
This displays:
717+
- Session path
718+
- Target URL
719+
- Remaining targets and directories
720+
- Jobs processed
721+
- Error count
722+
- Last modified time
723+
724+
### Custom Sessions Directory
725+
726+
Specify a custom directory to search for sessions:
727+
728+
```
729+
python3 dirsearch.py --list-sessions --sessions-dir /path/to/sessions
730+
```
731+
732+
**Default session locations:**
733+
- **Source install:** `<dirsearch>/sessions/`
734+
- **Bundled binary:** `$HOME/.dirsearch/sessions/`
735+
736+
### Output History
737+
738+
Sessions maintain a history of previous scan outputs, allowing you to review results from interrupted scans. Each resume appends to the output history with timestamps.
739+
622740

623741
Support Docker
624742
---------------
743+
744+
<details>
745+
<summary><strong>Docker Installation & Usage (click to expand)</strong></summary>
746+
625747
### Install Docker Linux
626748
Install Docker
627749

@@ -646,9 +768,141 @@ For using
646768
docker run -it --rm "dirsearch:v0.4.3" -u target -e php,html,js,zip
647769
```
648770

771+
</details>
772+
773+
774+
Building from Source
775+
---------------
776+
777+
You can build standalone executables using PyInstaller. This creates a single binary file that includes all dependencies.
778+
779+
### Requirements
780+
781+
- Python 3.9+
782+
- PyInstaller 6.3.0+
783+
- All dependencies from `requirements.txt`
784+
785+
### Quick Build
786+
787+
```sh
788+
# Install dependencies
789+
pip install -r requirements.txt
790+
pip install pyinstaller==6.3.0
791+
792+
# Build using the spec file
793+
pyinstaller pyinstaller/dirsearch.spec
794+
795+
# Binary will be in dist/dirsearch
796+
./dist/dirsearch --version
797+
```
798+
799+
### Manual Build (Linux/macOS)
800+
801+
```sh
802+
pyinstaller \
803+
--onefile \
804+
--name dirsearch \
805+
--paths=. \
806+
--collect-submodules=lib \
807+
--add-data "db:db" \
808+
--add-data "config.ini:." \
809+
--add-data "lib/report:lib/report" \
810+
--hidden-import=requests \
811+
--hidden-import=httpx \
812+
--hidden-import=urllib3 \
813+
--hidden-import=jinja2 \
814+
--hidden-import=colorama \
815+
--strip \
816+
--clean \
817+
dirsearch.py
818+
```
819+
820+
### Manual Build (Windows)
821+
822+
```powershell
823+
pyinstaller `
824+
--onefile `
825+
--name dirsearch `
826+
--paths=. `
827+
--collect-submodules=lib `
828+
--add-data "db;db" `
829+
--add-data "config.ini;." `
830+
--add-data "lib/report;lib/report" `
831+
--hidden-import=requests `
832+
--hidden-import=httpx `
833+
--hidden-import=urllib3 `
834+
--hidden-import=jinja2 `
835+
--hidden-import=colorama `
836+
--clean `
837+
dirsearch.py
838+
```
839+
840+
**Note:** Windows uses `;` instead of `:` as the path separator in `--add-data`.
841+
842+
### Build Output
843+
844+
After building:
845+
- **Linux/macOS:** `dist/dirsearch`
846+
- **Windows:** `dist/dirsearch.exe`
847+
848+
The binary includes:
849+
- All Python dependencies
850+
- `db/` directory (wordlists, blacklists)
851+
- `config.ini` (default configuration)
852+
- `lib/report/` (Jinja2 templates for reports)
853+
854+
855+
CI/CD & GitHub Workflows
856+
---------------
857+
858+
dirsearch uses GitHub Actions for continuous integration and automated builds.
859+
860+
### Available Workflows
861+
862+
| Workflow | Trigger | Description |
863+
|----------|---------|-------------|
864+
| **Inspection** (CI) | Push, PR | Runs tests, linting, and codespell on Python 3.9/3.11 across Ubuntu and Windows |
865+
| **PyInstaller Linux** | Manual, Workflow call | Builds `dirsearch-linux-amd64` binary |
866+
| **PyInstaller Windows** | Manual, Workflow call | Builds `dirsearch-windows-x64.exe` binary |
867+
| **PyInstaller macOS Intel** | Manual, Workflow call | Builds `dirsearch-macos-intel` binary |
868+
| **PyInstaller macOS Silicon** | Manual, Workflow call | Builds `dirsearch-macos-silicon` binary |
869+
| **PyInstaller Draft Release** | Manual | Builds all platforms and creates a draft GitHub release |
870+
| **Docker Image** | Push, PR | Builds and tests Docker image |
871+
| **CodeQL Analysis** | Push, PR, Schedule | Security scanning with GitHub CodeQL |
872+
| **Semgrep Analysis** | Push, PR | Static analysis with Semgrep |
873+
874+
### Running Workflows Manually
875+
876+
PyInstaller builds can be triggered manually from the GitHub Actions tab:
877+
878+
1. Go to **Actions** > Select workflow (e.g., "PyInstaller Linux")
879+
2. Click **Run workflow**
880+
3. Download artifacts from the completed run
881+
882+
### Creating a Release
883+
884+
To create a new release with all platform binaries:
885+
886+
1. Go to **Actions** > **PyInstaller Draft Release**
887+
2. Click **Run workflow**
888+
3. Enter the tag (e.g., `v0.4.4`)
889+
4. Select target branch
890+
5. Optionally mark as prerelease
891+
6. Review and publish the draft release
892+
893+
### Build Matrix
894+
895+
The CI workflow tests on:
896+
- **Python versions:** 3.9, 3.11
897+
- **Operating systems:** Ubuntu (latest), Windows (latest)
898+
649899

650900
References
651901
---------------
902+
903+
<details>
904+
<summary><strong>Articles & Tutorials (click to expand)</strong></summary>
905+
652906
- [Comprehensive Guide on Dirsearch](https://www.hackingarticles.in/comprehensive-guide-on-dirsearch/) by Shubham Sharma
653907
- [Comprehensive Guide on Dirsearch Part 2](https://www.hackingarticles.in/comprehensive-guide-on-dirsearch-part-2/) by Shubham Sharma
654908
- [How to Find Hidden Web Directories with Dirsearch](https://www.geeksforgeeks.org/how-to-find-hidden-web-directories-with-dirsearch/) by GeeksforGeeks
@@ -663,6 +917,8 @@ References
663917
- [Best Tools For Directory Bruteforcing](https://secnhack.in/multiple-ways-to-find-hidden-directory-on-web-server/) by Shubham Goyal
664918
- [Discover hidden files & directories on a webserver - dirsearch full tutorial](https://www.youtube.com/watch?v=jVxs5at0gxg) by CYBER BYTES
665919

920+
</details>
921+
666922

667923
Tips
668924
---------------

0 commit comments

Comments
 (0)