VEX Override Predicate Specification

Overview

The VEX Override predicate provides a cryptographically signed record of operator decisions to override or annotate vulnerability assessments. This enables auditable, tamper-evident records of security triage decisions within the StellaOps vulnerability management workflow.

Predicate Type URI

https://stellaops.dev/attestations/vex-override/v1

Use Cases

not_affected: Document that a vulnerability does not affect the artifact in its deployed configuration
mitigated: Record compensating controls that address the vulnerability
accepted: Acknowledge an accepted risk with proper authorization
under_investigation: Mark a vulnerability as being actively assessed

Schema

Required Fields

Field	Type	Description
`artifactDigest`	string	Artifact digest this override applies to (e.g., `sha256:abc123...`)
`vulnerabilityId`	string	CVE or vulnerability identifier being overridden
`decision`	string/enum	One of: `not_affected`, `mitigated`, `accepted`, `under_investigation`
`justification`	string	Human-readable explanation for the decision
`decisionTime`	ISO 8601	UTC timestamp when the decision was made
`operatorId`	string	Identifier of the operator who made the decision

Optional Fields

Field	Type	Description
`expiresAt`	ISO 8601	When this override should be re-evaluated
`evidenceRefs`	array	References to supporting documentation
`tool`	object	Information about the tool creating the predicate
`ruleDigest`	string	Digest of the policy rule that triggered evaluation
`traceHash`	string	Hash of reachability analysis at decision time
`metadata`	object	Additional key-value metadata

Evidence Reference Schema

{
  "type": "document|ticket|scan_report|attestation",
  "uri": "https://...",
  "digest": "sha256:...",
  "description": "Optional description"
}

Tool Schema

{
  "name": "StellaOps",
  "version": "1.0.0",
  "vendor": "StellaOps Inc"
}

Sample Payload

{
  "artifactDigest": "sha256:a1b2c3d4e5f6...",
  "decision": "not_affected",
  "decisionTime": "2026-01-14T10:00:00Z",
  "evidenceRefs": [
    {
      "description": "Security review document",
      "digest": "sha256:def456...",
      "type": "document",
      "uri": "https://docs.example.com/security-review/123"
    }
  ],
  "justification": "Component is compiled without the vulnerable code path due to build configuration",
  "operatorId": "security-team@example.com",
  "predicateType": "https://stellaops.dev/attestations/vex-override/v1",
  "ruleDigest": "sha256:rule789...",
  "tool": {
    "name": "StellaOps",
    "vendor": "StellaOps Inc",
    "version": "1.0.0"
  },
  "traceHash": "sha256:trace012...",
  "vulnerabilityId": "CVE-2024-12345"
}

Canonicalization Rules

VEX override predicates MUST be serialized using RFC 8785 JSON Canonicalization Scheme (JCS) before signing:

Key ordering: All object keys are sorted lexicographically (Unicode code point order)
Number format: No exponent notation, no leading zeros, no trailing zeros after decimal
String encoding: Default JSON escaping (no relaxed escaping)
Whitespace: Minified JSON (no whitespace between tokens)
Property naming: Original snake_case field names preserved (no camelCase conversion)

Serializer Configuration

// DO NOT use CamelCase naming policy
// DO NOT use UnsafeRelaxedJsonEscaping
// Use JsonCanonicalizer.Canonicalize() before signing

var canonicalJson = JsonCanonicalizer.Canonicalize(payloadJson);

DSSE Envelope Structure

{
  "payloadType": "https://stellaops.dev/attestations/vex-override/v1",
  "payload": "<base64-encoded-canonical-predicate>",
  "signatures": [
    {
      "keyid": "key-identifier",
      "sig": "<base64-signature>"
    }
  ]
}

Verification

Decode the base64 payload
Verify the signature using DSSE PAE (Pre-Authentication Encoding)
Parse and validate the predicate schema
Check expiration if expiresAt is present
Optionally verify transparency log inclusion (Rekor anchoring)

Offline Verification

The predicate supports offline verification when:

The signing certificate chain is bundled
Transparency log proofs are embedded
No network access is required for validation

See Rekor Verification Design for transparency log integration details.

4.7 KiB Raw Blame History