Explanation API and Replay Semantics

The Explanation API turns a vulnerability finding into a plain-language, evidence-grounded explanation that an operator can trust and an auditor can reproduce. Every explanation is anchored to verifiable evidence, wrapped in a signed attestation, and replayable bit-for-bit.

Audience: platform operators, security analysts, and integrators wiring Stella Ops AI explanations into review workflows or release gates.

This guide covers the explanation endpoints, the attestation format, and the replay semantics that guarantee deterministic reproduction.

Overview

The Explanation API provides evidence-anchored explanations answering:

• What is this vulnerability?
• Why does it matter in this context?
• Evidence: What supports exploitability?
• Counterfactual: What would change the verdict?

All explanations are anchored to verifiable evidence nodes (SBOM, reachability, runtime, VEX, patches).

Explanation Types

API Endpoints

Generate Explanation

POST /api/v1/advisory-ai/explain
Content-Type: application/json

{
  "findingId": "finding-abc123",
  "artifactDigest": "sha256:abcdef...",
  "scope": "service",
  "scopeId": "payment-service",
  "explanationType": "Full",
  "vulnerabilityId": "CVE-2024-1234",
  "componentPurl": "pkg:npm/lodash@4.17.20",
  "plainLanguage": true,
  "maxLength": 2000
}

Response:

{
  "explanationId": "expl-20251226-001",
  "content": "## What is CVE-2024-1234?\n\nCVE-2024-1234 is a critical remote code execution vulnerability...[1]\n\n## Why It Matters\n\nYour payment-service uses lodash@4.17.20 which is affected...[2]\n\n## Evidence\n\n- Reachability: The vulnerable `merge()` function is called from `/api/checkout`...[3]\n- Runtime: No WAF protection detected for this endpoint...[4]\n\n## What Would Change the Verdict\n\nThe verdict would change to 'not affected' if:\n- A VEX statement confirms non-exploitability...[5]\n- The function call is removed from the code path...[6]",
  "summary": {
    "line1": "Critical RCE in lodash affecting payment-service",
    "line2": "Reachable via /api/checkout with no WAF protection",
    "line3": "Upgrade to lodash@4.17.21 or add VEX exception"
  },
  "citations": [
    {
      "claimText": "CVE-2024-1234 is a critical remote code execution vulnerability",
      "evidenceId": "nvd:CVE-2024-1234",
      "evidenceType": "advisory",
      "verified": true,
      "evidenceExcerpt": "CVSS: 9.8 CRITICAL - Improper input validation in lodash merge..."
    },
    {
      "claimText": "payment-service uses lodash@4.17.20",
      "evidenceId": "sbom:payment-service:lodash@4.17.20",
      "evidenceType": "sbom",
      "verified": true,
      "evidenceExcerpt": "Component: lodash, Version: 4.17.20, Location: node_modules/lodash"
    },
    {
      "claimText": "vulnerable merge() function is called from /api/checkout",
      "evidenceId": "reach:payment-service:lodash.merge:/api/checkout",
      "evidenceType": "reachability",
      "verified": true,
      "evidenceExcerpt": "Call path: checkout.js:42 -> utils.js:15 -> lodash.merge()"
    }
  ],
  "confidenceScore": 0.92,
  "citationRate": 0.85,
  "authority": "EvidenceBacked",
  "evidenceRefs": [
    "nvd:CVE-2024-1234",
    "sbom:payment-service:lodash@4.17.20",
    "reach:payment-service:lodash.merge:/api/checkout",
    "runtime:payment-service:waf:none"
  ],
  "modelId": "claude-sonnet-4-20250514",
  "promptTemplateVersion": "v2.1.0",
  "inputHashes": [
    "sha256:abc123...",
    "sha256:def456..."
  ],
  "generatedAt": "2025-12-26T10:30:00Z",
  "outputHash": "sha256:789xyz..."
}

Replay Explanation

Re-runs the explanation with identical inputs to verify determinism.

GET /api/v1/advisory-ai/explain/{explanationId}/replay

Response:

{
  "original": { "...original explanation..." },
  "replayed": { "...replayed explanation..." },
  "identical": true,
  "similarity": 1.0,
  "divergenceDetails": null
}

Get Explanation

GET /api/v1/advisory-ai/explain/{explanationId}

Validate Explanation

POST /api/v1/advisory-ai/explain/{explanationId}/validate

Validates that the explanation’s input hashes still match current evidence.

Evidence Types

Authority Classification

Explanations are classified by their evidence backing:

public enum ExplanationAuthority
{
    EvidenceBacked,  // All claims anchored to verified evidence
    Suggestion       // AI suggestion requiring human review
}

Attestation Format

Explanations are wrapped in DSSE (Dead Simple Signing Envelope) attestations:

