Add signal contracts for reachability, exploitability, trust, and unknown symbols
- Introduced `ReachabilityState`, `RuntimeHit`, `ExploitabilitySignal`, `ReachabilitySignal`, `SignalEnvelope`, `SignalType`, `TrustSignal`, and `UnknownSymbolSignal` records to define various signal types and their properties. - Implemented JSON serialization attributes for proper data interchange. - Created project files for the new signal contracts library and corresponding test projects. - Added deterministic test fixtures for micro-interaction testing. - Included cryptographic keys for secure operations with cosign.
This commit is contained in:
StellaOps Bot
303
docs/schemas/vex-normalization.schema.json
Normal file
303
docs/schemas/vex-normalization.schema.json
Normal file
@@ -0,0 +1,303 @@
|
||||
{
|
||||
"$id": "https://stella.ops/schema/vex-normalization.json",
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"title": "VexNormalization",
|
||||
"description": "Normalized VEX representation supporting OpenVEX, CSAF VEX, and CycloneDX VEX formats with unified semantics",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"schemaVersion",
|
||||
"documentId",
|
||||
"sourceFormat",
|
||||
"statements"
|
||||
],
|
||||
"properties": {
|
||||
"schemaVersion": {
|
||||
"type": "integer",
|
||||
"const": 1,
|
||||
"description": "Schema version for forward compatibility"
|
||||
},
|
||||
"documentId": {
|
||||
"type": "string",
|
||||
"description": "Unique document identifier derived from source VEX",
|
||||
"examples": ["openvex:ghsa-2022-0001", "csaf:rhsa-2023-1234"]
|
||||
},
|
||||
"sourceFormat": {
|
||||
"type": "string",
|
||||
"enum": ["OPENVEX", "CSAF_VEX", "CYCLONEDX_VEX", "SPDX_VEX", "STELLAOPS"],
|
||||
"description": "Original VEX document format before normalization"
|
||||
},
|
||||
"sourceDigest": {
|
||||
"type": "string",
|
||||
"pattern": "^sha256:[a-f0-9]{64}$",
|
||||
"description": "SHA-256 digest of original source document"
|
||||
},
|
||||
"sourceUri": {
|
||||
"type": "string",
|
||||
"format": "uri",
|
||||
"description": "URI where source document was obtained"
|
||||
},
|
||||
"issuer": {
|
||||
"$ref": "#/$defs/VexIssuer",
|
||||
"description": "Issuing authority for this VEX document"
|
||||
},
|
||||
"issuedAt": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO-8601 timestamp when VEX was originally issued"
|
||||
},
|
||||
"lastUpdatedAt": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO-8601 timestamp when VEX was last modified"
|
||||
},
|
||||
"statements": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/NormalizedStatement"
|
||||
},
|
||||
"minItems": 1,
|
||||
"description": "Normalized VEX statements extracted from source"
|
||||
},
|
||||
"provenance": {
|
||||
"$ref": "#/$defs/NormalizationProvenance",
|
||||
"description": "Metadata about the normalization process"
|
||||
}
|
||||
},
|
||||
"$defs": {
|
||||
"VexIssuer": {
|
||||
"type": "object",
|
||||
"required": ["id", "name"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Unique issuer identifier (e.g., PURL, domain)",
|
||||
"examples": ["pkg:github/anchore", "redhat.com", "github.com/github"]
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Human-readable issuer name"
|
||||
},
|
||||
"category": {
|
||||
"type": "string",
|
||||
"enum": ["VENDOR", "DISTRIBUTOR", "COMMUNITY", "INTERNAL", "AGGREGATOR"],
|
||||
"description": "Issuer category for trust weighting"
|
||||
},
|
||||
"trustTier": {
|
||||
"type": "string",
|
||||
"enum": ["AUTHORITATIVE", "TRUSTED", "UNTRUSTED", "UNKNOWN"],
|
||||
"description": "Trust tier for policy evaluation"
|
||||
},
|
||||
"keyFingerprints": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Known signing key fingerprints for this issuer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"NormalizedStatement": {
|
||||
"type": "object",
|
||||
"required": ["statementId", "vulnerabilityId", "product", "status"],
|
||||
"properties": {
|
||||
"statementId": {
|
||||
"type": "string",
|
||||
"description": "Unique statement identifier within this document"
|
||||
},
|
||||
"vulnerabilityId": {
|
||||
"type": "string",
|
||||
"description": "CVE, GHSA, or other vulnerability identifier",
|
||||
"examples": ["CVE-2023-12345", "GHSA-xxxx-yyyy-zzzz"]
|
||||
},
|
||||
"vulnerabilityAliases": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Known aliases for this vulnerability"
|
||||
},
|
||||
"product": {
|
||||
"$ref": "#/$defs/NormalizedProduct"
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["not_affected", "affected", "fixed", "under_investigation"],
|
||||
"description": "Normalized VEX status using OpenVEX terminology"
|
||||
},
|
||||
"statusNotes": {
|
||||
"type": "string",
|
||||
"description": "Additional notes about the status determination"
|
||||
},
|
||||
"justification": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"component_not_present",
|
||||
"vulnerable_code_not_present",
|
||||
"vulnerable_code_not_in_execute_path",
|
||||
"vulnerable_code_cannot_be_controlled_by_adversary",
|
||||
"inline_mitigations_already_exist"
|
||||
],
|
||||
"description": "Normalized justification when status is not_affected"
|
||||
},
|
||||
"impactStatement": {
|
||||
"type": "string",
|
||||
"description": "Impact description when status is affected"
|
||||
},
|
||||
"actionStatement": {
|
||||
"type": "string",
|
||||
"description": "Recommended action to remediate"
|
||||
},
|
||||
"actionStatementTimestamp": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"versions": {
|
||||
"$ref": "#/$defs/VersionRange",
|
||||
"description": "Version constraints for this statement"
|
||||
},
|
||||
"subcomponents": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/NormalizedProduct"
|
||||
},
|
||||
"description": "Specific subcomponents affected within the product"
|
||||
},
|
||||
"firstSeen": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "When this statement was first observed"
|
||||
},
|
||||
"lastSeen": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "When this statement was last confirmed"
|
||||
}
|
||||
}
|
||||
},
|
||||
"NormalizedProduct": {
|
||||
"type": "object",
|
||||
"required": ["key"],
|
||||
"properties": {
|
||||
"key": {
|
||||
"type": "string",
|
||||
"description": "Canonical product key (preferably PURL)"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Human-readable product name"
|
||||
},
|
||||
"version": {
|
||||
"type": "string",
|
||||
"description": "Specific version if applicable"
|
||||
},
|
||||
"purl": {
|
||||
"type": "string",
|
||||
"pattern": "^pkg:",
|
||||
"description": "Package URL if available"
|
||||
},
|
||||
"cpe": {
|
||||
"type": "string",
|
||||
"pattern": "^cpe:",
|
||||
"description": "CPE identifier if available"
|
||||
},
|
||||
"hashes": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Content hashes (algorithm -> value)"
|
||||
}
|
||||
}
|
||||
},
|
||||
"VersionRange": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"affected": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Version expressions for affected versions"
|
||||
},
|
||||
"fixed": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Version expressions for fixed versions"
|
||||
},
|
||||
"unaffected": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Version expressions for unaffected versions"
|
||||
}
|
||||
}
|
||||
},
|
||||
"NormalizationProvenance": {
|
||||
"type": "object",
|
||||
"required": ["normalizedAt", "normalizer"],
|
||||
"properties": {
|
||||
"normalizedAt": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "When normalization was performed"
|
||||
},
|
||||
"normalizer": {
|
||||
"type": "string",
|
||||
"description": "Service/version that performed normalization",
|
||||
"examples": ["stellaops-excititor/1.0.0"]
|
||||
},
|
||||
"sourceRevision": {
|
||||
"type": "string",
|
||||
"description": "Source document revision if tracked"
|
||||
},
|
||||
"transformationRules": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Transformation rules applied during normalization"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"examples": [
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"documentId": "openvex:ghsa-2023-0001",
|
||||
"sourceFormat": "OPENVEX",
|
||||
"sourceDigest": "sha256:7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee",
|
||||
"sourceUri": "https://github.com/anchore/vex-data/example.json",
|
||||
"issuer": {
|
||||
"id": "pkg:github/anchore",
|
||||
"name": "Anchore",
|
||||
"category": "VENDOR",
|
||||
"trustTier": "TRUSTED"
|
||||
},
|
||||
"issuedAt": "2025-11-21T10:00:00Z",
|
||||
"statements": [
|
||||
{
|
||||
"statementId": "stmt-001",
|
||||
"vulnerabilityId": "CVE-2023-12345",
|
||||
"product": {
|
||||
"key": "pkg:npm/example@1.0.0",
|
||||
"name": "example",
|
||||
"version": "1.0.0",
|
||||
"purl": "pkg:npm/example@1.0.0"
|
||||
},
|
||||
"status": "not_affected",
|
||||
"justification": "vulnerable_code_not_in_execute_path",
|
||||
"statusNotes": "The vulnerable function is not used in the package's runtime code path.",
|
||||
"firstSeen": "2025-11-21T10:00:00Z",
|
||||
"lastSeen": "2025-11-21T10:00:00Z"
|
||||
}
|
||||
],
|
||||
"provenance": {
|
||||
"normalizedAt": "2025-11-21T10:15:00Z",
|
||||
"normalizer": "stellaops-excititor/1.0.0"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user