git.stella-ops.org/docs/modules/vuln-explorer/guides/signed-vex-override-workflow.md

Signed VEX Override Workflow

This guide describes how to create and manage signed VEX override decisions using DSSE attestations for audit-grade provenance.

Overview

VEX (Vulnerability Exploitability eXchange) decisions allow operators to mark vulnerabilities as not-affected, mitigated, or accepted-risk. When attestation signing is enabled, each override produces a DSSE envelope that:

1. Cryptographically binds the decision to the operator's identity
2. Records the decision in an immutable attestation log
3. Optionally anchors the attestation to Sigstore Rekor for transparency
4. Enables downstream policy engines to require signed overrides

API Endpoints

Create Signed Override

POST /v1/vex-decisions
Content-Type: application/json
Authorization: Bearer <token>

{
  "findingId": "find-abc123",
  "status": "NOT_AFFECTED",
  "justification": "CODE_NOT_REACHABLE",
  "justificationText": "Static analysis confirms code path is unreachable in production configuration",
  "scope": {
    "environments": ["production"],
    "projects": ["myapp"]
  },
  "validity": {
    "notBefore": "2026-01-15T00:00:00Z",
    "notAfter": "2026-07-15T00:00:00Z"
  },
  "attestationOptions": {
    "sign": true,
    "keyRef": "default-signing-key",
    "rekorUpload": true,
    "predicateType": "https://stella.ops/predicates/vex-override/v1"
  }
}

Response with Attestation Reference

{
  "id": "vex-dec-xyz789",
  "findingId": "find-abc123",
  "status": "NOT_AFFECTED",
  "justification": "CODE_NOT_REACHABLE",
  "justificationText": "Static analysis confirms code path is unreachable in production configuration",
  "createdAt": "2026-01-15T10:30:00Z",
  "createdBy": "user@example.com",
  "signedOverride": {
    "envelopeDigest": "sha256:abc123def456...",
    "signatureAlgorithm": "ECDSA_P256_SHA256",
    "signedAt": "2026-01-15T10:30:01Z",
    "keyId": "default-signing-key",
    "rekorInfo": {
      "logIndex": 123456789,
      "entryId": "24296fb24b8ad77a...",
      "integratedTime": "2026-01-15T10:30:02Z",
      "logId": "c0d23d6ad406973f..."
    },
    "verificationStatus": "VERIFIED"
  }
}

Update Signed Override

Updates create superseding records while preserving history:

PATCH /v1/vex-decisions/{id}
Content-Type: application/json
Authorization: Bearer <token>

{
  "status": "AFFECTED_MITIGATED",
  "justification": "COMPENSATING_CONTROLS",
  "justificationText": "WAF rule deployed to block exploit vectors",
  "attestationOptions": {
    "sign": true,
    "supersedes": "vex-dec-xyz789"
  }
}

List Decisions with Attestation Filter

GET /v1/vex-decisions?signedOnly=true&rekorAnchored=true

Verify Attestation

POST /v1/vex-decisions/{id}/verify

Response:

{
  "verified": true,
  "signatureValid": true,
  "rekorEntryValid": true,
  "certificateChain": ["CN=signing-key,..."],
  "verifiedAt": "2026-01-15T10:35:00Z"
}

CLI Usage

Create Signed Override

stella vex create \
  --finding find-abc123 \
  --status NOT_AFFECTED \
  --justification CODE_NOT_REACHABLE \
  --reason "Static analysis confirms unreachable" \
  --sign \
  --key default-signing-key \
  --rekor

View Override with Attestation

stella vex show vex-dec-xyz789 --include-attestation

Output:

VEX Decision: vex-dec-xyz789
  Finding:        find-abc123
  Status:         NOT_AFFECTED
  Justification:  CODE_NOT_REACHABLE
  Created:        2026-01-15T10:30:00Z
  Created By:     user@example.com
  
Attestation:
  Envelope Digest: sha256:abc123def456...
  Algorithm:       ECDSA_P256_SHA256
  Signed At:       2026-01-15T10:30:01Z
  Verification:    VERIFIED
  
Rekor Entry:
  Log Index:       123456789
  Entry ID:        24296fb24b8ad77a...
  Integrated Time: 2026-01-15T10:30:02Z

Verify Override Attestation

stella vex verify vex-dec-xyz789

Export Override Evidence

stella vex export vex-dec-xyz789 \
  --format bundle \
  --output override-evidence.zip

Policy Engine Integration

Signed overrides can be required by policy rules:

# Policy requiring signed VEX overrides
rules:
  - id: require-signed-vex
    condition: |
      vex.status in ["NOT_AFFECTED", "AFFECTED_MITIGATED"] 
      and (vex.signedOverride == null or vex.signedOverride.verificationStatus != "VERIFIED")
    action: FAIL
    message: "VEX overrides must be signed and verified"

Attestation Predicate Schema

The VEX override predicate follows in-toto attestation format:

{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [
    {
      "name": "finding:find-abc123",
      "digest": { "sha256": "..." }
    }
  ],
  "predicateType": "https://stella.ops/predicates/vex-override/v1",
  "predicate": {
    "decision": {
      "id": "vex-dec-xyz789",
      "status": "NOT_AFFECTED",
      "justification": "CODE_NOT_REACHABLE",
      "justificationText": "...",
      "scope": { "environments": ["production"] },
      "validity": { "notBefore": "...", "notAfter": "..." }
    },
    "finding": {
      "id": "find-abc123",
      "cve": "CVE-2026-1234",
      "package": "example-pkg",
      "version": "1.2.3"
    },
    "operator": {
      "identity": "user@example.com",
      "authorizedAt": "2026-01-15T10:30:00Z"
    },
    "supersedes": null
  }
}

Security Considerations

1. Key Management: Signing keys should be managed through Authority with appropriate access controls
2. Rekor Anchoring: Enable Rekor upload for public transparency; disable for air-gapped deployments
3. Expiry: Set appropriate validity windows; expired overrides surface warnings
4. Audit Trail: All signed overrides are recorded in the findings ledger history

Offline/Air-Gap Mode

For air-gapped deployments:

1. Rekor upload is disabled automatically
2. Attestations are stored locally with envelope digests
3. Verification uses local trust roots
4. Export bundles include all attestation evidence for manual verification

Related Documentation

• VEX Consensus Guide
• Attestor Architecture
• Findings Ledger
• Policy Integration