Snailpath 🐌⚡
Smart, low–false-positive directory discovery for modern web apps.
Async scanner with HTTP/2, soft-404 suppression, pragmatic budgets/resume support, and polished outputs (HTML, JSONL, evidence, Burp/ZAP replay pack).
Table of Contents
Why Snailpath?
Other busters are great at fast brute-forcing. Snailpath goes after coverage and signal quality:
- Zero-FP focus: combine auto-calibration with SimHash similarity to suppress wildcard 200s and soft-404s.
- Operator UX: readable HTML report, evidence files for proof, and a drop-in replay pack for Burp/ZAP.
- Budgets & resiliency: resumable scans, request/time budgets, and graceful HTTP/1.1/2 fallbacks.
Features
- Async engine (HTTP/2) with connection pooling and retries.
- Zero-FP mode (
--zero-fp): auto-calibrate on random miss paths + SimHash similarity filtering.
- Outputs: JSONL (machine), HTML report (human), evidence (headers + body snippet), replay pack (.http).
- Budgets & resumability: stop by time/request budgets; resume from previous JSONL.
- Extensible design: link/asset discovery helpers and optional HTTP/3 support behind an extra dependency.
- Pipx-ready packaging, Dockerfile, GitHub Actions CI, tests, and a tiny test server.
Install
From Source (Local Dev)
pip install .
# optional HTTP/3 support:
pip install 'aioquic>=0.9.25'
pipx (Once Published)
pipx install snailpath
# optional HTTP/3:
pipx inject snailpath 'aioquic>=0.9.25'
Requirements
- Python 3.9+ (tested on 3.9–3.12)
Quick Start
snailpath https://example.com wordlists/small.txt \
-c 80 --zero-fp \
--include 200,204,301-308 -x php -x bak \
-o out/target.jsonl --report out/target.html \
--evidence out/evidence --replay-pack out/replay.http
Resume & Checkpoint
# skip paths already found
snailpath https://example.com wl.txt --resume-from out/target.jsonl -o out/target.jsonl
# stop after a fixed budget
snailpath https://example.com wl.txt --budget-requests 10000 --budget-seconds 600
CLI Reference
Positional
base_url – e.g. https://target.tld
wordlist – path to a wordlist file
Common Flags
-c, --concurrency <int> – max concurrent requests (default 60)
-t, --timeout <sec> – per-request timeout (default 10)
-r, --recurse – reserved for future depth-1 recursion
-x, --ext <ext> – try extension (repeatable): -x php -x bak
--include "<codes/ranges>" – e.g. 200,204,301-303
--exclude "<codes/ranges>"
-o, --jsonl <path> – write JSONL findings
--report <path> – write HTML report
--evidence <dir> – save headers and 2KB body snippet per hit
--replay-pack <path> – write raw HTTP requests (.http) for Burp/ZAP
--resume-from <jsonl> – skip paths present in a prior JSONL
--proxy <url> – e.g. http://127.0.0.1:8080
--header "Name: Value" – custom header (repeatable)
--method <HEAD|GET> – primary probe method (default HEAD)
--zero-fp – soft-404 suppression (auto-cal + similarity)
--budget-requests <N> – stop after N requests
--budget-seconds <S> – stop after S seconds
Outputs
JSONL (Machine-Readable)
Each line is a JSON object. Example:
{
"url": "https://example.com/admin",
"path": "/admin",
"code": 200,
"length": 1234,
"title": "Admin Portal",
"headers": { "content-type": "text/html; charset=utf-8" },
"reason": "interesting-status,has-title,nontrivial-size",
"body_snippet": "<!doctype html>..."
}
HTML Report (Human)
A self-contained HTML file with summary and colorized findings.
Evidence Directory
For each hit, saves:
<status>_<path>.headers.txt
<status>_<path>.body.txt (first 2KB)
Replay Pack (.http)
Raw HTTP/1.1 request blocks suitable for "Paste raw" in Burp/ZAP or manual replay.
How It Works (Brief)
- Engine:
httpx.AsyncClient with HTTP/2 by default and resilient timeouts.
- Zero-FP mode: randomly probes improbable paths to build a baseline (status/length) and computes 64-bit SimHash over tokenized text. A result is filtered if it's sufficiently similar to the baseline soft-404s.
- Discovery helpers: utilities for link/src extraction to merge with traditional wordlists.
- Budgets: optional time/request ceilings and resume-from-JSONL to avoid duplicate work.
Tips & Patterns
- Stealthy recon: use
--method HEAD with --include 200,204,301-308 and enable --zero-fp.
- Enrich candidates: merge in paths found via HTML
href/src extraction where appropriate.
- Triage fast: generate
--report and --replay-pack, then validate in Burp/ZAP.
- CI-safe budgets: run with
--budget-requests or --budget-seconds.
Tiny Test Server
A minimal server to exercise success paths and soft-404 detection.
python tools/testserver.py
# serves:
# /exists -> 200 OK with a title
# /soft404/* -> 200 OK soft-404 template
# /random -> 200 OK random payload
# everything else -> 404
Example run against it:
snailpath http://127.0.0.1:8000 wordlists/small.txt \
--zero-fp -o out.jsonl --report out.html
Docker
docker build -t snailpath:latest .
docker run --rm -it snailpath:latest https://target.tld wordlists/small.txt -o out.jsonl
CI
GitHub Actions workflow (.github/workflows/ci.yml) runs lint/basic tests on Python 3.9–3.12.
Add tests in tests/ (see example) and keep features behind flags.
Contributing
- Keep experimental features behind flags (e.g.,
--h3, --zero-fp).
- Add/extend tests (we ship a tiny server for local checks).
- Maintain output schema stability; document changes in
CHANGELOG.md.
- Open PRs/issues—clear repro steps and expected behavior help a lot.
Security & Ethics
Use Snailpath only on targets you own or have permission to test.
Report vulnerabilities privately first. See SECURITY.md for contact details.
Roadmap
- Priority queue with novelty scoring (SimHash diversity) to reorder crawl branches.
- Expanded API heuristics and verb probing.
- More output formats (CSV, JUnit) and richer HTML triage.
- Deeper recursion modes with strict scope controls.
License
MIT — see LICENSE.
Getting Started
- Wordlists:
wordlists/small.txt
- Example commands: see Quick Start
- Need help? Open an issue with your command, logs, and environment details.
📚 Documentation & Author
This project's full writeup, methodology, and related research lives at:
https://snailsploit.com/tools
Created by Kai Aizen — independent offensive security researcher.
snailsploit.com · Research · Frameworks · GitHub · LinkedIn · ResearchGate · X/Twitter
Same attack. Different substrate.