ZGrab 2.0 Documentation

When using docker compose to manage these containers, the following behavior is observed:

• Port Binding: Containers are bound to specific port ranges based on their SSL configuration:
  • SSL images: Ports 3543x (where x is the instance identifier).
  • Non-SSL images: Ports 4543x.
• Startup Process: Upon container startup, the setup_[type].sh script is executed inside the image. This script:
  • Configures logging.
  • Generates self-signed SSL certificates (only for ssl type images).

To test the ZGrab HTTP module against strictly HTTP/1.1 and HTTP/2.0 compliant web servers, use the provided Docker Compose setup. This environment spins up specialized test containers.

1. Navigate to integration_tests/http/http_version_tests.
2. Build and start the containers:

   docker-compose up --build

3. Verify the servers are running by using curl from a separate terminal:
   • For HTTP/1.1: curl http://localhost:8081/index.html
   • For HTTP/2.0 over TLS: curl -k --http2 https://localhost:8082/index.html

After implementing the scanner, you must register the module so the framework can use it:

1. Add the module to the map in bin/default_modules.go.
2. Add the corresponding import at the top of bin/default_modules.go.

To support schema validation, add a schema file for your module:

1. Create a schema file at zgrab2_schemas/zgrab2/<myproto>.py.
2. Register the new schema in zgrab2_schemas/zgrab2/__init__.py.

To manually validate a ZGrab 2.0 JSON result, you must use the zschema tool. The process involves running the zschema module's main function with the validate command, pointing to the ZGrab 2.0 schema path, and providing the JSON file produced by ZGrab 2.0.

Prerequisites:

• Obtain zschema (e.g., via git clone https://github.com/zmap/zschema).
• Ensure PYTHONPATH includes the path to zschema.

To scan a target using a specific protocol module, use the syntax ./zgrab2 [module].

To see available flags and options for a specific module, append -h after the module name. Note that module-specific options must follow the module name, while application-wide options can be placed anywhere.

To execute scans with multiple protocols in a single run, use the multiple module with a .ini configuration file.

Configuration Rules:

• The first section must be [Application Options] and can include output-file and input-file.
• Subsequent sections must match the names of the ZGrab 2.0 modules you wish to use.
• If you use the same module multiple times, you must provide a unique name key within that section.
• You can use the trigger key in a module section to only run that module if the input line contains a matching TAG.

[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

To run the configuration:

./zgrab2 multiple -c multiple.ini

To create a new protocol module in ZGrab2, use the make scaffold-new-module command. This generates the necessary boilerplate files to begin implementation.

This creates two files:

• modules/<PROTO>/scanner.go: The scanner implementation.
• modules/<PROTO>.go: A thin registration wrapper.

make scaffold-new-module PROTO=myproto

To add a new module schema, you must perform two primary steps: defining the module's data structure and registering it within the ZGrab 2.0 package.

1. Add the module

Create a Python file named after your protocol identifier (e.g., if the identifier is my_protocol, name the file my_protocol.py). This naming convention allows for static schema validation.

Your module must include a SubRecord that extends from zgrab2.base_scan_response. You specifically need to override the result field. Refer to zgrab2/mysql.py for a reference implementation.

2. Register the module

To ensure the module code is executed and the response type is registered, you must import the module in zgrab2/__init__.py.

Note: Using this naming convention means that multiple scans on a single host or scans using custom identifiers will not validate correctly.

You can install h2i using the Go toolchain. Once installed, you can run it by providing a hostname as an argument.

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

The integration_tests/postgres/container directory provides configuration for building custom PostgreSQL Docker images used in integration testing. These images extend the standard PostgreSQL images by:

1. Enabling logging (stored in $PGDATA/pg_log/postgres.log).
2. Enabling SSL (when the image type is set to ssl).

Images are tagged as zgrab_postgres:[version]-[type], where [type] is either ssl or nossl.