git.stella-ops.org/docs/modules/policy/recheck-policy.md

# 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

```yaml
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.

| Parameter | Type | Description |
|-----------|------|-------------|
| threshold | decimal | EPSS score threshold (0.0-1.0) |
| action | RecheckAction | Action when triggered |

**Example:**
```yaml
- type: EPSSAbove
  threshold: 0.5
  action: RequireReapproval
```

### CVSSAbove

Triggers when CVSS score exceeds threshold.

| Parameter | Type | Description |
|-----------|------|-------------|
| threshold | decimal | CVSS score threshold (0.0-10.0) |
| action | RecheckAction | Action when triggered |

### ReachGraphChange

Triggers when reachability graph changes (new paths discovered).

| Parameter | Type | Description |
|-----------|------|-------------|
| action | RecheckAction | Action when triggered |

**Use case:** Exception was based on "unreachable" status; new analysis shows reachability.

### UnknownsAbove

Triggers when unknown budget exceeds threshold.

| Parameter | Type | Description |
|-----------|------|-------------|
| threshold | integer | Maximum allowed unknowns |
| action | RecheckAction | Action when triggered |

### KEVFlagged

Triggers when CVE is added to CISA KEV catalog.

| Parameter | Type | Description |
|-----------|------|-------------|
| action | RecheckAction | Action when triggered |

**Best practice:** Always use `Block` action for KEV additions.

### VEXStatusChange

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

| Parameter | Type | Description |
|-----------|------|-------------|
| action | RecheckAction | Action when triggered |

### NewCVEInPackage

Triggers when new CVE is discovered in the same package.

| Parameter | Type | Description |
|-----------|------|-------------|
| action | RecheckAction | Action when triggered |

### ExpiryWithin

Triggers when exception nears expiry.

| Parameter | Type | Description |
|-----------|------|-------------|
| threshold | integer | Days before expiry |
| action | RecheckAction | Action when triggered |

### PackageVersionChange

Triggers when package version changes in artifact.

| Parameter | Type | Description |
|-----------|------|-------------|
| action | RecheckAction | Action when triggered |

## 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:

```yaml
- 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:

```yaml
# 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

```yaml
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

```yaml
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](./evidence-hooks.md)
- [Exception API](../../api/exceptions.md)
- [Build Gates](../ci/recipes.md)