From 24a6743281db3dd40a94914755bf31dcb84fdcf6 Mon Sep 17 00:00:00 2001 From: baonq-me Date: Thu, 10 Sep 2026 04:26:38 +0800 Subject: [PATCH] feat(skills): add dirsearch path enumeration playbook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit dirsearch ships in the sandbox and is named in the system prompt, but unlike every other core recon tool (ffuf, nuclei, sqlmap, nmap, httpx, subfinder, naabu, katana) it had no `/tooling` playbook — so agents got no command structure, filtering strategy, non-interactive defaults, or recovery guidance for path/content enumeration. Add `strix/skills/tooling/dirsearch.md` mirroring the ffuf playbook (auto-discovered by the skills glob loader): canonical syntax, high-signal flags, agent-safe baseline, common patterns, correctness/usage rules, failure recovery, and a reciprocal ffuf cross-reference. List dirsearch in the skills README tooling row. Co-Authored-By: Claude Opus 4.8 --- strix/skills/README.md | 2 +- strix/skills/tooling/dirsearch.md | 80 +++++++++++++++++++++++++++++++ 2 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 strix/skills/tooling/dirsearch.md diff --git a/strix/skills/README.md b/strix/skills/README.md index 87a48ddfa..617f11928 100644 --- a/strix/skills/README.md +++ b/strix/skills/README.md @@ -33,7 +33,7 @@ The skills are dynamically injected into the agent's system prompt, allowing it | **`/frameworks`** | Specific testing methods for popular frameworks e.g. Django, Express, FastAPI, and Next.js | | **`/technologies`** | Specialized techniques for third-party services such as Supabase, Firebase, Auth0, and payment gateways | | **`/protocols`** | Protocol-specific testing patterns for GraphQL, WebSocket, OAuth, and other communication standards | -| **`/tooling`** | Command-line playbooks for core sandbox tools (nmap, nuclei, httpx, ffuf, subfinder, naabu, katana, sqlmap) | +| **`/tooling`** | Command-line playbooks for core sandbox tools (nmap, nuclei, httpx, ffuf, dirsearch, subfinder, naabu, katana, sqlmap) | | **`/cloud`** | Cloud provider security testing for AWS, Azure, GCP, and Kubernetes environments | | **`/reconnaissance`** | Advanced information gathering and enumeration techniques for comprehensive attack surface mapping | | **`/custom`** | Community-contributed skills for specialized or industry-specific testing scenarios | diff --git a/strix/skills/tooling/dirsearch.md b/strix/skills/tooling/dirsearch.md new file mode 100644 index 000000000..c859df8bb --- /dev/null +++ b/strix/skills/tooling/dirsearch.md @@ -0,0 +1,80 @@ +--- +name: dirsearch +description: dirsearch path/content enumeration syntax with status/size filtering, recursion, and non-interactive structured output. +--- + +# dirsearch CLI Playbook + +Official docs: +- https://github.com/maurosoria/dirsearch + +dirsearch is a mature path/content brute-forcer that ships with curated +wordlists, sane defaults, extension tagging, and built-in recursion. Reach +for it first for a broad directory/file sweep with no setup; reach for +`ffuf` when you need surgical fuzzing of a specific input position (header, +body, vhost) or precise matcher/filter control. + +Canonical syntax: +`dirsearch -u -e [flags]` + +High-signal flags: +- `-u ` / `-l ` single target URL / list of targets +- `-e ` extensions to append (e.g. `php,html,js,json,txt,bak`); `-f` force extensions on every word +- `-w ` custom wordlist (defaults to the bundled `db/dicts.txt`) +- `-x ` / `--exclude-status ` exclude status codes (e.g. `404,500-599`) +- `-i ` / `--include-status ` include only these status codes +- `--exclude-sizes ` drop responses of a given size (e.g. `0B,123B`) +- `--exclude-text ` / `--exclude-regex ` drop soft-404 bodies +- `-r` recursive discovery; `-R ` / `--max-recursion-depth ` cap depth; `--recursion-status ` +- `-t ` threads; `--max-rate ` requests/sec cap; `-s ` / `--delay ` per-request delay +- `--timeout ` request timeout; `--retries ` +- `-H
` custom header (repeatable); `--cookie `; `--user-agent `; `--random-agent` +- `-m ` HTTP method; `-d ` request body +- `--proxy ` upstream proxy (HTTP/SOCKS); `--proxy-auth` +- `--full-url` print absolute URLs in output +- `-q` / `--quiet-mode` suppress the banner/progress noise +- `-o ` output path; `--output-formats ` structured report +- `--crawl` parse discovered pages for more paths + +Agent-safe baseline for automation: +`dirsearch -u https://target.tld/ -e php,html,js,json,txt --exclude-status 404 --max-rate 50 -t 20 --timeout 10 -q --output-formats json -o dirsearch.json` + +Common patterns: +- Basic content discovery: + `dirsearch -u https://target.tld/ -e php,html,js,json,txt,bak,old --exclude-status 404 -t 30 -q` +- Recursive sweep with bounded depth: + `dirsearch -u https://target.tld/ -e php,json -r -R 2 --recursion-status 200-399 --exclude-status 404 -t 20 -q` +- Include-only interesting codes (auth-gated / redirects): + `dirsearch -u https://target.tld/ -e php,json -i 200,204,301,302,401,403 -t 20 -q` +- Strip soft-404 noise by size: + `dirsearch -u https://target.tld/ -e html --exclude-status 404 --exclude-sizes 0B,1256B -t 20 -q` +- Authenticated enumeration: + `dirsearch -u https://target.tld/ -e php,json -H 'Authorization: Bearer ' --cookie 'session=' --exclude-status 404 -t 15 -q` +- Proxy-instrumented run (route through the Strix proxy): + `dirsearch -u https://target.tld/ -e php,json --proxy http://127.0.0.1:48080 --exclude-status 404 -t 10 -q` +- Multiple targets from a file: + `dirsearch -l targets.txt -e php,json --exclude-status 404 -t 20 -q --output-formats json -o dirsearch.json` + +Critical correctness rules: +- Always constrain results with `--exclude-status 404` (or `-i` allow-list) — the default output is noisy and soft-404 sites need `--exclude-sizes`/`--exclude-text` on top. +- Save structured output with `--output-formats json -o ` for deterministic parsing; parse that file rather than scraping stdout. +- Bound every run: keep `-t`/`--max-rate` conservative to start, cap `-R` recursion depth, and set `--timeout` so a slow target cannot stall the sandbox. +- `-e` only *appends* extensions; use `-f` to force them onto every wordlist entry when the server hides real names behind extensions. + +Usage rules: +- Prefer a targeted `-e` extension set matched to the detected tech stack over a kitchen-sink list. +- Start with the bundled wordlist; switch to a focused custom `-w` (e.g. tech-specific list) only when the default under-covers. +- Feed confirmed paths into `create_note` (endpoint inventory) and `record_coverage` (surface + outcome) so other agents build on the map instead of re-enumerating. + +Failure recovery: +- If output is dominated by soft-404s, add `--exclude-sizes`/`--exclude-text`/`--exclude-regex` instead of raising thread count. +- If the run is too slow, lower `-t`/`--max-rate`, tighten `-e`, and cap `-R` recursion depth. +- If the target rate-limits or blocks, add `-s `, `--random-agent`, and route through `--proxy`. + +If uncertain, query web_search with: +`site:github.com/maurosoria/dirsearch README` + +Alternate tool for surgical fuzzing: `ffuf -w -u https://target.tld/FUZZ`. +Reach for `ffuf` when you need to mutate a precise input position (header, +body, vhost) or want fine-grained `-mc/-fc/-fs` matcher control; reach for +`dirsearch` for a fast, low-setup broad path/content sweep.