dirsearch: A Web Path Brute-Forcer That Grows With Your Workflow

If you've ever stared at a web server wondering what's hiding behind paths you haven't discovered yet, you've probably reached for a directory brute-forcing tool. dirsearch is one of the more established options in that space, and it's actively maintained by Mauro Soria and shelld3v. It's a Python-based web path discovery tool, and it's worth a look whether you're doing a one-off scan or wiring something into a larger automation pipeline.

What It Does

At its core, dirsearch is a web path brute-forcer. You give it a target URL, point it at a wordlist (or use the defaults), and it probes paths on the server to find ones that respond. That's the basic loop, but the tool has grown well past that.

It supports extensions via the -e flag, so you can check for php, html, js, and other file types in one pass. Recursion is built in—when it finds a directory, it can go deeper, with a configurable --max-recursion-depth to keep things from running away. There are filters for controlling what counts as a hit, proxy support, raw request handling, and report generation. Wordlists support %EXT% placeholders, categories, templates, prefixes, suffixes, and transformations, which gives you a fair amount of control over how the tool generates candidate paths.

The project requires Python 3.11 or higher. There's also an opt-in Rust native backend for source installs, which the README points to in the installation docs. Pre-built PyInstaller binaries and portable folder archives are available on the Releases page if you'd rather not build from source.

Why It's Cool

• The Python API is a real addition, not an afterthought. The README specifically calls out that dirsearch can be imported and used from Python code—for local automation, MCP servers, REST wrappers, and agent-controlled scans. Configuration lives in a FuzzerConfig object, which means you don't have to parse CLI flags or mess with CLI globals when you're embedding it. That's a meaningful design choice for anyone building tooling on top of it.

• Sessions let you pick up where you left off. Long scans against large targets can take a while. Being able to save, list, and resume scan sessions means you're not starting from scratch if something interrupts you.

• Recursion with a depth cap. Recursive scanning is useful, but unbounded recursion is a good way to hammer a server into the ground. The --max-recursion-depth flag gives you a sane way to control that.

• Wordlist flexibility. The %EXT% placeholder and the category/template/prefix/suffix/transformation support mean you can shape your wordlists without maintaining separate files for every combination. If you've ever hand-edited a wordlist to add extensions, you'll appreciate this.

• The documentation is actually organized. Installation, usage, wordlists, CLI options, configuration, sessions, Python API, and building all have their own docs in the docs/ folder. That's more than you get from a lot of tools in this category.

• Multiple install paths. Clone and run, pip install from GitHub, or grab a pre-built binary. Not everyone wants to manage a Python environment, and dirsearch doesn't force you to.

How to Try It

The quickest path is cloning the repo and running it directly:

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

If you'd rather install it as a command:

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

A few minimal examples to get a feel for the flags:

python3 dirsearch.py -u https://target
python3 dirsearch.py -u https://target -e php,html,js
python3 dirsearch.py -u https://target -e php,html,js -w /path/to/wordlist
python3 dirsearch.py -u https://target -r --max-recursion-depth 3

Use python3 dirsearch.py -h for common options or -hh for the full CLI reference. If you want to use it from Python, the docs/python-api.md file covers templates, custom wordlists, callbacks, authenticated sessions, and scan recipes aimed at agents.

You can find the project at github.com/maurosoria/dirsearch. There's also a Discord server if you want to talk to the team.

Final Thoughts

dirsearch isn't trying to be everything to everyone, but it covers a lot of ground for a path brute-forcer. The combination of recursion, filters, sessions, and an importable Python API makes it useful both as a standalone tool and as a component in something bigger. If you're doing web path discovery and you want something that's actively maintained and documented, it's worth adding to your toolkit. The Python API in particular is the kind of feature that tends to pay off the more you automate—and it's good to see a tool in this space take that seriously.

Follow @githubprojects for more developer tools and open source projects.