ZGrab 2.0 Framework
Branch: master
Clone or download
justinbastress Merge pull request #186 from zmap/jb/jp-fix
use jp on path (and get/build it if not available)
Latest commit 377e647 Jan 28, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github add GitHub PR template (#37) Jan 18, 2018
cmd/zgrab2 Restore mult.ini Jun 29, 2018
docker-runner Go get module package dependencies. Aug 17, 2018
integration_tests Merge branch 'master' into jb/jp-fix Jan 25, 2019
lib Merge pull request #176 from sdnewhop/master Jan 23, 2019
modules Merge pull request #176 from sdnewhop/master Jan 23, 2019
tools/keys sed name changes Oct 23, 2017
zgrab2_schemas Use Python 3 compatible imports in schemas Jan 7, 2019
.gitattributes Implements postgres zgrab2 module (#30) Jan 15, 2018
.gitignore Add Python gitignore entries (#149) Jul 10, 2018
.travis.yml install May 4, 2018
LICENSE initial commit with readme and license Aug 19, 2016
Makefile Add output unit tests; add output.Process to strip debug; make MySQL … Apr 3, 2018
README.md Update README.md Jun 29, 2018
config.go add bytelimit tests Sep 27, 2018
conn.go Add support for BytesReadLimit parameter in BaseFlags Oct 23, 2018
conn_bytelimit_test.go fix unit tests Dec 18, 2018
conn_timeout_test.go fix unit tests Dec 18, 2018
errors.go port POP3 Mar 15, 2018
input.go Provides a framework for modularized target input and result output f… Jul 5, 2018
input_test.go end Jun 28, 2018
module.go Add support for BytesReadLimit parameter in BaseFlags Oct 23, 2018
monitor.go Add memory and CPU profiling (if ZGRAB_[MEM/CPU]PROFILE is set); add … May 14, 2018
multiple.go gofmt, golint, add docs Oct 4, 2017
output.go Provides a framework for modularized target input and result output f… Jul 5, 2018
output_test.go Add shared FlagsToSet function in output.go (#62) Mar 1, 2018
processing.go Merge pull request #146 from zmap/jb/fixSNI Jan 23, 2019
requirements.txt fix zcrypto_schemas egg name May 4, 2018
scanner.go Scanner modules return the protocol ID, scan returns the protocol in … Mar 12, 2018
setup.py schemas.zgrab2 -> zgrab2_schemas May 4, 2018
status.go add initial work Oct 17, 2018
tls.go Add GetTLSConfigForTarget and GetTLSConnectionForTarget methods (allo… Jul 5, 2018
utility.go add some tighter bounds checking in MSSQL scanner, and if there is an… Oct 1, 2018


ZGrab 2.0

This repo contains the new ZGrab framework, and will eventually replace https://github.com/zmap/zgrab.


You will need to have a valid $GOPATH set up, for more information about $GOPATH, see https://golang.org/doc/code.html.

Once you have a working $GOPATH, run:

$ go get github.com/zmap/zgrab2

This will install zgrab under $GOPATH/src/github.com/zmap/zgrab2

$ cd $GOPATH/src/github.com/zmap/zgrab2
$ make

Single Module Usage

ZGrab2 supports modules. For example, to run the ssh module use

./zgrab2 ssh

Module specific options must be included after the module. Application specific options can be specified at any time.

Input Format

Targets are specified with input files or from stdin, in CSV format. Each input line has three fields:


Each line must specify IP, DOMAIN, or both. If only DOMAIN is provided, scanners perform a DNS hostname lookup to determine the IP address. If both IP and DOMAIN are provided, scanners connect to IP but use DOMAIN in protocol-specific contexts, such as the HTTP HOST header and TLS SNI extension.

If the IP field contains a CIDR block, the framework will expand it to one target for each IP address in the block.

The TAG field is optional and used with the --trigger scanner argument.

Unused fields can be blank, and trailing unused fields can be omitted entirely. For backwards compatibility, the parser allows lines with only one field to contain DOMAIN.

These are examples of valid input lines:
domain.com, domain.com, domain.com, tag, , tag
, domain.com, tag, , tag

Multiple Module Usage

To run a scan with multiple modules, a .ini file must be used with the multiple module. Below is an example .ini file with the corresponding zgrab2 command.


[Application Options]
./zgrab2 multiple -c multiple.ini

Application Options must be the initial section name. Other section names should correspond exactly to the relevant zgrab2 module name. The default name for each module is the command name. If the same module is to be used multiple times then name must be specified and unique.

Multiple module support is particularly powerful when combined with input tags and the --trigger scanner argument. For example, this input contains targets with two different tags:, , tagA, censys.io, tagB

Invoking zgrab2 with the following multiple configuration will perform an SSH grab on the first target above and an HTTP grab on the second target:



Adding New Protocols

Add module to modules/ that satisfies the following interfaces: Scanner, ScanModule, ScanFlags.

The flags struct must embed zgrab2.BaseFlags. In the modules init() function the following must be included.

func init() {
    var newModule NewModule
    _, err := zgrab2.AddCommand("module", "short description", "long description of module", portNumber, &newModule)
    if err != nil {

Output schema

To add a schema for the new module, add a module under schemas, and update schemas/__init__.py to ensure that it is loaded.

See schemas/README.md for details.

Integration tests

To add integration tests for the new module, run integration_tests/new.sh [your_new_protocol_name]. This will add stub shell scripts in integration_tests/your_new_protocol_name; update these as needed. See integration_tests/mysql/* for an example. The only hard requirement is that the test.sh script drops its output in $ZGRAB_OUTPUT/[your-module]/*.json, so that it can be validated against the schema.

How to Run Integration Tests

To run integration tests, you must have Docker installed. Then, you can follow the following steps to run integration tests:

$ go get github.com/jmespath/jp && go build github.com/jmespath/jp
$ pip install --user zschema
$ make integration-test

Running the integration tests will generate quite a bit of debug output. To ensure that tests completed successfully, you can check for a successful exit code after the tests complete:

$ echo $?


ZGrab2.0 is licensed under Apache 2.0 and ISC. For more information, see the LICENSE file.