Vulnerability Policies

Policy reference for governing dependency & image vulnerabilities (Trivy-based). Use these policies to block net‑new critical risk while monitoring existing backlog.

Overview

Vulnerability policies evaluate scanner findings, filter via rule predicates, classify change categories (new, changed, removed, existing), execute actions (info|warn|block), and emit outputs (Markdown / HTML / JSON). They are the primary guardrail against introducing new CVEs or unresolved high‑severity issues.

Canonical change category semantics: see Diff-Based Analysis. Allowed fields & operators: see Policy System.

Style & naming conventions (actions formatting info | warn | block, canonical change order) are defined in the Style & Naming Guide.

AI Governance Rationale

AI‑assisted or bulk refactors can unintentionally introduce vulnerable packages. Diff‑aware vulnerability policies block only net‑new CRITICAL/HIGH issues while allowing legacy remediation to proceed incrementally, sustaining velocity without silent regression.

Policy Object Schema

(Non‑validation domain schema — full structure in Policy System.)

{
  "name": "crit-vulns-block",
  "disabled": false,
  "actions": {"new": "block", "existing": "warn"},
  "rules": [ {"field": "Severity", "type": "eq", "value": "CRITICAL"} ],
  "outputs": [
    {"format": "markdown", "template": "table", "destination": "git:pr", "fields": ["VulnerabilityID","PkgName","Severity","FixedVersion"], "changes": ["new"], "collapse": true},
    {"format": "json", "destination": "file:/results/crit-vulns.json", "changes": ["new","changed","removed"]}
  ]
}

Rules array = OR logic. Absence of rules means no filtering (all findings). Keep separate policies per severity / rollout phase.

Allowed Fields

Canonical list: Policy System → Allowed Record Fields. Commonly used:

• VulnerabilityID, PkgName, Severity, FixedVersion, Relationship (requires dependency tree)

Rule Examples

Severity Filtering

{"rules": [
  {"field": "Severity", "type": "eq", "value": "CRITICAL"},
  {"field": "Severity", "type": "eq", "value": "HIGH"}
]}

Package Name Patterns

{"rules": [
  {"field": "PkgName", "type": "contains", "value": "crypto"},
  {"field": "PkgName", "type": "hasPrefix", "value": "@internal/"},
  {"field": "VulnerabilityID", "type": "regex", "value": "^CVE-2025-.*"}
]}

Fix Availability (Only Block When Fix Exists)

{"rules": [
  {"field": "Severity", "type": "eq", "value": "CRITICAL"},
  {"field": "FixedVersion", "type": "ne", "value": ""}
]}

Note: Previous docs used an exists operator on FixedVersion. Support is limited to validation/filesystem contexts. Use inequality to an empty value (non-empty indicates a fix).

Direct Dependencies Only

{"rules": [
  {"field": "Relationship", "type": "eq", "value": "direct"},
  {"field": "Severity", "type": "eq", "value": "CRITICAL"}
]}

(Requires global.dependency_tree=true.)

Phased Rollout

See Progressive Enforcement for escalation strategy (supersedes prior inline tables).

Output Strategies

Goal	Output Pattern
Reviewer clarity	Markdown table with limited fields (VulnerabilityID, PkgName, Severity, FixedVersion) to PR
Machine ingestion	JSON file with broader fields + change categories including removed
Backlog tracking	Issue destination with existing only
Unified comment	combined:true across multiple vulnerability policies

Combined JSON groups must share format; result is a single concatenated array (see Combining & Grouping).

Exceptions (Explicit Allowlisting)

Avoid embedding large negative match sets. Prefer a narrow rule that excludes a single accepted risk CVE via inequality:

"rules": [
  {"field":"Severity","type":"eq","value":"CRITICAL"},
  {"field":"VulnerabilityID","type":"ne","value":"CVE-2025-ACCEPTED"}
]

Document rationale in output comment when temporarily excluding risk.

Common Mistakes & Fixes

Problem	Cause	Fix
Rules ignored	Used legacy nested object: { "rules": { "severity": [...] }}	Replace with array of rule objects
Block not firing	Only existing findings present	Ensure diff mounts (/main+/branch) with CI_EVENT=pr & action on new
Everything new	Missing /main mount or wrong CI_EVENT	Provide baseline volume & set CI_EVENT=pr
FixedVersion not shown	Omitted from fields list	Add FixedVersion to output fields
Relationship filter no effect	dependency_tree disabled	Set global.dependency_tree=true
Combined JSON error	Mixed json + markdown in combined group	Keep formats uniform per destination

Best Practices

Goal	Recommendation
Minimize noise	Limit PR outputs to new (and changed if needed)
Justify blocking	Include FixedVersion for remediation path
Rapid rollout	Separate policies per severity to escalate independently
Explainability	Use concise title & comment fields
Automation	Export at least one JSON artifact
Maintainability	Favor multiple focused policies over monoliths

Related Topics

• Policy System
• Diff-Based Analysis
• Combining & Grouping
• Output Formats
• Configuration Overview
• Main Config Reference
• Progressive Enforcement

---

Next: configure complementary domains — see License Policies.