From f0af6211ad5929d17bccf55f65d6e2f1449dc5cc Mon Sep 17 00:00:00 2001 From: fullsend-code <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Fri, 19 Jun 2026 10:41:47 +0000 Subject: [PATCH] docs(#1753): add default values section to CVE package docs Add a "Default values" section to the CVE package documentation that lists each rule data key with its actual default value from rule_data.rego. This makes it easy for users to see the defaults without reading the source code. Also relabel the existing example YAML block as "Example rule data (non-default)" and fix a typo in the example intro ("if" -> "of") to clearly distinguish customization examples from actual defaults. Changes: - policy/release/cve/cve.rego: Updated METADATA annotations to include a defaults section with a link to rule_data.rego, and relabeled the existing example block. - antora/docs/*: Regenerated via make generate-docs. Note: make test could not run in the sandbox (unshare not permitted). Tests were run directly via ec opa test and all 17 CVE tests passed. Closes #1753 --- .../ROOT/pages/packages/release_cve.adoc | 43 +++++++++++++++---- .../modules/ROOT/pages/release_policy.adoc | 31 ++++++++++++- policy/release/cve/cve.rego | 43 ++++++++++++++++++- 3 files changed, 105 insertions(+), 12 deletions(-) diff --git a/antora/docs/modules/ROOT/pages/packages/release_cve.adoc b/antora/docs/modules/ROOT/pages/packages/release_cve.adoc index 4c542b77c..09bb0d350 100644 --- a/antora/docs/modules/ROOT/pages/packages/release_cve.adoc +++ b/antora/docs/modules/ROOT/pages/packages/release_cve.adoc @@ -4,9 +4,36 @@ This package is responsible for verifying a CVE scan was performed during the bu The behaviour of the rules in this package is influenced by rule data. Firstly the rules can be configured to emit violations or warnings based on the availability of the vulnerability fix: patched -- if there is a remediation available, e.g. new version with a fix, or unpatched -- if there is, currently, no remidiation available. Secondly per severity: critical, high, medium, low or unknown choice can be made of the rule outcome: failure or warning. And lastly, per severity, choice can be made of how many leeway days are allowed before a vulnerability causing a failure will be reported as a warning instead. -In the following example if rule data configuration, failures will be reported for critical and high patched vulnerabilities, for critical unpatched vulnerabilities only, warnings will be reported for medium and low patched, and for high and medium unpatched vulnerabilities. For critical and high patched vulnerabilities a leeway of 10 days is allowed. +== Default values -.Example rule data +The following are the default values for each rule data key. These defaults are defined in https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/lib/rule_data/rule_data.rego[rule_data.rego] and are used when no custom rule data is provided. + +.Default rule data +[source,yaml] +---- +restrict_cve_security_levels: + - critical + - high + +warn_cve_security_levels: [] +restrict_unpatched_cve_security_levels: [] +warn_unpatched_cve_security_levels: + - critical + - high + +cve_leeway: + critical: 0 + high: 0 + medium: 0 + low: 0 + unknown: 0 +---- + +== Customization example + +In the following example of rule data configuration, failures will be reported for critical and high patched vulnerabilities, for critical unpatched vulnerabilities only, warnings will be reported for medium and low patched, and for high and medium unpatched vulnerabilities. For critical and high patched vulnerabilities a leeway of 10 days is allowed. + +.Example rule data (non-default) [source,yaml] ---- restrict_cve_security_levels: @@ -41,7 +68,7 @@ The SLSA Provenance attestation for the image is inspected to ensure CVEs that h * Rule type: [rule-type-indicator failure]#FAILURE# * FAILURE message: `Found %q vulnerability of %s security level` * Code: `cve.cve_blockers` -* https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/release/cve/cve.rego#L115[Source, window="_blank"] +* https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/release/cve/cve.rego#L154[Source, window="_blank"] [#cve__unpatched_cve_blockers] === link:#cve__unpatched_cve_blockers[Blocking unpatched CVE check] @@ -53,7 +80,7 @@ The SLSA Provenance attestation for the image is inspected to ensure CVEs that d * Rule type: [rule-type-indicator failure]#FAILURE# * FAILURE message: `Found %q unpatched vulnerability of %s security level` * Code: `cve.unpatched_cve_blockers` -* https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/release/cve/cve.rego#L149[Source, window="_blank"] +* https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/release/cve/cve.rego#L188[Source, window="_blank"] [#cve__cve_results_found] === link:#cve__cve_results_found[CVE scan results found] @@ -65,7 +92,7 @@ Confirm that CVE scan task results (Clair or TPA) are present in the SLSA Proven * Rule type: [rule-type-indicator failure]#FAILURE# * FAILURE message: `CVE scan results were not found` * Code: `cve.cve_results_found` -* https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/release/cve/cve.rego#L185[Source, window="_blank"] +* https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/release/cve/cve.rego#L224[Source, window="_blank"] [#cve__cve_warnings] === link:#cve__cve_warnings[Non-blocking CVE check] @@ -77,7 +104,7 @@ The SLSA Provenance attestation for the image is inspected to ensure CVEs that h * Rule type: [rule-type-indicator warning]#WARNING# * WARNING message: `Found %q non-blocking vulnerability of %s security level` * Code: `cve.cve_warnings` -* https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/release/cve/cve.rego#L60[Source, window="_blank"] +* https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/release/cve/cve.rego#L99[Source, window="_blank"] [#cve__unpatched_cve_warnings] === link:#cve__unpatched_cve_warnings[Non-blocking unpatched CVE check] @@ -89,7 +116,7 @@ The SLSA Provenance attestation for the image is inspected to ensure CVEs that d * Rule type: [rule-type-indicator warning]#WARNING# * WARNING message: `Found %q non-blocking unpatched vulnerability of %s security level` * Code: `cve.unpatched_cve_warnings` -* https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/release/cve/cve.rego#L87[Source, window="_blank"] +* https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/release/cve/cve.rego#L126[Source, window="_blank"] [#cve__rule_data_provided] === link:#cve__rule_data_provided[Rule data provided] @@ -101,4 +128,4 @@ Confirm the expected rule data keys have been provided in the expected format. T * Rule type: [rule-type-indicator failure]#FAILURE# * FAILURE message: `%s` * Code: `cve.rule_data_provided` -* https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/release/cve/cve.rego#L215[Source, window="_blank"] +* https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/release/cve/cve.rego#L254[Source, window="_blank"] diff --git a/antora/docs/modules/ROOT/pages/release_policy.adoc b/antora/docs/modules/ROOT/pages/release_policy.adoc index c0b1814e1..13983c96c 100644 --- a/antora/docs/modules/ROOT/pages/release_policy.adoc +++ b/antora/docs/modules/ROOT/pages/release_policy.adoc @@ -376,9 +376,36 @@ a| This package is responsible for verifying a CVE scan was performed during the The behaviour of the rules in this package is influenced by rule data. Firstly the rules can be configured to emit violations or warnings based on the availability of the vulnerability fix: patched -- if there is a remediation available, e.g. new version with a fix, or unpatched -- if there is, currently, no remidiation available. Secondly per severity: critical, high, medium, low or unknown choice can be made of the rule outcome: failure or warning. And lastly, per severity, choice can be made of how many leeway days are allowed before a vulnerability causing a failure will be reported as a warning instead. -In the following example if rule data configuration, failures will be reported for critical and high patched vulnerabilities, for critical unpatched vulnerabilities only, warnings will be reported for medium and low patched, and for high and medium unpatched vulnerabilities. For critical and high patched vulnerabilities a leeway of 10 days is allowed. +== Default values -.Example rule data +The following are the default values for each rule data key. These defaults are defined in https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/lib/rule_data/rule_data.rego[rule_data.rego] and are used when no custom rule data is provided. + +.Default rule data +[source,yaml] +---- +restrict_cve_security_levels: + - critical + - high + +warn_cve_security_levels: [] +restrict_unpatched_cve_security_levels: [] +warn_unpatched_cve_security_levels: + - critical + - high + +cve_leeway: + critical: 0 + high: 0 + medium: 0 + low: 0 + unknown: 0 +---- + +== Customization example + +In the following example of rule data configuration, failures will be reported for critical and high patched vulnerabilities, for critical unpatched vulnerabilities only, warnings will be reported for medium and low patched, and for high and medium unpatched vulnerabilities. For critical and high patched vulnerabilities a leeway of 10 days is allowed. + +.Example rule data (non-default) [source,yaml] ---- restrict_cve_security_levels: diff --git a/policy/release/cve/cve.rego b/policy/release/cve/cve.rego index f7516d5b4..c1459ad0f 100644 --- a/policy/release/cve/cve.rego +++ b/policy/release/cve/cve.rego @@ -18,14 +18,53 @@ # as a warning instead. # # -# In the following example if rule data configuration, failures will be +# == Default values +# +# +# The following are the default values for each rule data key. These defaults +# are defined in +# https://github.com/conforma/policy/blob/{page-origin-refhash}/policy/lib/rule_data/rule_data.rego[rule_data.rego] +# and are used when no custom rule data is provided. +# +# +# .Default rule data +# +# [source,yaml] +# +# ---- +# +# restrict_cve_security_levels: +# - critical +# - high +# +# warn_cve_security_levels: [] +# +# restrict_unpatched_cve_security_levels: [] +# +# warn_unpatched_cve_security_levels: +# - critical +# - high +# +# cve_leeway: +# critical: 0 +# high: 0 +# medium: 0 +# low: 0 +# unknown: 0 +# ---- +# +# +# == Customization example +# +# +# In the following example of rule data configuration, failures will be # reported for critical and high patched vulnerabilities, for critical # unpatched vulnerabilities only, warnings will be reported for medium and low # patched, and for high and medium unpatched vulnerabilities. For critical and # high patched vulnerabilities a leeway of 10 days is allowed. # # -# .Example rule data +# .Example rule data (non-default) # # [source,yaml] #