Gobuster's seven modes and the options the README never shows

Seven subcommands share one engine, and you cannot add an eighth

Gobuster dispatches on a mode word placed before the flags:

gobuster [mode] [options]

The repository mirrors that split at the top level. main.go is the entry point, cli/ holds the command definitions, libgobuster/ holds the code the modes share, and every mode owns a package: gobusterdir/, gobusterdns/, gobusterfuzz/, gobustergcs/, gobusters3/, gobustertftp/, gobustervhost/. Flag parsing comes from urfave/cli/v2 at v2.27.7, pinned in go.mod, which is why all seven share one option syntax and one help layout.

gobuster help                   # Show general help
gobuster help [mode]            # Show help for specific mode
gobuster [mode] --help          # Alternative help syntax

The seven modes cover web directories and files, DNS subdomains, virtual hosts, Amazon S3 buckets, Google Cloud Storage buckets, TFTP files, and keyword fuzzing. The ceiling here is structural rather than a missing flag. Each of the seven modes is its own package in the tree. Fuzz mode does not close the gap either, because the three substitution points shown are the query string, one request header, and POST data.

# Fuzz URL parameters
gobuster fuzz -u https://example.com?param=FUZZ -w wordlist.txt

# Fuzz headers
gobuster fuzz -u https://example.com -H "X-Custom-Header: FUZZ" -w wordlist.txt

# Fuzz POST data
gobuster fuzz -u https://example.com -d "username=admin&password=FUZZ" -w passwords.txt

The quick start and the vhost section give two different vhost commands

The quick start block is:

gobuster vhost -u https://example.com -w /path/to/wordlist.txt

Later, the vhost section gives this instead:

gobuster vhost -u https://example.com --append-domain -w wordlist.txt

The second tells gobuster to treat each word as a label and append it to the target domain. The first does not, so every word in the wordlist becomes the entire value of the Host header. For a reader who copies the quick start line, the scan asks the target about hosts that have nothing to do with its domain, and the result set is not the one the vhost section is describing. This matters because dir mode and vhost mode accept the same `-u` and `-w` flags, so nothing in the flag names tells you which of the two shapes of request you are about to send, and the help examples do not spell out the difference either. Read the vhost section rather than the quick start, and confirm what your target expects in the Host header before you treat a short result list as proof that no other virtual hosts exist.

go.mod pulls in a pkcs12 library that no documented option reaches

go.mod requires software.sslmate.com/src/go-pkcs12 at v0.6.0, a library for reading PKCS#12 archives. No option in the usage section mentions pkcs12, pfx, a client certificate, or a keystore. The gap runs the same way around terminal control. golang.org/x/term at v0.37.0 and fatih/color at v1.18.0 are direct requirements, with mattn/go-isatty pulled in indirectly, and colour libraries of that kind decide for themselves whether to emit escape sequences based on the output stream, yet none of the usage examples shown turns colour off or reduces output to machine readable lines.

The consequence is concrete. You cannot tell from the README whether PKCS#12 handling belongs to a mode that is not shown in the usage examples, is wired into one of the seven, or is simply unused in the current tree. If your target demands a client certificate before it will talk to you, check `gobuster help [mode]` rather than relying on the usage examples. Neither gap is a reason to avoid the tool, but both mean the documentation is not the whole interface.

The README asks for Go 1.24 while go.mod declares go 1.25

The installation section states the requirement as Go 1.24 or higher, and the troubleshooting list repeats it: ensure Go 1.24+ is installed, checked with `go version`. The module file says otherwise, declaring `go 1.25`, which is the language version the module compiles against rather than a suggestion. A machine on Go 1.24 that follows the quick install line:

go install github.com/OJ/gobuster/v3@latest

will be asking the toolchain to build a module that declares 1.25, and the documented troubleshooting step will not catch it, because 1.24 satisfies the stated floor. The build path has the same split: `go mod tidy` then `go build` for source builds, and `go build -a -o gobuster -trimpath` under CGO_ENABLED=0 inside the Dockerfile. The tree also carries a gofumpt tool directive, .golangci.yml, .yamllint.yml, Taskfile.yml and .goreleaser.yaml, so formatting, linting and release work are all configured. What it does not tell you is the release payload. The README calls the releases page a place to download pre-compiled binaries and its installation section does not say which operating systems and CPU architectures those binaries cover. If you are on Windows or on Apple silicon, that is the one fact you have to verify yourself before you start.

The Docker example names a wordlist the image never puts there

The container example is:

# Pull the latest image
docker pull ghcr.io/oj/gobuster:latest

# Run gobuster in Docker
docker run --rm -it ghcr.io/oj/gobuster:latest dir -u https://example.com -w /usr/share/wordlists/dirb/common.txt

Read it next to the Dockerfile and the wordlist is simply not there. The image starts from alpine:latest, installs only ca-certificates, creates a user named gobuster, sets USER gobuster, sets WORKDIR to /app, and copies in one statically linked binary as the exec form entrypoint. Nothing in that build writes to /usr/share/wordlists, and the run line mounts no volume, so the path cannot exist inside the container. You have to bind mount a wordlist yourself before the documented command does anything at all. The fixed exec form entrypoint is the second snag: because it is an array rather than a shell, overriding the command to get an interactive shell does not work the usual way, and no override example is given. Both base images are floating tags, so the container you build today is not necessarily the one someone else built last week. For a scan you intend to repeat and record, build from source or install a tagged release instead.

git clone https://github.com/OJ/gobuster.git
cd gobuster
go mod tidy
go build

Status filtering is documented from one side, and a catch-all page defeats it

The dir mode shows the include side only:

# With file extensions
gobuster dir -u https://example.com -w wordlist.txt -x php,html,js,txt

# With custom headers and cookies
gobuster dir -u https://example.com -w wordlist.txt -H "Authorization: Bearer token" -c "session=value"

# Show response length
gobuster dir -u https://example.com -w wordlist.txt -l

# Filter by status codes
gobuster dir -u https://example.com -w wordlist.txt -s 200,301,302

Nothing shown adds a flag for excluding codes, and the No Results Found recipe sends you back to that same switch: verify the target URL is accessible, try different wordlists, check status code filtering with the `-s` flag. That advice presumes too few results, yet the same single lever is all you hold when a server answers 200 for every path, which is exactly what a single page application fallback does. Then every word prints as a hit and the output says nothing about what exists. The only option shown for separating real content from a catch-all is `-l`, response length, which is a manual read rather than a filter. Two other knobs compound this. Extension expansion multiplies requests by the extension count, so the broad example carries seven:

gobuster dir -u https://target.com -w /usr/share/wordlists/dirbuster/directory-list-2.3-medium.txt -x php,html,js,txt,asp,aspx,jsp

Against a rate limited host the Permission Denied recipe is to lower `-t`, add `--delay`, and change the user agent with `-a`. And the dir mode options shown contain no recursion flag, so you cannot tell from the README whether discovered directories are descended into automatically.

Master moved in September 2026, the newest tag is from September 2025

The newest release is v3.8.2, published 2025-09-04, after v3.8.1 on 2025-08-27 and v3.8.0 on 2025-07-17. The master branch last received a push on 2026-10-28, more than a year past that tag. Those two dates behave very differently in practice. `go install github.com/OJ/gobuster/v3@latest` resolves to the newest tag, so a fresh install gives you v3.8.2 and none of the work that has landed on master since. The repository's top level listing, which holds README.md, LICENSE, Dockerfile, Taskfile.yml, go.mod, go.sum, main.go, the seven mode packages, cli/, libgobuster/ and vhs/, carries no changelog, so there is no in repo way to learn what that work changed. The project is not archived and the branch is being written to, and the release cadence inside the tag history is a few weeks apart, but the distance between tag and branch is the thing to plan around rather than the push date itself. Funding runs through OpenCollective, and the README states that donated funds go to charity with a log kept in the repository. The tag is the fixed point you can build a repeatable scan on.

Editorial conclusion

Use gobuster when your target matches one of the seven modes, when you can supply your own wordlist, and when you are willing to treat the README as incomplete. It fits a repeatable dir or dns scan pinned to a known release. It fits badly if you need client certificate support you cannot locate, a protocol it does not implement, or a build whose platform list you have to guess. Before relying on it, check the Go version on your machine against the go 1.25 line in go.mod, confirm which release the install command actually resolved to, and mount a wordlist into the container if you use Docker.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. OJ/gobuster on GitHub
4. README
5. Releases