Noureddine RAMDI / dirsearch: a Python web path brute-forcer with precise extension handling

Created Mon, 04 May 2026 10:23:02 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
885 Words
github-stars python security pentesting web bruteforce reconnaissance

maurosoria/dirsearch

Web security reconnaissance often hinges on uncovering hidden directories and files that web servers don’t advertise. dirsearch tackles this challenge with a Python-based brute-forcing tool designed to discover such paths efficiently and flexibly. Its standout feature is a precise extension handling system that avoids the typical wordlist bloat seen in other brute-forcers.

What dirsearch does and how it is built

dirsearch is a web path brute-forcer focused on security reconnaissance. It systematically probes web servers by sending HTTP requests for potential directory and file paths derived from wordlists. The goal is to find hidden or unlinked resources that might reveal sensitive information or vulnerable endpoints.

The tool is written in Python and supports Python 3.9+. Its architecture centers on multi-threaded HTTP request dispatching, enabling concurrent scanning for speed. It supports recursive brute-forcing, which means it can dig deeper into discovered directories automatically.

One of dirsearch’s strengths is its flexible input handling: it accepts URLs directly, CIDR ranges, nmap scan reports, and raw HTTP request files. This flexibility facilitates integration into larger security workflows.

Session resumption is another practical feature, allowing long scans to be paused and resumed without losing progress—important for large or slow scans.

Under the hood, dirsearch relies on a sophisticated wordlist system that includes keyword replacement mechanisms for extensions. This design enables efficient and precise generation of path permutations.

How dirsearch manages extensions: a technical perspective

Many brute-forcers handle file extensions by naively appending them to every dictionary entry, which leads to massive, often redundant requests. dirsearch solves this with a %EXT% keyword system embedded in the wordlists themselves.

Instead of blindly appending extensions, entries in the wordlist can include %EXT% as a placeholder. During scanning, dirsearch replaces this placeholder with each extension from a provided list. For example, a wordlist entry like admin.%EXT% expands to admin.php, admin.html, etc., but only for entries explicitly designed to handle extensions.

In addition, dirsearch offers two modes to control extension handling:

  • --force-extensions: appends the list of extensions to every wordlist entry, regardless of whether %EXT% is present. This mode is useful when the wordlist doesn’t use the placeholder but you want to try extensions systematically.

  • --overwrite-extensions: swaps out existing extensions in wordlist entries with the provided list. For example, index.html can be tested as index.php, index.asp, etc.

This approach avoids excessive requests and keeps the scan focused. It also means wordlists can be more compact and maintainable since you don’t need to enumerate every extension variant manually.

The tradeoff is added complexity in wordlist creation and scan configuration. Users need to understand how to structure their wordlists and choose the right extension mode for their target. Poor wordlists or incorrect modes can miss some paths.

The code handling this is surprisingly clean and well-documented, emphasizing maintainability. Furthermore, the multi-threaded scanning engine efficiently dispatches HTTP requests with configurable concurrency, which is critical for keeping scans timely without overwhelming targets.

Quick start

The project supports multiple installation methods, including pip and Docker. The README provides these commands:

Install Docker Linux

Install Docker

curl -fsSL https://get.docker.com | bash

To use docker you need superuser power

Requirements

  • Python 3.9+
  • PyInstaller 6.3.0+
  • All dependencies from requirements.txt

Install dependencies

pip install -r requirements.txt pip install pyinstaller==6.3.0

This setup gets you the dependencies needed to run dirsearch from source. Docker usage simplifies environment setup but requires Docker installed with appropriate privileges.

who dirsearch is for and verdict

dirsearch is a practical and well-maintained tool for security professionals focused on web reconnaissance. It fits well in pentesting toolkits and bug bounty workflows where uncovering hidden paths is a priority.

Its extension handling system is a clear technical advantage, allowing detailed control over request generation and reducing unnecessary traffic. This also helps evade detection and rate-limiting on target servers.

However, dirsearch is not a vulnerability scanner or web crawler—it won’t analyze or exploit found paths. Its effectiveness depends heavily on quality wordlists and correct configuration of extension modes.

The active community and frequent updates mean it keeps pace with evolving web technology trends and security needs. If you routinely perform web security assessments, dirsearch is worth understanding and integrating.

The tradeoff is the need to learn its wordlist syntax and extension handling options to use it effectively—this might steepen the learning curve for beginners but pays off in scan precision.

Overall, dirsearch strikes a good balance between flexibility, performance, and usability for its domain.

→ GitHub Repo: maurosoria/dirsearch ⭐ 14,236 · Python