ZGrab2

https://github.com/zmap/zgrab2
Admin
ZGrab2 is a fast, modular application-layer network scanner designed for completing large...
Tokens:15,598
Snippets:123
Trust Score:9.4
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install h2i with go install and run

Source: https://github.com/zmap/zgrab2/blob/master/lib/http2/h2i/README.md

Install h2i using `go install` and then run it with a hostname. The command `h2i <host>` connects to the given host.

```bash
$ go install golang.org/x/net/http2/h2i@latest
$ h2i <host>
```

--------------------------------

### Get module-specific help with -h

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Displays detailed command-line usage and options for a specific module, including application-wide options and usage examples. Replace [module] with the module name.

```bash
./zgrab2 [module] -h
```

--------------------------------

### Install and run integration tests

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Prepare the environment by installing Python dependencies and executing the integration test suite.

```shell
# Install Python dependencies
sudo apt update
sudo apt install -y python3 jp python3-pip
python3 -m venv venv
source venv/bin/activate
# Install Python dependencies
pip install zschema
pip install -r requirements.txt
make integration-test-clean; make integration-test
```

--------------------------------

### Start Docker containers

Source: https://github.com/zmap/zgrab2/blob/master/integration_tests/http/http_version_tests/README.md

Run from the integration_tests/http/http_version_tests directory to build and start the test web servers.

```shell
docker-compose up --build
```

--------------------------------

### Scan method documentation example

Source: https://github.com/zmap/zgrab2/wiki/Scanner-details

Shows the expected format for documenting the Scan method, including step-by-step description and detection points. The example includes a function signature with an error in the return type (interface{} error) as written in the source.

```go
// Scan probes for the presence of XYZ on the target.
//  1. Connect to the configured TCP port on target (default XYZ)
//  2. Send packet A, receive response
//    - On failure, fail detection with SCAN_PROTOCOL_ERROR
//  3. Copy field X from response into field X of results
//  4. Send packet B, receive response
//   - On failure, return SCAN_PROTOCOL_ERROR with the partial results
// ...
// 10. Copy field Z from response into field Z of results
// 11. Return SCAN_SUCCESS with the results.
func (scanner *Scanner) Scan(target ScanTarget) (ScanStatus, interface{} error) {
```

--------------------------------

### Install ZGrab2 System-wide

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Command to install the compiled binary to the system path and verify availability.

```shell
make install; zgrab2 --help
```

--------------------------------

### SMB Client Session Establishment

Source: https://github.com/zmap/zgrab2/blob/master/lib/smb/README.md

Creates an SMB session with the given options, checks if signing is required)Skip, and verifies authentication. The example uses the smb.NewSession function with debug mode disabled. It logs the signing requirement and login status, and exits on error.

```go
package main

import (
	"log"

	"github.com/stacktitan/smb/smb"
)

func main() {

	host := "172.16.248.192"
	options := smb.Options{
		Host:        host,
		Port:        445,
		User:        "alice",
		Domain:      "corp",
		Workstation: "",
		Password:    "Password123!",
	}
	debug := false
	session, err := smb.NewSession(options, debug)
	if err != nil {
		log.Fatalln("[!]", err)
	}
	defer session.Close()

	if session.IsSigningRequired {
		log.Println("[-] Signing is required")
	} else {
		log.Println("[+] Signing is NOT required")
	}

	if session.IsAuthenticated {
		log.Println("[+] Login successful")
	} else {
		log.Println("[-] Login failed")
	}

	if err != nil {
		log.Fatalln("[!]", err)
	}
}

```

--------------------------------

### Example invocation with http module

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Runs the http module on a domain from stdin, with max-redirects and endpoint options. Demonstrates piping input to zgrab2.

```shell
echo "en.wikipedia.org" | ./zgrab2 http --max-redirects=1 --endpoint="/wiki/New_York_City"
```

--------------------------------

### Input targets with tags

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Example input file format containing targets associated with specific tags.

```text
141.212.113.199, , tagA
216.239.38.21, censys.io, tagB
```

--------------------------------

### Get TLSConnection and perform handshake with zgrab2.TLSFlags

Source: https://github.com/zmap/zgrab2/wiki/TLSFlags

