Adding new modules

Modules are added by calling zgrab2.AddCommand("<module-id>", "<module-display-name>", "<module description>", <module default port>, &theModule), where theModule is an instance of the appropriate Module implementation.

A typical module will consist in the following files:

• modules/<module-id>/scanner.go: Package documentation should describe the protocol, the input flags, what the scan does, and the output format. The body should provide the following:
  • Flags: Implements zgrab2.ScanFlags. Defines the input arguments from the command line.
    • All modules should include zgrab2.BaseFlags
    • Modules that implement TLS should include zgrab2.TLSFlags
  • Module: Implements zgrab2.ScanModule
    • Module.NewFlags() should return a pointer to a new default Flags instance
    • Module.NewScanner() should return a pointer to a new default Scanner instance
  • Scanner: Implements zgrab2.Scanner
    • Scanner.Init() receives the parsed ScanFlags (this can be cast to the module-specific *Flags)
    • Scanner.Scan() is invoked for each host being scanned. If the scan fails to detect the target protocol, it should return nil for the ScanResults. Otherwise, it should return a pointer to a (maybe only partially filled) ScanResults instance.
  • ScanResults: This will be returned by the Scanner.Scan() method and JSON-encoded in the output.
    • Ideally, this should provide both a MarshalJSON() and an UnmarshalJSON() method (if the defaults are not sufficient)
    • This should be query-friendly
      • No unconstrained map[string]strings
      • No cycles
    • The schemas/<module-id>.py should
  • RegisterModule(): A function that calls zgrab2.AddModule() on a module instance.
• modules/<module-id>.go: Calls <module>.RegisterModule() in its init() function.
• schemas/<module-id>.py: Defines the format of the output.
  • You must update schemas/__init__.py to pull in the new module.
• integration_tests/<module-id>/setup.sh: A script to do any necessary setup for the integration test (e.g. build docker images / launch containers)
  • Should be idempotent
  • Should exit with nonzero code on failure
• integration_tests/<module-id>/cleanup.sh: Make a best effort to undo anything done in setup.sh
  • Should be idempotent
  • Should only fail on a critical error
• integration_tests/<module-id>/test.sh: Run integration tests for the module
  • Can assume that setup.sh has already been successfully run
  • Can assume that the zgrab2 docker container has been built and is up-to-date
  • Typical usage: CONTAINER_NAME=zgrab_<module-id> $ZGRAB_ROOT/docker-runner/docker-run.sh <module-id>

Running integration_tests/new.sh <module-id> will create skeletons for all of these files with most of the boilerplate filled in.