test

2025-12-22 09:56:20 +02:00
parent 00bc4f79dd
commit dfaa2079aa
7 changed files with 1574 additions and 12 deletions
--- a/docs/modules/triage/exploit-path-inbox.md
+++ b/docs/modules/triage/exploit-path-inbox.md
@@ -0,0 +1,176 @@
+# Exploit Path Inbox Architecture
+
+## Overview
+
+The Exploit Path Inbox provides a triage workflow that groups vulnerabilities by their complete attack chain rather than individual CVEs. This enables analysts to assess and remediate entire exploit paths at once, improving efficiency and ensuring comprehensive coverage.
+
+## Key Concepts
+
+### Exploit Path
+
+An **Exploit Path** represents the complete chain from an entry point to a vulnerable symbol:
+
+```
+Artifact → Package → Vulnerable Symbol → Entry Point
+```
+
+For example:
+```
+sha256:abc... → pkg:npm/lodash@4.17.19 → _.template() → /api/render
+```
+
+### Path ID Generation
+
+Path IDs are deterministic hashes ensuring stable references:
+
+```
+PathId = SHA256(artifactDigest | packagePurl | symbolName | entryPointName)
+```
+
+This allows:
+- Consistent tracking across scans
+- Stable exception targeting
+- Reproducible audits
+
+### Grouping Logic
+
+Findings are grouped into exploit paths based on:
+
+1. **Reachability Graph**: If reachability data exists, group by actual call paths
+2. **Fallback**: If no reachability, group by package only
+
+## Data Model
+
+### ExploitPath
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `pathId` | string | Stable deterministic identifier |
+| `artifactDigest` | string | Container image digest |
+| `package` | PackageRef | Package containing vulnerability |
+| `symbol` | VulnerableSymbol | Vulnerable function/method |
+| `entryPoint` | EntryPoint | Entry point exposing the path |
+| `cveIds` | string[] | All CVEs affecting this path |
+| `reachability` | ReachabilityStatus | Reachability lattice state |
+| `riskScore` | PathRiskScore | Aggregated risk metrics |
+| `evidence` | PathEvidence | Supporting evidence |
+| `activeExceptions` | ExceptionRef[] | Active suppressions |
+| `isQuiet` | boolean | Whether path is suppressed |
+
+### ReachabilityStatus
+
+| State | Description |
+|-------|-------------|
+| `Unknown` | No reachability analysis performed |
+| `StaticallyReachable` | Static analysis found a path |
+| `RuntimeConfirmed` | Runtime observation confirmed reachability |
+| `Unreachable` | Confirmed not reachable |
+| `Contested` | Conflicting evidence |
+
+## API Endpoints
+
+### GET /triage/inbox
+
+Returns exploit paths for a given scope.
+
+**Query Parameters:**
+- `artifactDigest` (string): Filter by artifact
+- `environment` (string): Filter by environment
+- `quiet` (boolean): Filter by suppression status
+- `minCvss` (number): Minimum CVSS score
+- `reachability` (string): Filter by reachability status
+- `offset` (number): Pagination offset
+- `limit` (number): Page size (default 50)
+
+**Response:**
+```json
+{
+  "paths": [...],
+  "totalCount": 42,
+  "quietCount": 12,
+  "activeCount": 30,
+  "offset": 0,
+  "limit": 50
+}
+```
+
+### GET /triage/paths/{pathId}
+
+Returns detailed exploit path information.
+
+### GET /triage/paths/{pathId}/proof
+
+Returns proof bundle (see proof-bundle-spec.md).
+
+## UI Components
+
+### Three-Pane Layout
+
+1. **Left Pane (Path List)**
+   - Exploit paths sorted by risk
+   - Quiet/Active toggle
+   - Search by CVE, package, symbol
+   - Risk score badges
+
+2. **Center Pane (Path Detail)**
+   - CVE list with scores
+   - Package and symbol info
+   - Entry point context
+   - Active exceptions
+   - "Create Exception" button
+
+3. **Right Pane (Proof Viewer)**
+   - Reach subgraph visualization
+   - Symbol map with source links
+   - VEX claims with trust badges
+   - "Export Proof" button
+
+## Integration Points
+
+### Exception System
+
+Exceptions can target exploit paths via `pathId`:
+```yaml
+scope:
+  pathId: "path:abc123..."
+```
+
+This suppresses all CVEs in the path at once.
+
+### Build Gates
+
+Build gates can query by exploit path reachability:
+```yaml
+gates:
+  - name: block-reachable-critical
+    condition: reachability == "RuntimeConfirmed" && severity == "Critical"
+    action: block
+```
+
+### VEX Generation
+
+VEX statements can reference exploit paths for context:
+```json
+{
+  "vulnerability": "CVE-2024-1234",
+  "product": "sha256:abc...",
+  "status": "not_affected",
+  "justification": "vulnerable_code_not_in_execute_path",
+  "context": {
+    "exploitPathId": "path:abc123..."
+  }
+}
+```
+
+## Best Practices
+
+1. **Triage by Path**: Address entire exploit paths, not individual CVEs
+2. **Use Reachability**: Prioritize runtime-confirmed paths
+3. **Document Evidence**: Attach proof bundles to exceptions
+4. **Regular Review**: Re-evaluate paths when reachability changes
+
+## Related Documentation
+
+- [Proof Bundle Specification](./proof-bundle-spec.md)
+- [Recheck Policy](../policy/recheck-policy.md)
+- [Evidence Hooks](../policy/evidence-hooks.md)