Hipcheck 3.10.0 Release

Written by Andrew Lilley Brinker

Posted on January 31, 2025

The Hipcheck team has released version 3.10.0. This release features two improvements to the "query protocol" that defines how plugins in Hipcheck communicate, a new env macro for policy files, and a start on human-readable explanations when a package doesn't pass policy.

For the unfamiliar, Hipcheck is a tool to help open source software users decide what dependencies to use by applying their own policies with maximum configurability.

Hipcheck

Query Protocol Improvements

This release features two major improvements to the "query protocol." This is the protocol that defines how plugins communicate with hc (what we often call "Hipcheck Core").

This communication works as follows:

  1. hc starts each plugin as a subprocess, and the plugin starts listening for gRPC calls on a specified port, acting as a gRPC server with hc as its client.
  2. After some setup, hc initiates a bidirectional streaming RPC call, over which query messages will be sent.

The rules for how hc and plugins encapsulate queries to send and receive messages form the "query protocol."

In RFD #9 and RFD #10, we defined two modifications to this protocol, batched queries and submit chunking:

  • Batched Queries: Previously, each query message could contain at most one complete query, either a single query that fit in one messages, or a large query split across multiple messages. However, sometimes a query's request or response data are small, in which case paying the overhead of a full gRPC messages every time can start to become a burden. To resolve this, we introduced support for "batched queries," so a single message can contain more than one query at a time.
  • Submit Chunking: While we've always supported splitting large query responses across multiple messages, we'd missed including that same support for chunking when sending a query request. This causes failures on some large repositories, like the Linux repository, where the large number of commits would cause some queries requests based on commit hashes to exceed the gRPC message size limit. This is now fixed, and query requests can be chunked in the same way responses can be.

This fix involved backwards-compatible changes to the protobuf definitions for the gRPC protocol, along with updates to hc and to our Rust SDK, which is used by all of our first-party plugins.

#env Macro for Policy Files

Policy files are how users specify what analyses to run on packages they want to assess, and how those analyses should be configured.

Sometimes in a policy file it's convenient to incorporate data pulled from an environment variable, to make it easier to modify the policy applied in a more dynamic fashion than updating the file by hand.

We've now added support for a new #env macro in policy files, which reads the specified environment variable and injects the result of that environment variable at runtime into the policy file.

Use of the new macro looks like:

analysis "some/plugin" {
    api-token #env("SOME_VARIABLE")
}

English-Language Policy Explanations

One of our ongoing goals for Hipcheck is to make it easy to use for everyone. We want this to be a tool that empowers regular users of open source software. As part of that, previously when an analysis failed we could print the policy expression specified for that analysis, and an explanation of what that analysis is trying to validate as provided by the plugin creator.

With this new version, we can now also in some cases produce a human-readable explanation of the policy expression that failed, helping to make it clearer why a package hasn't passed a specific policy.

This an early stage change, and one we expect to continue iterating on it subsequent versions.

Other Improvements

  • We introduced a new Exec.kdl file, as an initial experiment in letting users tune the internal performance characteristics of Hipcheck.
  • We fixed a bug with the #rel macro in policy files, causing it to produce invalid paths on Windows.
  • We modified how hc setup works, to fill out a starter set of policy files without needing to download a bundle from the network.

Rust SDK

As described in "Query Protocol Improvements" above, we've introduced support for query batching and submit chunking, both of which involved changes to the Rust SDK. The submit chunking change is entirely internal and does not introduce new APIs. The query batching support is now exposed via two new APIs on hipcheck_sdk::PluginEngine:

  • PluginEngine::batch: This returns a QueryBuilder, letting you build up a set of queries to include in a batch incrementally.
  • PluginEngine::batch_query: Expects a Vec of query keys, enabling you to make many queries together at once.

We also added more documentation to the crate and cleaned up some organization to hopefully be clearer / easier to navigate.

Plugins

All plugins have been updated to the latest version of the Rust SDK, meaning they now support submit chunking and perform query batching where appropriate.

The mitre/git plugin now has a configurable commit cache size, as it performs some internal data caching.

Finally, we transitioned all remaining configuration files expected by individual plugins from TOML to KDL. If you're still using the old TOML files they should continue to work, through we recommend starting with the KDL files that are now distributed with the default starter policy from hc setup.

Conclusion

That's it for Hipcheck 3.10.0! As always, we greatly appreciate the hard work of everyone involved in the project who contributed to this release. I especially want to thank Julian Lanson for continuing to lead development and for shepherding this release to completion.

Thanks as well to CISA for their continued support of our work on Hipcheck.

The following team members contributed to this release: