Files

StellaOps Bot dfaa2079aa test

2025-12-22 09:56:20 +02:00

4.8 KiB

Raw Blame History

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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:

{
  "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

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:

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:

Query all active exceptions
Export proof bundle for each
Generate PDF report with embedded evidence

Dispute Resolution

When VEX claims conflict:

View all claims in proof bundle
Compare trust scores and timestamps
Document resolution rationale

Schema Validation

Proof bundles must validate against JSON Schema:

$id: https://stellaops.io/schemas/proof-bundle/v1

4.8 KiB Raw Blame History