git.stella-ops.org/docs/policy/verdict-attestations.md

Policy Verdict Attestations

Status: Implementation in Progress (SPRINT_3000_0100_0001) Predicate URI: https://stellaops.dev/predicates/policy-verdict@v1 Schema: docs/schemas/stellaops-policy-verdict.v1.schema.json

---

Overview

Verdict Attestations provide cryptographically-bound proof that a policy evaluation verdict (passed/warned/blocked/quieted) was issued for a specific finding at a specific time with specific evidence. Every policy run produces signed verdict attestations wrapped in DSSE envelopes, enabling:

• Trust & Integrity: Cryptographic proof verdicts haven't been tampered with
• Audit & Compliance: Standalone artifacts for incident review, regulatory compliance
• Automation: Downstream tools can verify verdict authenticity before acting
• Transparency: Optional anchoring in Rekor transparency log

---

Architecture

Flow

Policy Engine
    ↓ (evaluates finding)
PolicyExplainTrace
    ↓ (mapped to)
VerdictPredicate (canonical JSON)
    ↓ (sent to)
Attestor Service
    ↓ (signs with DSSE)
Verdict Attestation (signed envelope)
    ↓ (stored in)
Evidence Locker (PostgreSQL + object store)
    ↓ (optionally anchored in)
Rekor Transparency Log

Components

Component	Responsibility	Location
PolicyExplainTrace	Policy evaluation result	StellaOps.Scheduler.Models
VerdictPredicateBuilder	Maps trace → predicate	StellaOps.Policy.Engine.Attestation
VerdictAttestationService	Sends attestation requests	StellaOps.Policy.Engine.Attestation
VerdictAttestationHandler	Receives, validates, signs	StellaOps.Attestor
Evidence Locker	Stores and indexes verdicts	StellaOps.EvidenceLocker

---

Predicate Schema

See stellaops-policy-verdict.v1.schema.json for the complete JSON schema.

Example Predicate

{
  "_type": "https://stellaops.dev/predicates/policy-verdict@v1",
  "tenantId": "tenant-alpha",
  "policyId": "P-7",
  "policyVersion": 4,
  "runId": "run:P-7:20251223T140500Z:1b2c3d4e",
  "findingId": "finding:sbom:S-42/pkg:npm/lodash@4.17.21",
  "evaluatedAt": "2025-12-23T14:06:01+00:00",
  "verdict": {
    "status": "blocked",
    "severity": "critical",
    "score": 19.5,
    "rationale": "CVE-2025-12345 exploitable via lodash.template with confirmed reachability"
  },
  "ruleChain": [
    {
      "ruleId": "rule-allow-known",
      "action": "allow",
      "decision": "skipped"
    },
    {
      "ruleId": "rule-block-critical",
      "action": "block",
      "decision": "matched",
      "score": 19.5
    }
  ],
  "evidence": [
    {
      "type": "advisory",
      "reference": "CVE-2025-12345",
      "source": "nvd",
      "status": "affected",
      "digest": "sha256:abc123...",
      "weight": 1.0
    },
    {
      "type": "vex",
      "reference": "vex:ghsa-2025-0001",
      "source": "vendor",
      "status": "not_affected",
      "digest": "sha256:def456...",
      "weight": 0.5,
      "metadata": {}
    }
  ],
  "vexImpacts": [
    {
      "statementId": "vex:ghsa-2025-0001",
      "provider": "vendor",
      "status": "not_affected",
      "accepted": false,
      "justification": "VEX statement contradicts confirmed reachability analysis"
    }
  ],
  "reachability": {
    "status": "confirmed",
    "paths": [
      {
        "entrypoint": "GET /api/users",
        "sink": "lodash.template",
        "confidence": "high",
        "digest": "sha256:path123..."
      }
    ]
  },
  "metadata": {
    "componentPurl": "pkg:npm/lodash@4.17.21",
    "sbomId": "sbom:S-42",
    "traceId": "01HE0BJX5S4T9YCN6ZT0",
    "determinismHash": "sha256:..."
  }
}

DSSE Envelope

The predicate is wrapped in a DSSE envelope:

{
  "payload": "<base64(canonicalJson(predicate))>",
  "payloadType": "application/vnd.stellaops.policy-verdict+json",
  "signatures": [
    {
      "keyid": "sha256:keypair123...",
      "sig": "<base64(signature)>"
    }
  ]
}

---

API Reference

Create Verdict Attestation (Internal)

Note: This is an internal API called by the Policy Engine, not exposed externally.

POST /internal/api/v1/attestations/verdict
Content-Type: application/json

Request:

