LULZBUSTER(1)

NAME
lulzbuster - a very fast and smart web directory and file enumeration tool

SYNOPSIS
lulzbuster -s url [options]
lulzbuster -z session-file [options]
lulzbuster {-V|-H|-X}

DESCRIPTION
lulzbuster is a multithreaded, very fast and smart HTTP(S) directory and file bruteforcer written in C on top of libcurl. Given a target URL and a wordlist, it enumerates valid paths by firing concurrent HTTP requests and reporting back the responses that look like real hits (i.e. status codes the user did not exclude). It is aimed at penetration testers, bug-bounty hunters and CTF players who want a small, fast, scriptable tool that does one thing well.

The scan flow is:

•   parse the wordlist and any user-supplied extensions (-A) into a flat list of attack URLs;

•   fire a handful of probes against random URL shapes to detect a wildcard 200 ("everything answers OK") and capture its (code, size) fingerprint;

•   spin up N worker threads (-t) that share a libcurl share handle for DNS, SSL session and connection reuse;

•   run each request, parse code/size/lines/words, and emit a row to stderr plus to any selected log files (-O / -l);

•   optionally recurse into hits whose URL ends with '/' (-d);

•   on Ctrl+C, SIGTERM, or a global timeout (-T) write a per-target session file so the scan can be resumed with -z.

Two modes of operation are worth calling out:

Default mode
    Reports every response whose status code is not in the exclude list (-x). Fast, but noisy on sites that return 200 to everything.

Smart mode (-S)
    Uses the wildcard fingerprint plus a (code, size_bucket) clustering table (-K) to suppress hits that look like wildcard noise. Slower because of the extra bookkeeping, but the output is far more actionable.

OPTIONS

  Target

-s url
    Target start URL. Required for any real scan. Must be a full http:// or https:// URL.

  HTTP

-h method
    HTTP request method (default: GET). Supported: HEAD, GET, POST, PUT, DELETE, OPTIONS. Pass ? to list them and exit.

-x codes
    Comma-separated list of HTTP status codes to exclude from the hit table (default: 400,404,500,501,502,503). Use this to surface codes the default ignores, e.g. -x 400 alone keeps every other response.

-f  Follow HTTP redirects. Hint: appending '/' via -A '/' is usually preferable to -f because it avoids a second round-trip per word.

-F num
    Maximum number of redirects to follow (default: 0; -1 = unlimited; only used together with -f).

-u ua
    User-agent string (default: built-in Windows Edge).

-U  Pick a random user-agent from the built-in list per request. Mutually exclusive with -u. See -X to print the list.

-c header
    Custom HTTP header(s), e.g. -c 'Cookie: session=abc'. Currently one -c per scan; multiple headers go in the same string separated by CRLF if your shell can quote it.

-a user:pass
    HTTP authentication credentials. lulzbuster sends CURLAUTH_ANY, so auth only fires once a 401 challenge comes back.

-r  Auto-update the Referer header to the previous URL (curl's CURLOPT_AUTOREFERER). Only effective alongside -f since Referer is set by curl when following a redirect.

-j ver
    HTTP version: 1.0, 1.1, 2.0, 3.0. Default is curl's default. ? lists them.

  TLS

-i  Insecure mode — skip server certificate and hostname verification. Useful against self-signed staging environments.

-E file
    Client certificate file (PEM) for mTLS-protected targets.

-y file
    Client key file (PEM).

-Y pass
    Passphrase for an encrypted client key.

  Timeouts

-D sec
    Per-request delay (default: 0). Use to be polite or evade rate-limits.

-C sec
    Connect timeout (default: 10).

-R sec
    Request (read) timeout (default: 30).

-T sec
    Global wall-clock timeout. When it fires, lulzbuster behaves like the user hit Ctrl+C: in-flight requests finish, partial stats are printed, the session is saved, and the process exits.

  Tuning

-t num
    Worker thread count (default: 30, max: implementation-defined).

-g num
    Connection cache size for libcurl (default: 30). Should match -t for steady-state scans — smaller values cause connection churn.

  Wordlist

-w file
    Wordlist file. Default: /usr/local/share/lulzbuster/lists/medium.txt when installed system-wide.

-A list
    Comma-separated list of extensions to append to each word, e.g. -A '/,.php,.bak'. The bare word is also probed in addition to each extension, so -A '.php' tests both /foo and /foo.php.

  Proxy

-p url
    Proxy address, format: <scheme>://<host>:<port>. Supported schemes: http, https, socks4, socks4a, socks5, socks5h. ? lists them.

-P user:pass
    Proxy authentication credentials.

  Body filter

-m size
    Skip hits whose body is smaller than size bytes. Suffixes K, M, G are accepted (e.g. -m 10K).

-M size
    Skip hits whose body is bigger than size bytes. Same suffix syntax as -m.

-b regex
    Keep only hits whose response body matches the given POSIX extended regex, e.g. -b 'admin|login'. Complements -x, -m and -M for noisy targets where the status code and body size alone are not discriminating (CMS soft-404s, single-page apps, etc.). The regex is evaluated against the first MiB of body.

-B regex
    Drop hits whose response body matches the given POSIX extended regex, e.g. -B 'page not found'. The hit is filtered out before -S cluster bookkeeping, so suppression thresholds are not polluted by content-filtered noise. Same buffering rules as -b.

  Smart mode

-S  Enable smart mode: wildcard-fingerprint suppression plus (code, size_bucket) cluster suppression. Recommended for any target you do not already know is wildcard-clean.

-K num
    Cluster threshold for smart mode (default: 8). After num hits with the same (code, size_bucket) tuple, further matches in that cluster are suppressed as wildcard noise.

  Recursion

-d depth
    Maximum recursion depth (default: 0 = no recursion). lulzbuster recurses into hits whose URL ends with '/' and returned one of 200, 301, 302, 401, 403.

-e list
    Comma-separated list of substrings; URLs matching any are excluded from recursion (e.g. -e '/admin/,logout'). The hit itself is still reported, only the descent is skipped.

  Output

-l file
    Log hits to a file. With a single -O format the path is used verbatim; with multiple formats the path is treated as a stem and .<ext> is appended per format. Without -O, -l implies the default log (text) format.

-O formats
    Opt-in logging plus format selection. Accepts log, csv, jsonl, all, or a comma-list (e.g. -O log,jsonl). Without -l, each format gets an auto-derived filename based on the start URL (e.g. https-www-example-com.csv).

-N  Disable colored output on stderr. Also auto-disabled when stderr is not a TTY or when the NO_COLOR environment variable is set. Logfiles are always plain text regardless of this flag.

  Other

-n list
    Nameservers (default: 1.1.1.1,8.8.8.8,208.67.222.222). Comma-separated.

-z file
    Resume from a previously written session file. The session captures -s, -w, -A, -S/-K, -d/-e and the word offset reached at interrupt time. Wordlist mtime/size are verified to refuse mismatched resumes.

  Misc

-X  Print the built-in user-agent list and exit.

-V  Print the version and exit.

-H  Print the help screen and exit.

EXAMPLES

Plain scan against a target with the default wordlist:

    $ lulzbuster -s https://example.com/

Smart-mode scan with PHP/HTML extensions, recursion two levels deep, and multi-format logging:

    $ lulzbuster -s https://target/ -w lists/big.txt \
                 -A '.php,.html,/' -S -d 2 -O all

Polite scan via a SOCKS5 proxy with a 200ms delay:

    $ lulzbuster -s http://intranet.local/ -t 5 -D 1 \
                 -p socks5h://127.0.0.1:9050

Resume an interrupted scan:

    $ lulzbuster -z https-target-com.session

FILES

/usr/local/share/lulzbuster/lists/
    Bundled wordlists (small.txt, medium.txt, big.txt). The default -w points to medium.txt.

<stem>.session
    Per-target session file written on interrupt, where <stem> is derived from the start URL (e.g. https-example-com.session). The path is also printed at exit time.

<stem>.{log,csv,jsonl}
    Auto-derived hit log files when -O is used without -l.

SIGNALS

SIGINT
    Ctrl+C. Triggers a graceful exit: in-flight requests are allowed to finish, partial stats are printed, the session file is written, and the process exits with success status.

SIGTERM
    Polite kill(1). Same handler as SIGINT.

SIGALRM
    Internally raised when -T fires. Same effect as SIGINT.

ENVIRONMENT

NO_COLOR
    If set (any value), ANSI color escapes are not emitted. Equivalent to passing -N.

EXIT STATUS

0   Scan completed (with or without hits) or was interrupted gracefully.

1   Fatal error during startup, argument parsing, or unrecoverable HTTP/system error mid-run.

NOTES

•   HTTP/2 multiplexing is not used — each worker thread holds its own easy handle. Connection reuse across threads still works via libcurl's share handle.

•   Hit clustering (-S) is order-sensitive: which 8 hits in a cluster are printed before suppression depends on worker scheduling. The total "hits printed / hits suppressed" stats are deterministic.

•   The session-file format carries a version key (SESSION_VERSION) and mismatched resumes are refused with an error.

BUGS
Report bugs, crashes, false-positives, regressions or general feedback to noptrix@nullsecurity.net (noptrix@nullsecurity.net). Please include the full command line, the -V output, and a short description of the target environment when filing.

AUTHOR
Written by Levon 'noptrix' Kayan noptrix@nullsecurity.net (<noptrix@nullsecurity.net>).

SEE ALSO
curl(1),

COPYRIGHT
See the LICENSE file shipped with this distribution.