Schema details

Overview

The schemas folder contains the zschema definitions for the various zgrab2 modules.

FIXME: It also contains the definitions for the types defined in zcrypto.

The top-level type of all zgrab2 results is the grab_result defined in schemas/zgrab2.py, which is added to the registry as type zgrab2.

Individual modules provide an extension of the base_scan_response, overriding the result field. Then they register the extension with the module name via zgrab2.register_scan_response_type("modulename", modulename_response_type). This adds the "modulename": module_response_type mapping in the grab_result.data field. FIXME: This will obviously only work with the default scan names -- if the user sets a custom scan name, the output will fail to validate. It is unclear how this will be addressed.

To ensure that the response type gets registered, schemas/__init__.py should include a line to import the module.

Result

The mapping from the Go struct (or, in more complex cases, from the custom-marshalled JSON object) to the Python definition is mostly mechanical -- the key names in the SubRecord() correspond to the field's `json:"key_name"`.

Some common types:

• []byte is encoded as a base64 string; this corresponds to the zschema type Binary()
• `zgrab:"debug"` values can be marked with the DebugOnly() modifier provided by zgrab2.py (e.g. "my_debug_string": DebugOnly(String())
• Integer() is deprecated, so it is preferable to use an explicit integer size (e.g. Unsigned32BitInteger())
• Enumerated string values are Enum(values = [ 'value1', 'value2', ... ])
• Both map[string]someType and struct correspond to SubRecord({"key": valueType})
  • For this reason, unconstrained maps are not supported; see Scanner details#scanresult for conventions on how this is encoded or see the example of extensions and unknown_extensions in schemas/zcrypto.py and zcrypto/x509/extensions.go)

Testing

After installing zschema (pip install zschema) you can manually validate scan results by running

python -m zschema validate schemas/__init__.py:zgrab2 /path/to/your/output.json