259 lines
7.5 KiB
JSON
259 lines
7.5 KiB
JSON
{
|
|
"$id": "https://stella.ops/schema/vex-decision.json",
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"title": "VexDecision",
|
|
"description": "VEX-style statement attached to a finding + subject, representing a vulnerability exploitability decision",
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"vulnerabilityId",
|
|
"subject",
|
|
"status",
|
|
"justificationType",
|
|
"createdBy",
|
|
"createdAt"
|
|
],
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Internal stable ID for this decision"
|
|
},
|
|
"vulnerabilityId": {
|
|
"type": "string",
|
|
"description": "CVE, GHSA, or other vulnerability identifier",
|
|
"examples": ["CVE-2023-12345", "GHSA-xxxx-yyyy-zzzz"]
|
|
},
|
|
"subject": {
|
|
"$ref": "#/$defs/SubjectRef",
|
|
"description": "The artifact or SBOM component this decision applies to"
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"NOT_AFFECTED",
|
|
"UNDER_INVESTIGATION",
|
|
"AFFECTED_MITIGATED",
|
|
"AFFECTED_UNMITIGATED",
|
|
"FIXED"
|
|
],
|
|
"description": "VEX status following OpenVEX semantics"
|
|
},
|
|
"justificationType": {
|
|
"type": "string",
|
|
"enum": [
|
|
"CODE_NOT_PRESENT",
|
|
"CODE_NOT_REACHABLE",
|
|
"VULNERABLE_CODE_NOT_IN_EXECUTE_PATH",
|
|
"CONFIGURATION_NOT_AFFECTED",
|
|
"OS_NOT_AFFECTED",
|
|
"RUNTIME_MITIGATION_PRESENT",
|
|
"COMPENSATING_CONTROLS",
|
|
"ACCEPTED_BUSINESS_RISK",
|
|
"OTHER"
|
|
],
|
|
"description": "Justification type inspired by CSAF/VEX specifications"
|
|
},
|
|
"justificationText": {
|
|
"type": "string",
|
|
"maxLength": 4000,
|
|
"description": "Free-form explanation supporting the justification type"
|
|
},
|
|
"evidenceRefs": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/$defs/EvidenceRef"
|
|
},
|
|
"description": "Links to PRs, commits, tickets, docs supporting this decision"
|
|
},
|
|
"scope": {
|
|
"$ref": "#/$defs/VexScope",
|
|
"description": "Environments and projects where this decision applies"
|
|
},
|
|
"validFor": {
|
|
"$ref": "#/$defs/ValidFor",
|
|
"description": "Time window during which this decision is valid"
|
|
},
|
|
"attestationRef": {
|
|
"$ref": "#/$defs/AttestationRef",
|
|
"description": "Reference to the signed attestation for this decision"
|
|
},
|
|
"supersedesDecisionId": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "ID of a previous decision this one supersedes"
|
|
},
|
|
"createdBy": {
|
|
"$ref": "#/$defs/ActorRef",
|
|
"description": "User who created this decision"
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO-8601 timestamp when decision was created"
|
|
},
|
|
"updatedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO-8601 timestamp when decision was last updated"
|
|
}
|
|
},
|
|
"$defs": {
|
|
"SubjectRef": {
|
|
"type": "object",
|
|
"required": ["type", "name", "digest"],
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": ["IMAGE", "REPO", "SBOM_COMPONENT", "OTHER"],
|
|
"description": "Type of artifact this subject represents"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Human-readable subject name (e.g. image ref, package name)",
|
|
"examples": ["registry.internal/stella/app-service@sha256:7d9c..."]
|
|
},
|
|
"digest": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "string"
|
|
},
|
|
"description": "Algorithm -> digest map (e.g. sha256 -> hex string)",
|
|
"examples": [{"sha256": "7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee"}]
|
|
},
|
|
"sbomNodeId": {
|
|
"type": "string",
|
|
"description": "Optional SBOM node/bomRef identifier for SBOM_COMPONENT subjects"
|
|
}
|
|
}
|
|
},
|
|
"EvidenceRef": {
|
|
"type": "object",
|
|
"required": ["type", "url"],
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": ["PR", "TICKET", "DOC", "COMMIT", "OTHER"],
|
|
"description": "Type of evidence link"
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Human-readable title for the evidence"
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"format": "uri",
|
|
"description": "URL to the evidence resource"
|
|
}
|
|
}
|
|
},
|
|
"VexScope": {
|
|
"type": "object",
|
|
"properties": {
|
|
"environments": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Environment names where decision applies (e.g. prod, staging)",
|
|
"examples": [["prod", "staging"]]
|
|
},
|
|
"projects": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Project/service names where decision applies"
|
|
}
|
|
},
|
|
"description": "If empty/null, decision applies to all environments and projects"
|
|
},
|
|
"ValidFor": {
|
|
"type": "object",
|
|
"properties": {
|
|
"notBefore": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "Decision is not valid before this timestamp (defaults to creation time)"
|
|
},
|
|
"notAfter": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "Decision expires after this timestamp (recommended to set)"
|
|
}
|
|
}
|
|
},
|
|
"AttestationRef": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Internal attestation identifier"
|
|
},
|
|
"digest": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "string"
|
|
},
|
|
"description": "Content digest of the attestation"
|
|
},
|
|
"storage": {
|
|
"type": "string",
|
|
"description": "Storage location (OCI ref, bundle path, or URL)",
|
|
"examples": ["oci://registry.internal/stella/attestations@sha256:2e61..."]
|
|
}
|
|
}
|
|
},
|
|
"ActorRef": {
|
|
"type": "object",
|
|
"required": ["id", "displayName"],
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "User identifier"
|
|
},
|
|
"displayName": {
|
|
"type": "string",
|
|
"description": "Human-readable display name"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"examples": [
|
|
{
|
|
"id": "8a3d0b5a-1e07-4b57-b6a1-1a29ce6c889e",
|
|
"vulnerabilityId": "CVE-2023-12345",
|
|
"subject": {
|
|
"type": "IMAGE",
|
|
"name": "registry.internal/stella/app-service@sha256:7d9c...",
|
|
"digest": {
|
|
"sha256": "7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee"
|
|
}
|
|
},
|
|
"status": "NOT_AFFECTED",
|
|
"justificationType": "VULNERABLE_CODE_NOT_IN_EXECUTE_PATH",
|
|
"justificationText": "Vulnerable CLI helper is present in the image but never invoked in the running service.",
|
|
"evidenceRefs": [
|
|
{
|
|
"type": "PR",
|
|
"title": "Document non-usage of CLI helper",
|
|
"url": "https://git.example.com/stella/app-service/merge_requests/42"
|
|
}
|
|
],
|
|
"scope": {
|
|
"environments": ["prod", "staging"],
|
|
"projects": ["app-service"]
|
|
},
|
|
"validFor": {
|
|
"notBefore": "2025-11-21T10:15:00Z",
|
|
"notAfter": "2026-05-21T10:15:00Z"
|
|
},
|
|
"createdBy": {
|
|
"id": "user-123",
|
|
"displayName": "Alice Johnson"
|
|
},
|
|
"createdAt": "2025-11-21T10:15:00Z"
|
|
}
|
|
]
|
|
}
|