{
  "predicateType": "https://stellaops.dev/predicates/policy-verdict@v1",
  "predicate": "{...}",
  "subject": [
    {
      "name": "finding:sbom:S-42/pkg:npm/lodash@4.17.21",
      "digest": {
        "sha256": "abc123..."
      }
    }
  ]
}

Response:

{
  "verdictId": "verdict:run:P-7:20251223T140500Z:finding-42",
  "attestationUri": "/api/v1/verdicts/verdict:run:P-7:20251223T140500Z:finding-42",
  "rekorLogIndex": 12345678
}

Retrieve Verdict Attestation

GET /api/v1/verdicts/{verdictId}

Response:

{
  "verdictId": "verdict:run:P-7:20251223T140500Z:finding-42",
  "tenantId": "tenant-alpha",
  "policyRunId": "run:P-7:20251223T140500Z:1b2c3d4e",
  "findingId": "finding:sbom:S-42/pkg:npm/lodash@4.17.21",
  "verdictStatus": "blocked",
  "evaluatedAt": "2025-12-23T14:06:01+00:00",
  "envelope": {
    "payload": "<base64>",
    "payloadType": "application/vnd.stellaops.policy-verdict+json",
    "signatures": [...]
  },
  "rekorLogIndex": 12345678,
  "createdAt": "2025-12-23T14:06:05+00:00"
}

List Verdicts for Policy Run

GET /api/v1/runs/{runId}/verdicts?status=blocked&limit=50

Query Parameters:

• status: Filter by verdict status (passed/warned/blocked/quieted)
• severity: Filter by severity (critical/high/medium/low)
• limit: Maximum results (default 50, max 200)
• offset: Pagination offset

Response:

{
  "verdicts": [
    {
      "verdictId": "verdict:run:P-7:20251223T140500Z:finding-42",
      "findingId": "finding:sbom:S-42/pkg:npm/lodash@4.17.21",
      "verdictStatus": "blocked",
      "severity": "critical",
      "evaluatedAt": "2025-12-23T14:06:01+00:00"
    }
  ],
  "pagination": {
    "total": 234,
    "limit": 50,
    "offset": 0
  }
}

Verify Verdict Signature

POST /api/v1/verdicts/{verdictId}/verify

Response:

{
  "verdictId": "verdict:run:P-7:20251223T140500Z:finding-42",
  "signatureValid": true,
  "verifiedAt": "2025-12-23T15:00:00+00:00",
  "verifications": [
    {
      "keyId": "sha256:keypair123...",
      "algorithm": "ed25519",
      "valid": true
    }
  ],
  "rekorVerification": {
    "logIndex": 12345678,
    "inclusionProofValid": true,
    "verifiedAt": "2025-12-23T15:00:01+00:00"
  }
}

---

CLI Usage

Retrieve Verdict

stella verdict get verdict:run:P-7:20251223T140500Z:finding-42

# Output:
# Verdict: blocked (critical, score 19.5)
# Finding: finding:sbom:S-42/pkg:npm/lodash@4.17.21
# Evaluated: 2025-12-23T14:06:01+00:00
# Signature: ✓ Verified (ed25519)
# Rekor: ✓ Anchored (log index 12345678)

Verify Verdict Signature (Offline)

stella verdict verify verdict-12345.json --public-key ./pubkey.pem

# Output:
# ✓ Signature valid
# ✓ Predicate schema valid
# ✓ Determinism hash matches

List Verdicts for Run

stella verdict list --run run:P-7:20251223T140500Z:1b2c3d4e --status blocked

# Output:
# 234 verdicts found (showing 50)
#
# verdict:...:finding-42 | blocked | critical | CVE-2025-12345 | lodash@4.17.21
# verdict:...:finding-78 | blocked | high     | CVE-2025-99999 | express@4.18.0
# ...

Download Verdict Envelope

stella verdict download verdict:run:P-7:20251223T140500Z:finding-42 --output ./verdict.json

---

Implementation Guide

Policy Engine Integration

The Policy Engine's PolicyRunExecutionService calls VerdictAttestationService after evaluating each finding:

public class PolicyRunExecutionService
{
    private readonly VerdictAttestationService _verdictAttestationService;

    public async Task<PolicyRunStatus> ExecuteAsync(PolicyRunRequest request)
    {
        // ... policy evaluation logic

        foreach (var trace in explainTraces)
        {
            // Emit verdict attestation
            if (_options.VerdictAttestationsEnabled)
            {
                var verdictId = await _verdictAttestationService.AttestVerdictAsync(trace);
                _logger.LogInformation("Verdict attestation created: {VerdictId}", verdictId);
            }
        }

        // ... continue
    }
}

Attestor Handler

