How to handle Sentinel policy metadata

Sentinel
1

Hi community,

I am using HashiCorp Sentinel as policy-as-code framework along with Terraform Enterprise.

I recently faced the challenge to add metadata to the policies, for example to automatically generated an overview of all policies along with additional information, such as internal policy references and a unique ID, that can be used by external teams or auditors that are “not yet familiar with looking at code”.

Interesting metadata per policy would be: unique ID, description, references to policies/documents (e.g. internal and external standards), etc.

My first attempt was to add additional fields to the sentinel.hcl file, as this is already a single location where all policies are listed:

policy "POL001-enforce-storage-accounts-min-tls" {
    enforcement_level = "hard-mandatory"
    id = "POL001"
    name = "Enforce HTTPS on Storage Accounts"
    description = "Ensure that `azurerm_storage_account` resources have the `enable_https_traffic_only` flag set to true."
    references {
        standard = "CIS Microsoft Azure Foundations Benchmark 1.1.0"
        control = "3.1 Ensure that 'Secure transfer required' is set to 'Enabled'"
}

Unfortunately, unknown/additional fields are not allowed within a policy block and result in an exception.
Potential other locations would be within a policy.sentinel file directly (as comment at the top?) or completely independent of the policy definition - but both are ugly solutions and cause parsing or maintenance overhead from my perspective.

So my question or feature request would be:

  1. Did anyone else every tried to work with / add metadata to Sentinel policy definitions? How did you solve it?
  2. Is it possible to add a “metadata” block or something similar to a policy block definition to allow additional custom field that are not interpreted but can be parsed for own purposes?

Thanks and a good start into the week!

2

@ddetering thanks for reaching out!

I think there are a couple of ways of achieving what you are after. As you have already called out you can add a comment at the top of the policy which describes the intention of the entire policy, or you could add a comment above each rule that describes the logic for each rule evaluation.

You can also provide messaging and contextual information by using the map expression and return the unique identifier for the policy etc. I have written an example in the playground that you may find useful.

If you would like this to be a bit more dynamic and centralized, you could call an external HTTP endpoint that describes the rule, intentions, references etc. but one of the challenges you will face is truncation. There are a limited number of characters that we support in the trace and if you exceed the limitation it will result in a .... You’ll notice in the example above that certain fields are being truncated.

We could add support for metadata within the policy block definition, but again truncation would most likely occur when this data is referenced and returned within the trace. I personally feel like the map expression is the best solution for communicating why something has failed.

Let me know what you think of the example I have shared and where there is further room for improvement. In the meantime I will have a think about how the Sentinel team can provide the kind of functionality that you are looking for.

1 Like
3

@hcrhall many thanks for your fast answer and for providing the great example! Much appreciated.

I’ll experiment with the solution of the example you provided and will get back if further ideas come to my mind.

Thanks again!