test
This commit is contained in:
StellaOps Bot
251
docs/modules/policy/recheck-policy.md
Normal file
251
docs/modules/policy/recheck-policy.md
Normal file
@@ -0,0 +1,251 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user