git.stella-ops.org/docs/modules/triage/proof-bundle-spec.md

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