The Attestor receives attestation requests via internal API:

public class VerdictAttestationHandler
{
    public async Task<AttestationResult> HandleAsync(AttestationRequest request)
    {
        // 1. Validate predicate schema
        await _schemaValidator.ValidateAsync(request.Predicate, request.PredicateType);

        // 2. Create DSSE envelope
        var envelope = await _dsseService.SignAsync(request);

        // 3. Store in Evidence Locker
        var verdictId = await _evidenceLocker.StoreVerdictAsync(envelope);

        // 4. Optional: Anchor in Rekor
        long? rekorLogIndex = null;
        if (_options.RekorEnabled)
        {
            rekorLogIndex = await _rekorClient.UploadAsync(envelope);
        }

        return new AttestationResult
        {
            VerdictId = verdictId,
            RekorLogIndex = rekorLogIndex
        };
    }
}

Evidence Locker Storage

Verdicts are stored in PostgreSQL with full-text index and object store reference:

INSERT INTO verdict_attestations (
    verdict_id,
    tenant_id,
    run_id,
    policy_id,
    policy_version,
    finding_id,
    verdict_status,
    evaluated_at,
    envelope,
    predicate_digest,
    rekor_log_index
) VALUES (
    'verdict:run:P-7:20251223T140500Z:finding-42',
    'tenant-alpha',
    'run:P-7:20251223T140500Z:1b2c3d4e',
    'P-7',
    4,
    'finding:sbom:S-42/pkg:npm/lodash@4.17.21',
    'blocked',
    '2025-12-23T14:06:01+00:00',
    '{"payload": "...", "signatures": [...]}',
    'sha256:abc123...',
    12345678
);

---

Determinism

Verdict attestations are deterministic when evaluated with identical inputs:

1. Input Normalization: Policy inputs (SBOMs, advisories, VEX, environment) are canonicalized
2. Canonical JSON: Predicates serialize with lexicographic key ordering
3. Stable Sorting: Evidence, rule chains, and arrays are sorted deterministically
4. Hash Computation: determinismHash = SHA256(sorted digests of all evidence)

Determinism Validation

# Compute determinism hash for policy run
stella policy determinism-hash run:P-7:20251223T140500Z:1b2c3d4e

# Compare with original run's hash
# If hashes match → deterministic
# If hashes differ → identify divergence source

---

Offline Support

Verdict attestations support air-gapped deployments:

• Signature Verification: Uses bundled public keys, no network required
• Rekor Optional: Transparency log anchoring can be disabled
• Bundle Export: Verdicts included in evidence packs for offline transfer

---

Performance Considerations

Volume

Large policy runs can produce millions of verdicts:

• Batch Signing: Group verdicts into batches, sign batch manifest
• Async Processing: Attestation pipeline runs asynchronously from policy evaluation
• Compression: Verdict envelopes use compact JSON and gzip compression

Storage

• Hot Storage: Recent verdicts (< 30 days) in PostgreSQL
• Cold Storage: Older verdicts archived to object store
• Indexing: Indexes on run_id, finding_id, tenant_id, evaluated_at

---

Security

Signing Keys

• Key Management: Keys stored in KMS or CryptoPro (GOST support)
• Key Rotation: Verdicts include keyId, support multi-signature
• Offline Keys: Support for offline signing ceremonies (air-gapped)

Access Control

• RBAC: policy:verdict:read scope required for API access
• Tenant Isolation: Verdicts scoped by tenantId, cross-tenant queries blocked
• Audit Trail: All verdict retrievals logged with actor, timestamp

---

Troubleshooting

Verdict Attestation Failed

Symptom: Policy run completes but no verdicts created

Causes:

1. Attestor service unavailable → Check health endpoint
2. Schema validation failure → Check predicate structure
3. Signing key unavailable → Verify KMS connectivity

Resolution:

# Check attestor health
curl http://attestor:8080/health

# Verify predicate schema
stella schema validate policy-verdict.json --schema stellaops-policy-verdict.v1.schema.json

# Retry attestation
stella policy rerun run:P-7:20251223T140500Z:1b2c3d4e --attestations-only

Signature Verification Failed

Symptom: POST /api/v1/verdicts/{id}/verify returns signatureValid: false

Causes:

1. Public key mismatch → Verify correct key for keyId
2. Payload tampering → Compare digest with original
3. Clock skew → Check timestamp validity window

Resolution:

# Verify with correct public key
stella verdict verify verdict.json --public-key ./correct-pubkey.pem

# Check payload digest
stella digest compute verdict.json

---

References

• DSSE Specification
• Rekor Transparency Log
• Policy Engine Architecture
• Attestor Architecture
• Evidence Locker Architecture