test
This commit is contained in:
StellaOps Bot
250
docs/modules/snapshot/merge-preview.md
Normal file
250
docs/modules/snapshot/merge-preview.md
Normal file
@@ -0,0 +1,250 @@
|
||||
# Policy Merge Preview
|
||||
|
||||
## Overview
|
||||
|
||||
The **Policy Merge Preview** shows how VEX statements from different sources combine using lattice logic. This visualization helps analysts understand:
|
||||
|
||||
1. What each source contributes
|
||||
2. How conflicts are resolved
|
||||
3. What evidence is missing
|
||||
4. The final merged status
|
||||
|
||||
## Merge Semantics
|
||||
|
||||
StellaOps uses a three-layer merge model:
|
||||
|
||||
```
|
||||
vendor ⊕ distro ⊕ internal = final
|
||||
```
|
||||
|
||||
Where ⊕ represents the lattice join operation.
|
||||
|
||||
### Layer Hierarchy
|
||||
|
||||
| Layer | Description | Typical Trust |
|
||||
|-------|-------------|---------------|
|
||||
| **Vendor** | Software vendor's VEX statements | 0.95-1.0 |
|
||||
| **Distro** | Distribution maintainer's assessments | 0.85-0.95 |
|
||||
| **Internal** | Organization's own assessments | 0.70-0.90 |
|
||||
|
||||
### Lattice Operations
|
||||
|
||||
Using K4 (Kleene's 4-valued logic):
|
||||
|
||||
| Status | Lattice Position |
|
||||
|--------|-----------------|
|
||||
| Affected | Top (Both) |
|
||||
| UnderInvestigation | Unknown (Neither) |
|
||||
| Fixed | True |
|
||||
| NotAffected | False |
|
||||
|
||||
Join table (⊕):
|
||||
```
|
||||
| Affected | Under... | Fixed | NotAffected
|
||||
---------+----------+----------+-------+------------
|
||||
Affected | A | A | A | A
|
||||
Under... | A | U | U | U
|
||||
Fixed | A | U | F | F
|
||||
NotAff | A | U | F | N
|
||||
```
|
||||
|
||||
## API Endpoint
|
||||
|
||||
### GET /policy/merge-preview/{cveId}
|
||||
|
||||
**Parameters:**
|
||||
- `cveId`: CVE identifier
|
||||
- `artifact`: Artifact digest (query param)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"cveId": "CVE-2024-1234",
|
||||
"artifactDigest": "sha256:abc...",
|
||||
"contributions": [
|
||||
{
|
||||
"layer": "vendor",
|
||||
"sources": ["lodash-security"],
|
||||
"status": "NotAffected",
|
||||
"trustScore": 0.95,
|
||||
"statements": [...],
|
||||
"mergeTrace": {
|
||||
"explanation": "Vendor states not affected due to version"
|
||||
}
|
||||
},
|
||||
{
|
||||
"layer": "distro",
|
||||
"sources": ["redhat-csaf"],
|
||||
"status": "Affected",
|
||||
"trustScore": 0.90,
|
||||
"statements": [...],
|
||||
"mergeTrace": {
|
||||
"explanation": "Distro states affected without context"
|
||||
}
|
||||
},
|
||||
{
|
||||
"layer": "internal",
|
||||
"sources": [],
|
||||
"status": null,
|
||||
"trustScore": 0,
|
||||
"statements": [],
|
||||
"mergeTrace": null
|
||||
}
|
||||
],
|
||||
"finalStatus": "NotAffected",
|
||||
"finalConfidence": 0.925,
|
||||
"missingEvidence": [
|
||||
{
|
||||
"type": "internal-assessment",
|
||||
"description": "Add internal security assessment",
|
||||
"priority": "medium"
|
||||
}
|
||||
],
|
||||
"latticeType": "K4",
|
||||
"generatedAt": "2024-12-22T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
When sources disagree, resolution follows:
|
||||
|
||||
1. **Trust Weight**: Higher trust wins
|
||||
2. **Lattice Position**: If trust equal, higher lattice position wins
|
||||
3. **Freshness**: If still tied, more recent statement wins
|
||||
4. **Tie**: First statement wins
|
||||
|
||||
### Resolution Trace
|
||||
|
||||
Each merge includes explanation:
|
||||
```json
|
||||
{
|
||||
"leftSource": "vendor:lodash",
|
||||
"rightSource": "distro:redhat",
|
||||
"leftStatus": "NotAffected",
|
||||
"rightStatus": "Affected",
|
||||
"leftTrust": 0.95,
|
||||
"rightTrust": 0.90,
|
||||
"resultStatus": "NotAffected",
|
||||
"explanation": "'vendor:lodash' has higher trust weight than 'distro:redhat'"
|
||||
}
|
||||
```
|
||||
|
||||
## UI Components
|
||||
|
||||
### Layer Cards
|
||||
|
||||
Each layer shows:
|
||||
- Source names
|
||||
- Current status badge
|
||||
- Trust score bar
|
||||
- Statement count
|
||||
|
||||
### Merge Flow Diagram
|
||||
|
||||
Visual representation:
|
||||
```
|
||||
┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐
|
||||
│ Vendor │ ──⊕─│ Distro │ ──⊕─│ Internal │ ──=─│ Final │
|
||||
│ NotAff. │ │ Affected│ │ — │ │ NotAff. │
|
||||
│ (0.95) │ │ (0.90) │ │ │ │ (0.925) │
|
||||
└─────────┘ └─────────┘ └──────────┘ └─────────┘
|
||||
```
|
||||
|
||||
### Missing Evidence CTA
|
||||
|
||||
Prominent call-to-action for missing evidence:
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ ⚠ Improve Confidence │
|
||||
│ │
|
||||
│ [+] Add internal security assessment │
|
||||
│ Increases confidence by ~5% │
|
||||
│ │
|
||||
│ [+] Add reachability analysis │
|
||||
│ Determines if code is called │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Merge Traces (Expandable)
|
||||
|
||||
Detailed explanation of each merge:
|
||||
```
|
||||
▼ Merge Details
|
||||
|
||||
Vendor layer:
|
||||
Sources: lodash-security
|
||||
Status: NotAffected (trust: 95%)
|
||||
|
||||
Distro layer:
|
||||
Sources: redhat-csaf
|
||||
Status: Affected (trust: 90%)
|
||||
Merge: 'lodash-security' has higher trust weight
|
||||
|
||||
Internal layer:
|
||||
No statements
|
||||
|
||||
Final: NotAffected (confidence: 92.5%)
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Trust Weights
|
||||
|
||||
Configure in `trust.yaml`:
|
||||
```yaml
|
||||
sources:
|
||||
vendor: 1.0
|
||||
distro: 0.9
|
||||
nvd: 0.8
|
||||
internal: 0.85
|
||||
community: 0.5
|
||||
unknown: 0.3
|
||||
```
|
||||
|
||||
### Lattice Type
|
||||
|
||||
Configure lattice in `policy.yaml`:
|
||||
```yaml
|
||||
lattice:
|
||||
type: K4 # or Boolean, 8-state
|
||||
joinStrategy: trust-weighted
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Understanding Disagreement
|
||||
|
||||
When vendor says "not affected" but NVD says "affected":
|
||||
- View merge preview
|
||||
- See trust scores
|
||||
- Understand why vendor wins
|
||||
- Decide if internal assessment needed
|
||||
|
||||
### 2. Adding Internal Context
|
||||
|
||||
When external sources lack context:
|
||||
- View missing evidence
|
||||
- Click "Add evidence"
|
||||
- Submit internal VEX statement
|
||||
- See confidence increase
|
||||
|
||||
### 3. Audit Documentation
|
||||
|
||||
For compliance:
|
||||
- Export merge preview
|
||||
- Include in audit report
|
||||
- Document decision rationale
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Review Conflicts**: When layers disagree, investigate why
|
||||
2. **Add Internal Context**: Your reachability data often resolves conflicts
|
||||
3. **Trust Calibration**: Adjust trust weights based on source accuracy
|
||||
4. **Document Decisions**: Use merge preview in exception justifications
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [VEX Trust Scoring](../excititor/scoring.md)
|
||||
- [Lattice Configuration](../policy/implementation_plan.md)
|
||||
- [REPLAY.yaml Specification](./replay-yaml.md)
|
||||
Reference in New Issue
Block a user