Use TLSFlags to obtain a TLSConnection, perform the handshake, and store the TLS log in the result's 'tls' field. The example assumes flags.UseTLS is set and that the connection is opened with BaseFlags.

```go
conn, err := scanTarget.Open(&flags.BaseFlags)
if flags.UseTLS {
  tlsConnection, err := flags.TLSFlags.GetTLSConnection(conn)
  err := tlsConnection.Handshake()
  result.tls = tlsConnection.GetLog()
  conn = tlsConnection
}

```

--------------------------------

### Run the SSH module

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Executes the ssh module with default options. Use this to start a scan with the ssh module.

```shell
./zgrab2 ssh
```

--------------------------------

### NTP scan output example

Source: https://github.com/zmap/zgrab2/blob/master/README.md

The JSON output format returned by ZGrab2 after a successful scan, followed by the scan summary.

```sh
{"ip":"23.143.196.199","domain":"pool.ntp.org","data":{"ntp":{"status":"success","protocol":"ntp","port":123,"result":{"version":3,"time":"2025-11-07T00:58:45.13740072Z"},"timestamp":"2025-11-06T16:58:45-08:00"}}}
00h:00m:00s; Scan Complete; 1 targets scanned; 33.01 targets/sec; 100.0% success rate
```

--------------------------------

### Valid input line examples

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Shows valid CSV input lines. Fields can be blank, trailing fields omitted, and CIDR blocks are expanded. If only DOMAIN is given, DNS lookup is performed.

```text
10.0.0.1
domain.com
10.0.0.1, domain.com
10.0.0.1, domain.com, tag
10.0.0.1, domain.com, tag, 1234
10.0.0.1, , tag
10.0.0.1, , , 5678
, domain.com, tag
192.168.0.0/24, , tag
```

--------------------------------

### Validate zgrab2 output with zschema

Source: https://github.com/zmap/zgrab2/blob/master/zgrab2_schemas/README.md

Run zgrab2 to produce output.json, then use the zschema validator with the zgrab2 schema to validate the JSON file. Requires zschema installed and PYTHONPATH set to its location.

```bash
echo 127.0.0.1 | ./cmd/zgrab2/zgrab2 mysql > output.json
PYTHONPATH=/path/to/zschema python3 -m zschema validate zgrab2 output.json --path . --module zgrab2_schemas.zgrab2
```

--------------------------------

### ScanResults struct with JSON and zgrab tags

Source: https://github.com/zmap/zgrab2/wiki/Scanner-details

Example of a ScanResult type with exported fields, JSON tags, and a zgrab debug tag. Shows omitempty usage and pointer for optional int.

```go
type ScanResults struct {
  // MyFieldID is a string that can safely be omitted if it is empty.
  MyFieldID string   `json:"my_field_id,omitempty"`

  // MyBoolean is a boolean value, and we want to include it in the response whether the value is true or false.
  // This is a debug value that should only be returned when verbose output is enabled.
  MyBoolean bool     `json:"my_boolean" zgrab:"debug"`

  // MyOptionalInt is an optional int, where the value 0 is meaningful and distinct from "not present".
  MyOptionalInt *int `json:"my_optional_int,omitempty"`
}
```

--------------------------------

### Clone and Build ZGrab2 from Source

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Commands to download the repository, compile the binary, and verify the HTTP module help message.

```shell
git clone https://github.com/zmap/zgrab2.git
cd zgrab2
make
./zgrab2 http --help # to see the http module's help message
```

--------------------------------

### Implement Scanner.Init for TCP modules

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Configure the scanner by casting flags, setting base flags, and defining the DialerGroupConfig for TCP-based protocols.

```go
func (s *Scanner) Init(flags zgrab2.ScanFlags) error {
    f, _ := flags.(*Flags)
    s.config = f
    s.SetBaseFlags(&f.BaseFlags)
    s.DialerGroupConfig = &zgrab2.DialerGroupConfig{
        TransportAgnosticDialerProtocol: zgrab2.TransportTCP,
        BaseFlags:                       &f.BaseFlags,
    }
    return nil
}
```

--------------------------------

### Add GOPATH to System PATH

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Add the Go binary directory to your shell configuration to resolve 'command not found' errors.

