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/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)