Recheck Policy Reference

Overview

A Recheck Policy defines conditions that trigger automatic re-evaluation of an exception. When conditions are met, the exception may be flagged for review, require re-approval, or be automatically revoked.

Policy Model

recheckPolicy:
  policyId: "policy-critical-cves"
  name: "Critical CVE Recheck"
  conditions:
    - type: EPSSAbove
      threshold: 0.5
      action: RequireReapproval
    - type: ReachGraphChange
      action: Block
    - type: KEVFlagged
      action: Block
    - type: ExpiryWithin
      threshold: 7  # days
      action: Warn
  defaultAction: Warn
  isActive: true

Condition Types

EPSSAbove

Triggers when EPSS score exceeds threshold.

Example:

- type: EPSSAbove
  threshold: 0.5
  action: RequireReapproval

CVSSAbove

Triggers when CVSS score exceeds threshold.

ReachGraphChange

Triggers when reachability graph changes (new paths discovered).

Use case: Exception was based on “unreachable” status; new analysis shows reachability.

UnknownsAbove

Triggers when unknown budget exceeds threshold.

KEVFlagged

Triggers when CVE is added to CISA KEV catalog.

Best practice: Always use Block action for KEV additions.

VEXStatusChange

Triggers when VEX status changes (e.g., NotAffected → Affected).

NewCVEInPackage

Triggers when new CVE is discovered in the same package.

ExpiryWithin

Triggers when exception nears expiry.

PackageVersionChange

Triggers when package version changes in artifact.

Actions

Warn

Log warning but allow exception to remain active.

• Appears in audit log
• Visible in exception details
• Does not block deployment

RequireReapproval

Move exception back to “pending” status requiring re-approval.

• Notifies original approvers
• Exception inactive until re-approved
• Evidence may need updating

Revoke

Automatically revoke the exception.

• Exception becomes inactive immediately
• Audit log entry created
• Notification sent

Block

Fail build/deployment pipeline.

• CI/CD gate returns failure
• Requires manual intervention
• Most severe action

Environment Scoping

Conditions can be scoped to specific environments:

- type: EPSSAbove
  threshold: 0.3
  environmentScope:
    - prod
    - staging
  action: Block
- type: EPSSAbove
  threshold: 0.7
  environmentScope:
    - dev
  action: Warn

Evaluation Flow

1. Scan triggered
2. Get active exceptions for artifact
3. For each exception with recheck policy:
   a. Evaluate each condition
   b. Check environment scope
   c. Record triggered conditions
4. Determine highest-priority action
5. Apply action (warn/reapproval/revoke/block)
6. Update exception with recheck result

Persistence

• Recheck policy definitions are stored in policy.recheck_policies with conditions as JSONB.
• Exceptions reference a policy through policy.exceptions.recheck_policy_id.
• The latest evaluation snapshot is stored in policy.exceptions.last_recheck_result and policy.exceptions.last_recheck_at.

Build Gate Integration

Recheck policies integrate with build gates:

# In CI/CD pipeline
- name: check-exceptions
  uses: stellaops/exception-gate@v1
  with:
    artifact: ${{ env.IMAGE_DIGEST }}
    environment: production
    fail-on: block

Best Practices

1. Start with Warn: Begin with warning actions, escalate based on data
2. KEV = Block: Always block on KEV additions
3. Environment Tiers: Stricter policies for production
4. Regular Review: Review triggered conditions monthly
5. Document Rationale: Explain threshold choices

Example Policies

High-Security Policy

recheckPolicy:
  policyId: "high-security"
  name: "High Security Recheck"
  conditions:
    - type: EPSSAbove
      threshold: 0.3
      action: Block
    - type: CVSSAbove
      threshold: 7.0
      action: RequireReapproval
    - type: KEVFlagged
      action: Block
    - type: ReachGraphChange
      action: Block
    - type: VEXStatusChange
      action: RequireReapproval
  defaultAction: Warn

Standard Policy

recheckPolicy:
  policyId: "standard"
  name: "Standard Recheck"
  conditions:
    - type: EPSSAbove
      threshold: 0.7
      action: RequireReapproval
    - type: KEVFlagged
      action: Block
    - type: ExpiryWithin
      threshold: 14
      action: Warn
  defaultAction: Warn

Related Documentation

• Evidence Hooks
• Exception API
• Build Gates