Predicate Type

https://stellaops.org/attestation/ai-explanation/v1

Predicate Schema

{
  "_type": "https://stellaops.org/attestation/ai-explanation/v1",
  "explanationId": "expl-20251226-001",
  "explanationType": "Full",
  "authority": "EvidenceBacked",
  "finding": {
    "findingId": "finding-abc123",
    "vulnerabilityId": "CVE-2024-1234",
    "componentPurl": "pkg:npm/lodash@4.17.20"
  },
  "model": {
    "modelId": "claude-sonnet-4-20250514",
    "promptTemplateVersion": "v2.1.0"
  },
  "inputs": {
    "inputHashes": ["sha256:abc123...", "sha256:def456..."],
    "evidenceRefs": ["nvd:CVE-2024-1234", "sbom:..."]
  },
  "output": {
    "contentHash": "sha256:789xyz...",
    "confidenceScore": 0.92,
    "citationRate": 0.85,
    "citationCount": 6
  },
  "generatedAt": "2025-12-26T10:30:00Z"
}

DSSE Envelope

{
  "payloadType": "application/vnd.stellaops.ai-explanation+json",
  "payload": "<base64-encoded-predicate>",
  "signatures": [
    {
      "keyId": "stellaops-ai-signer-2025",
      "sig": "<base64-signature>"
    }
  ]
}

OCI Attachment

Attestations are pushed as OCI referrers:

Artifact: sha256:imagedigest
  └── Referrer: application/vnd.stellaops.ai-explanation+json
      └── expl-20251226-001.dsse.json

Replay Semantics

Replay Manifest

Every explanation includes a replay manifest enabling deterministic reproduction:

{
  "manifestVersion": "1.0",
  "explanationId": "expl-20251226-001",
  "model": {
    "modelId": "claude-sonnet-4-20250514",
    "weightsDigest": "sha256:modelweights...",
    "promptTemplateVersion": "v2.1.0"
  },
  "inputs": {
    "findingId": "finding-abc123",
    "artifactDigest": "sha256:abcdef...",
    "evidenceHashes": {
      "advisory": "sha256:111...",
      "sbom": "sha256:222...",
      "reachability": "sha256:333..."
    }
  },
  "parameters": {
    "temperature": 0.0,
    "seed": 42,
    "maxTokens": 4096
  },
  "output": {
    "contentHash": "sha256:789xyz...",
    "generatedAt": "2025-12-26T10:30:00Z"
  }
}

Determinism Requirements

For replay to produce identical output:

Divergence Detection

When replay produces different output:

{
  "diverged": true,
  "similarity": 0.94,
  "originalHash": "sha256:789xyz...",
  "replayedHash": "sha256:different...",
  "divergencePoints": [
    {
      "position": 1234,
      "original": "...uses lodash@4.17.20...",
      "replayed": "...uses lodash version 4.17.20..."
    }
  ],
  "likelyCause": "model_update"
}

Divergence Causes

CLI Commands

# Generate explanation
stella advisory explain finding-abc123 \
  --type full \
  --plain-language \
  --attest --sign

# Replay explanation
stella advisory replay expl-20251226-001

# Verify explanation attestation
stella attest verify expl-20251226-001.dsse.json

# Check for divergence
stella advisory replay expl-20251226-001 --detect-divergence

Configuration

advisoryAi:
  explanation:
    # Default explanation type
    defaultType: Full

    # Plain language by default
    plainLanguage: true

    # Maximum explanation length
    maxLength: 4000

    # Minimum citation rate for EvidenceBacked authority
    minCitationRate: 0.80

    # Generate attestation for each explanation
    generateAttestation: true

    # Sign attestations
    signAttestation: true

  # Determinism settings for replay
  inference:
    temperature: 0.0
    seed: 42
    maxTokens: 4096

3-Line Summary Format

Every explanation includes a 3-line summary following the AI UX pattern:

Error Handling

Generation Errors

{
  "error": "evidence_retrieval_failed",
  "message": "Unable to retrieve SBOM for artifact sha256:abc...",
  "recoverable": true,
  "suggestion": "Ensure the artifact has been scanned before requesting explanation"
}

Validation Errors

{
  "error": "citation_verification_failed",
  "message": "Citation [2] references evidence that no longer exists",
  "invalidCitations": ["sbom:payment-service:lodash@4.17.20"],
  "suggestion": "Re-generate explanation with current evidence"
}

Related Documentation

• Advisory AI API Reference — base conventions, scopes, and the summary/conflict/remediation endpoints
• Guardrails & Evidence Intake — how evidence is sanitized, cited, and sealed
• AI Attestations
• LLM Provider Plugins
• Offline Model Bundles
• Advisory AI Architecture