Welcome to the Python SDK for writing plugins for the Hipcheck analysis tool.

User / Plugin Developer Information

The guide for developing plugins with this SDK can be found here.

The API documentation for this package can be found here.

A dummy example plugin using the SDK can be found here.

Python SDK Developer Information

You must have uv installed. Installation instructions can be found here.

Running unit tests

From sdk/python, run

uv run pytest ./tests

Regenerating auto-generated code

The contents of src/hipcheck_sdk/gen is generated Python code from multiple sources. Some files are generated by the grpcio Python library using the Hipcheck protobuf protocol spec. An additional file contains Python classes automatically derived from the Hipcheck Target object schema. To regenerate these files, you can run the following:

uv run scripts/update-gen.py

Testing example plugin listening on port

From sdk/python, run

uv run tests/example-plugin/main.py --port <PORT>`.

Or from hipcheck repository root, run

uv run --project sdk/python sdk/python/tests/example-plugin/main.py --port <PORT>

Testing example plugin in Hipcheck analysis

From the Hipcheck repository root, use a policy with the following plugins entry:

    plugin "mitre/example" version="0.0.0" manifest="sdk/python/tests/example-plugin/local-plugin.kdl"

Currently, this will get through configuration and receive the query from Hipcheck core, but the plugin will appear as an error in the final report because it is not currently written to accept Target objects.

Building the HTML

From docs/, run the following:

uv run make html # Build the html in the build/ directory
cp -r build/html <DESTINATION_DIR>