docs(policies): digest integrity checks (#1304)

Signed-off-by: Miguel Martinez <[email protected]>

Author: migmartri

docs/docs/reference/policies.mdx

@@ -12,7 +12,7 @@ before signing and sending it to Chainloop.
 Currently, policy violations won't block `attestation push` commands, but instead, we chose to include them in the attestation so that they can 
 be used for building server side control gates.
 
-### Policy specification
+## Policy specification
 A policy can be defined in a YAML document, like this:
 
 <CodeBlock language="yaml" title="cyclonedx-licenses.yaml" showLineNumbers>
@@ -32,7 +32,7 @@ spec:
   path: my-script.rego
 ```
 
-### Applying policies to contracts
+## Applying policies to contracts
 When defining a contract, a new `policies` section can be specified. Policies can be applied to any material, but also to the attestation statement as a whole.
 ```yaml
 schemaVersion: v1
@@ -46,8 +46,10 @@ materials:
 policies:
   materials: # policies applied to materials
     - ref: file://cyclonedx-licenses.yaml # (1)
+    # or optionally with the digest appended, see integrity checks below
+    # - ref: file://cyclonedx-licenses.yaml@sha256:5b40425cb7bcba16ac47e3d8a8d3af7288afeeb632096994e741decedd5d38b3
   attestation: # policies applied to the whole attestation
-    - ref: https://github.com/chainloop/chainloop-dev/blob/main/docs/examples/policies/chainloop-commit.yaml # (2)
+    - ref: https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/examples/policies/chainloop-commit.yaml # (2)
 ```
 Here we can see that:
 - (1) materials will be validated against `cyclonedx-licenses.yaml` policy. But, since that policy has a `type` property set to `SBOM_CYCLONEDX_JSON`, only SBOM materials (`sbom` and `another-sbom` in this case) will be evaluated. 
@@ -68,7 +70,7 @@ Finally, note that material policies are evaluated during `chainloop attestation
 
 ### Embedding or referencing policies
 There are two ways to attach a policy to a contract:
-* **By referencing it**, as it can be seen in the examples above. `ref` property admits a local `file://`` (filesystem) or remote reference `https://`. For example:
+* **By referencing it**, as it can be seen in the examples above. `ref` property admits a local `file://` (filesystem) or remote reference `https://`. For example:
   ```yaml
   policies:
     materials: 
@@ -78,7 +80,7 @@ There are two ways to attach a policy to a contract:
   ```yaml
   policies:
     materials:
-      - ref: https://github.com/chainloop/chainloop-dev/blob/main/docs/examples/policies/cyclonedx-licenses.yaml
+      - ref: https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/examples/policies/sbom/cyclonedx-banned-licenses.yaml
   ```
   are both equivalent. The advantage of having remote policies is that they can be easily reused, allowing organizations to create policy catalogs.
 
@@ -127,7 +129,22 @@ policies:
 ```
 (1) This is interpreted as a string, that's why we need to add `to_number` in the policy script
 
-### Rego scripts
+### Integrity Checks
+
+Optionally, you can append the sha256 hash of the policy file content to your policy attachment reference. By doing so, the policy engine will make sure the resolved policy matches the expected hash in the contract reference.
+
+For example
+
+  ```yaml
+  policies:
+    materials: 
+      # append digest to optionally check the integrity of the policy file during evaluation
+      - ref: file://cyclonedx-banned-licenses.yaml@sha256:5b40425cb7bcba16ac47e3d8a8d3af7288afeeb632096994e741decedd5d38b3
+      # It also works for http references
+      - ref: https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/examples/policies/sbom/cyclonedx-banned-licenses.yaml@sha256:5b40425cb7bcba16ac47e3d8a8d3af7288afeeb632096994e741decedd5d38b3
+  ```
+
+## Policy scripts format (REGO)
 Currently, policy scripts are assumed to be written in [Rego language](https://www.openpolicyagent.org/docs/latest/policy-language/#learning-rego). Other policy engines might be implemented in the future.
 The only requirement of the policy is the existence of one or multiple `violations` rules, which evaluate to a **set of violation messages**.
 For example, this policy script: