dorkbot: a command line pipeline from search results to a vulnerability report

From a search query to a JSON report of findings

dorkbot is described as a command line tool to scan Google search results for vulnerabilities, and it is a modular one. The problem it addresses is that vulnerability research over a large, changing set of web targets is tedious in a way that a single scanner cannot fix. You need a way to gather candidate URLs at scale, keep them in a list so the same host is not scanned twice, and run one or more scanning tools against them, and you need the result in a form another script can read. The audience is security researchers and their tooling, which is visible in the choice of formats: SQLite or PostgreSQL for the target store, JSON for the output, and pluggable external scanners rather than a built-in vulnerability engine. The tool is developed under a University of Texas at Austin research licence, which is the kind of detail to check before running it against anything you do not own.

Two module families, indexers and scanners

The architecture is split into two sets of modules, and the split maps onto the pipeline. Indexers are modules that return a list of targets, and they are the part that talks to a search source. Scanners are modules that perform a vulnerability scan against each target, and they wrap the external tools. Targets are stored in a database as they are indexed, and once scanned a standard JSON report is produced containing any vulnerabilities found. Indexing and scanning can be run separately or combined in a single command, with at most one of each. That separation is the useful design decision here. You can collect a large set of targets once, review them, and then scan, and the database becomes the boundary between the two phases. The module flags follow the same split, with an indexer flag and a repeatable argument flag for the indexer, and the matching pair for the scanner.

Quickstart with a Google API credential

The README's quickstart has three steps before the tool does anything. You create a Google API credential through the Developer Console, and you create a Google Custom Search Engine and note the search engine id, in the form of a long number and a short key. Then the install and the two commands:

$ pip3 install dorkbot wapiti3
$ dorkbot -i google_api -o key=your_api_credential_here -o engine=your_engine_id_here -o query="filetype:php inurl:id"
$ dorkbot -s wapiti

The first command runs the google_api indexer with three arguments, the credential, the search engine id and the query, and it fills the database with targets. The second runs the wapiti scanner over the stored targets. Notice that the scanner command has no indexer flags: the targets are already in the database from the previous run, and the two phases do not have to be combined. Wapiti is installed alongside dorkbot in the same command, which is the first sign of how the tool relates to its scanners: dorkbot orchestrates, the scanner does the work.

The target database and the prune mode

The database options are the heart of the tool's behaviour. A database file or URI can be given, and a prune option applies fingerprinting and the blocklist without scanning anything, which is how you clean a target set before committing to a scan. There are options to delete and recreate the tables, to set the number of retries when an operation fails, to specify error strings that should trigger a retry, and to show the total and unscanned target and fingerprint counts. The target side has its own list: listing targets, restricting work to unscanned targets only, listing the sources, adding a URL by hand, deleting one, and flushing all of them. There is also a test mode that fetches the next scannable target but does not mark it scanned, and a reset that clears the scanned status, which together make it possible to rehearse a run before committing to it. Because the same target list is a database table rather than a file list, a scan is resumable.

Fingerprints and blocklists as a scope control

Two mechanisms let you narrow what gets scanned. Fingerprints are generated for all targets on request, and the fingerprint maximum limits how many matches a fingerprint may keep before new matches are deleted, which stops one very common signature from taking over the set. Blocklists work in the same spirit, with an internal list that you can list, add items to, delete from and flush, and an external blocklist file or database that can be supplied as a supplement. The entries accepted are an IP, a host or a regular expression pattern. There are also two delete-on options: delete a target if it matches a blocklist item, and delete a target if an error is encountered while processing it. The second one is worth thinking about before enabling it, because it removes the evidence of a host that could not be scanned, which is exactly the host you might want to look at again. The scoping here is a list you maintain yourself, not a policy the tool enforces.

Finding the scanner: directory, tools folder, then PATH

The scanner modules do not implement scanning themselves, they drive external programs, and the README explains how those programs are found. As needed, dorkbot searches for tools in a defined order: a directory specified through the relevant module option, then the tools directory inside the dorkbot directory, whose default is the current directory, using a subdirectory named after the tool, and finally the user's PATH, which covers a system wide install. The listed scanners are Wapiti, Spectre Scan, and Arachni, which the README marks as deprecated. Database drivers are a separate list, with psycopg preferred and psycopg2 as the alternative, both installable from pip. The pyproject file reflects the same split, with an optional dependency group for PostgreSQL and another for Wapiti, so you install only the pieces your run needs.

A research licence, a config file and no tagged releases

The licence is the first thing to read. The pyproject file names it as a reference to the University of Texas at Austin research licence with a license file, and the README does not summarise the terms, so the LICENSE file is where the actual permissions and obligations are. This is not a generic open source licence, and the difference matters for anyone who plans to run scans beyond a research context. The project requires Python 3.8 or later, is packaged with setuptools, exposes a single console script, and is at version 1.11.0 with a git suffix, which is the sort of version a development tree carries. There are no GitHub releases, so a stable tag to pin against is not available here. The repository is not archived and the last push was on 2026-09-14. Configuration lives in a dorkbot.ini file read from the user configuration directory, honouring XDG_CONFIG_HOME or APPDATA, and the example shows how sections can prepopulate command line flags for the program and for individual modules.

Editorial conclusion

dorkbot fits a security researcher who needs a repeatable pipeline for collecting candidate targets and scanning them with existing tools, and who will manage scope and authorization outside the tool. It does not fit a team that expects a scanner to enforce rules about which hosts may be touched, since the blocklist is a list you populate yourself. Verify first which external scanner your environment can legally and practically run, then confirm that the Google API credential and search engine id you pass to the indexer are the ones you intend, before you let a scan start.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. utiso/dorkbot on GitHub