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)
--- a/docs/modules/triage/proof-bundle-spec.md
+++ b/docs/modules/triage/proof-bundle-spec.md
@@ -0,0 +1,235 @@
+# Proof Bundle Specification
+
+## Overview
+
+A **Proof Bundle** aggregates all evidence supporting an exploit path assessment. It provides a complete, self-contained package for audit, compliance, and decision-making.
+
+## Bundle Contents
+
+### 1. Reach Subgraph
+
+The reachability subgraph shows the call path from entry point to vulnerable symbol.
+
+```json
+{
+  "nodes": [
+    {
+      "id": "node-001",
+      "label": "handleRequest",
+      "type": "entryPoint",
+      "depth": 0,
+      "isVulnerable": false,
+      "isEntryPoint": true
+    },
+    {
+      "id": "node-002",
+      "label": "renderTemplate",
+      "type": "function",
+      "depth": 1,
+      "isVulnerable": false,
+      "isEntryPoint": false
+    },
+    {
+      "id": "node-003",
+      "label": "_.template",
+      "type": "vulnerableSymbol",
+      "depth": 2,
+      "isVulnerable": true,
+      "isEntryPoint": false
+    }
+  ],
+  "edges": [
+    {
+      "sourceId": "node-001",
+      "targetId": "node-002",
+      "label": "calls",
+      "weight": 0.95
+    },
+    {
+      "sourceId": "node-002",
+      "targetId": "node-003",
+      "label": "calls",
+      "weight": 0.90
+    }
+  ],
+  "entryPointId": "node-001",
+  "vulnerableSymbolId": "node-003",
+  "totalNodes": 3,
+  "totalEdges": 2
+}
+```
+
+### 2. Symbol Map
+
+Maps symbol identifiers to source code locations.
+
+```json
+{
+  "symbols": [
+    {
+      "id": "node-001",
+      "fullyQualifiedName": "src.api.handleRequest",
+      "sourceFile": "src/api/handler.js",
+      "lineNumber": 42,
+      "language": "javascript",
+      "signature": "function handleRequest(req, res)"
+    },
+    {
+      "id": "node-003",
+      "fullyQualifiedName": "lodash.template",
+      "sourceFile": "node_modules/lodash/template.js",
+      "lineNumber": 156,
+      "language": "javascript",
+      "signature": "function template(string, options)"
+    }
+  ],
+  "sourceFiles": [
+    "src/api/handler.js",
+    "node_modules/lodash/template.js"
+  ]
+}
+```
+
+### 3. VEX Claims
+
+VEX statements from various sources with trust scores.
+
+```json
+{
+  "vexClaims": [
+    {
+      "cveId": "CVE-2024-1234",
+      "status": "not_affected",
+      "justification": "vulnerable_code_not_in_execute_path",
+      "source": "vendor:lodash",
+      "trustScore": 0.95,
+      "timestamp": "2024-12-22T10:00:00Z",
+      "signatureValid": true
+    },
+    {
+      "cveId": "CVE-2024-1234",
+      "status": "affected",
+      "justification": null,
+      "source": "nvd",
+      "trustScore": 0.80,
+      "timestamp": "2024-12-20T08:00:00Z",
+      "signatureValid": false
+    }
+  ]
+}
+```
+
+### 4. Trust Scores
+
+Aggregated confidence metrics.
+
+```json
+{
+  "trustScores": {
+    "reachabilityConfidence": 0.90,
+    "vexConfidence": 0.85,
+    "overallConfidence": 0.875,
+    "evidenceCount": 5
+  }
+}
+```
+
+## API Endpoint
+
+### GET /triage/paths/{pathId}/proof
+
+Returns the complete proof bundle.
+
+**Response:**
+```json
+{
+  "pathId": "path:abc123...",
+  "generatedAt": "2024-12-22T12:00:00Z",
+  "reachSubgraph": { ... },
+  "symbolMap": { ... },
+  "vexClaims": [ ... ],
+  "trustScores": { ... },
+  "bundleDigest": "sha256:def456..."
+}
+```
+
+### GET /triage/paths/{pathId}/proof/export
+
+Returns proof bundle as downloadable JSON file.
+
+## Bundle Integrity
+
+Each bundle includes a digest for integrity verification:
+
+```
+bundleDigest = SHA256(canonical_json(bundle_without_digest))
+```
+
+This allows:
+- Tamper detection
+- Audit trail verification
+- Reproducible exports
+
+## Visualization
+
+### Reach Graph Rendering
+
+Use Cytoscape.js or similar for interactive visualization:
+- Nodes colored by type (entry point, intermediate, vulnerable)
+- Edge width indicates confidence weight
+- Collapsible for large graphs
+
+### Symbol Navigation
+
+Click-through from symbols to source code:
+- IDE integration (VS Code, JetBrains)
+- GitHub/GitLab links
+- Line number highlighting
+
+### VEX Claim Comparison
+
+Side-by-side view of conflicting VEX statements:
+- Trust score comparison
+- Timestamp ordering
+- Signature verification badges
+
+## Use Cases
+
+### Exception Creation
+
+When creating an exception, attach proof bundle:
+```yaml
+exception:
+  pathId: "path:abc123..."
+  proofBundleDigest: "sha256:def456..."
+  evidence:
+    - type: proof-bundle
+      reference: "/triage/paths/path:abc123.../proof"
+```
+
+### Compliance Audit
+
+Export proof bundles for compliance documentation:
+1. Query all active exceptions
+2. Export proof bundle for each
+3. Generate PDF report with embedded evidence
+
+### Dispute Resolution
+
+When VEX claims conflict:
+1. View all claims in proof bundle
+2. Compare trust scores and timestamps
+3. Document resolution rationale
+
+## Schema Validation
+
+Proof bundles must validate against JSON Schema:
+```
+$id: https://stellaops.io/schemas/proof-bundle/v1
+```
+
+## Related Documentation
+
+- [Exploit Path Inbox](./exploit-path-inbox.md)
+- [VEX Trust Scoring](../excititor/scoring.md)
+- [Reachability Analysis](../scanner/operations/entrypoint.md)