```shell
export PATH=$PATH:$GOPATH/bin
```

--------------------------------

### Package Documentation Template

Source: https://github.com/zmap/zgrab2/wiki/Scanner-details

Template for the package documentation comment that should precede the package declaration in scanner.go. It includes placeholders for default port, flag descriptions, TLS support, scan behavior, and output description.

```go
// Package myprotocol provides the zgrab2 scanner module for myprotocol.
// Default Port: <your default port> (TCP)
// 
// The --some-flag changes the scan/output in this way
// The --other-flag changes the scan/output in this way
// ...<more flag descriptions>...
// Supports the standard TLS flags <unless it doesn't>
//
// The scan does X, Y and Z, unless P then it does Q.
// ...<more scan description>...
//
// The output is (description of the output).
// ...<more output description>...
package myprotocol
```

--------------------------------

### Build ZGrab2

Source: https://github.com/zmap/zgrab2/blob/master/integration_tests/http/http_version_tests/README.md

Run from the main zgrab2 directory to compile the zgrab2 binary before running the tests.

```shell
make
```

--------------------------------

### Run ZGrab2 with Configuration File via Docker

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Execute complex scans by mounting a local configuration file into the Docker container.

```shell
docker run --rm -i -v /path/to/your/config.ini:/config.ini ghcr.io/zmap/zgrab2 multiple -c /config.ini
```

--------------------------------

### Test servers with curl

Source: https://github.com/zmap/zgrab2/blob/master/integration_tests/http/http_version_tests/README.md

Run from a separate terminal to verify the HTTP/1.1 and HTTP/2.0 servers are responding. The second command uses -k to ignore TLS certificate verification and --http2 to use HTTP/2.

```shell
curl http://localhost:8081/index.html   
curl -k --http2 https://localhost:8082/index.html   
```

--------------------------------

### HTTP/1.1 test command

Source: https://github.com/zmap/zgrab2/blob/master/integration_tests/http/http_version_tests/README.md

Run from the main zgrab2 directory after building. Sends 'localhost' as input to the zgrab2 http module on port 8081. Expected status code 200 and protocol HTTP/1.1.

```shell
echo "localhost" | ./zgrab2 http --port=8081
```

--------------------------------

### Configure multiple modules with multiple.ini

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Defines an application configuration with multiple HTTP and SSH modules, followed by the command to execute the scan.

```ini
[Application Options]
output-file="output.txt"
input-file="input.txt"
[http]
name="http80"
port=80
endpoint="/"
[http]
name="http8080"
port=8080
endpoint="/"
[ssh]
port=22
```

```shell
./zgrab2 multiple -c multiple.ini
```

--------------------------------

### Run ZGrab2 via Docker

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Execute a basic HTTP scan against a single domain using the official Docker image.

```shell
echo 'example.com' | docker run --rm -i ghcr.io/zmap/zgrab2 http
```

--------------------------------

### h2i demo session

Source: https://github.com/zmap/zgrab2/blob/master/lib/http2/h2i/README.md

Shows the h2i usage message, connecting to google.com, negotiating protocol h2-14, sending a PING, sending HTTP/1.1 headers, and receiving frames. The session ends with a GOAWAY frame and EOF.

