252 lines
5.5 KiB
Markdown
252 lines
5.5 KiB
Markdown
# 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
|
|
```
|
|
|
|
## 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)
|