```bash
$ h2i
Usage: h2i <hostname>
  
  -insecure
        Whether to skip TLS cert validation
  -nextproto string
        Comma-separated list of NPN/ALPN protocol names to negotiate. (default "h2,h2-14")

$ h2i google.com
Connecting to google.com:443 ...
Connected to 74.125.224.41:443
Negotiated protocol "h2-14"
[FrameHeader SETTINGS len=18]
  [MAX_CONCURRENT_STREAMS = 100]
  [INITIAL_WINDOW_SIZE = 1048576]
  [MAX_FRAME_SIZE = 16384]
[FrameHeader WINDOW_UPDATE len=4]
  Window-Increment = 983041
  
h2i> PING h2iSayHI
[FrameHeader PING flags=ACK len=8]
  Data = "h2iSayHI"
h2i> headers
(as HTTP/1.1)> GET / HTTP/1.1
(as HTTP/1.1)> Host: ip.appspot.com
(as HTTP/1.1)> User-Agent: h2i/brad-n-blake
(as HTTP/1.1)>  
Opening Stream-ID 1:
 :authority = ip.appspot.com
 :method = GET
 :path = /
 :scheme = https
 user-agent = h2i/brad-n-blake
[FrameHeader HEADERS flags=END_HEADERS stream=1 len=77]
  :status = "200"
  alternate-protocol = "443:quic,p=1"
  content-length = "15"
  content-type = "text/html"
  date = "Fri, 01 May 2015 23:06:56 GMT"
  server = "Google Frontend"
[FrameHeader DATA flags=END_STREAM stream=1 len=15]
  "173.164.155.78\n"
[FrameHeader PING len=8]
  Data = "\x00\x00\x00\x00\x00\x00\x00\x00"
h2i> ping  
[FrameHeader PING flags=ACK len=8]  
  Data = "h2i_ping"  
h2i> ping  
[FrameHeader PING flags=ACK len=8]
  Data = "h2i_ping"
h2i> ping
[FrameHeader GOAWAY len=22]
  Last-Stream-ID = 1; Error-Code = PROTOCOL_ERROR (1)

ReadFrame: EOF
```

--------------------------------

### Scaffold a new ZGrab2 module

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Use the make scaffold-new-module command to generate the necessary boilerplate files for a new protocol module.

```shell
make scaffold-new-module PROTO=myproto
```

--------------------------------

### Configure triggered scans with tags

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Configuration for the multiple module that uses triggers to map specific modules to tagged input targets.

```ini
[ssh]
trigger="tagA"
name="ssh22"
port=22

[http]
trigger="tagB"
name="http80"
port=80
```

--------------------------------

### HTTP/2.0 over TLS test command

Source: https://github.com/zmap/zgrab2/blob/master/integration_tests/http/http_version_tests/README.md

Run from the main zgrab2 directory after building. Sends 'localhost' as input to the zgrab2 http module on port 8082 with HTTPS enabled. Expected status code 200 and protocol HTTP/2.0.

```shell
echo "localhost" | ./zgrab2 http --port=8082 --use-https
```

--------------------------------

### Run zgrab2 against a container with docker-run.sh

Source: https://github.com/zmap/zgrab2/wiki/Integration-test-details

Command to run the latest zgrab2 code from its docker container, linking to the target container via the CONTAINER_NAME environment variable. Output is redirected to ../../zgrab-output/output.json.

```bash
CONTAINER_NAME=$TARGET_CONTAINER_NAME $ZGRAB_ROOT/docker-runner/docker-run.sh modulename --flag1 --flag2 > ../../zgrab-output/output.json
```

--------------------------------

### Input format: four fields

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Specifies the CSV input format for targets. Each line has up to four fields: IP, DOMAIN, TAG, PORT. IP and DOMAIN are optional but at least one must be provided.

```text
IP, DOMAIN, TAG, PORT
```

--------------------------------

### Verify integration test success

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Check the exit code of the previous command to confirm that integration tests completed successfully.

```shell
echo $?
0
```

--------------------------------

### Scan a target with the NTP module

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Pipe a hostname or IP address into the zgrab2 ntp command to perform a scan.

```shell
echo "pool.ntp.org" | zgrab2 ntp
```

--------------------------------

### Run specific module integration tests

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Use the TEST_MODULES environment variable to run integration tests for one or more specific modules.

```shell
make integration-test-clean; TEST_MODULES="http" make integration-test
make integration-test-clean; TEST_MODULES="http ssh" make integration-test
```

--------------------------------

### Specify DNS resolvers with zgrab2 http

Source: https://github.com/zmap/zgrab2/wiki/Performance-Tuning

Use the --dns-resolvers flag to override the default DNS servers (from /etc/resolv.conf) with public resolvers like 1.1.1.1 and 8.8.8.8 for better performance under high query volumes.

```shell
echo "example.com" | zgrab2 http --dns-resolvers="1.1.1.1,8.8.8.8"
```

--------------------------------

### Reload Shell Configuration

Source: https://github.com/zmap/zgrab2/blob/master/README.md

Command to apply changes made to your shell configuration file.

```shell
source ~/.bashrc  # or source ~/.zshrc
```
Tokens:
Raw