git.stella-ops.org/docs/attestor/schemas/verdict-manifest.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stella-ops.org/schemas/verdict-manifest/1.0.0",
  "title": "Verdict Manifest",
  "description": "A signed, immutable record of a VEX decisioning outcome that enables deterministic replay and audit compliance.",
  "type": "object",
  "required": [
    "manifestId",
    "tenant",
    "assetDigest",
    "vulnerabilityId",
    "inputs",
    "result",
    "policyHash",
    "latticeVersion",
    "evaluatedAt",
    "manifestDigest"
  ],
  "properties": {
    "manifestId": {
      "type": "string",
      "description": "Unique identifier in format: verd:{tenant}:{asset_short}:{vuln_id}:{timestamp}",
      "pattern": "^verd:[a-z0-9-]+:[a-f0-9]+:[A-Z0-9-]+:[0-9]+$"
    },
    "tenant": {
      "type": "string",
      "description": "Tenant identifier for multi-tenancy",
      "minLength": 1
    },
    "assetDigest": {
      "type": "string",
      "description": "SHA256 digest of the asset/SBOM",
      "pattern": "^sha256:[a-f0-9]{64}$"
    },
    "vulnerabilityId": {
      "type": "string",
      "description": "CVE, GHSA, or vendor vulnerability identifier",
      "minLength": 1
    },
    "inputs": {
      "$ref": "#/$defs/VerdictInputs"
    },
    "result": {
      "$ref": "#/$defs/VerdictResult"
    },
    "policyHash": {
      "type": "string",
      "description": "SHA256 hash of the policy configuration",
      "pattern": "^sha256:[a-f0-9]{64}$"
    },
    "latticeVersion": {
      "type": "string",
      "description": "Semantic version of the trust lattice algorithm",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
    },
    "evaluatedAt": {
      "type": "string",
      "description": "ISO 8601 UTC timestamp of evaluation",
      "format": "date-time"
    },
    "manifestDigest": {
      "type": "string",
      "description": "SHA256 digest of the canonical manifest (excluding this field)",
      "pattern": "^sha256:[a-f0-9]{64}$"
    }
  },
  "$defs": {
    "VerdictInputs": {
      "type": "object",
      "description": "All inputs pinned for deterministic replay",
      "required": ["sbomDigests", "vulnFeedSnapshotIds", "vexDocumentDigests", "clockCutoff"],
      "properties": {
        "sbomDigests": {
          "type": "array",
          "description": "SHA256 digests of SBOM documents used",
          "items": {
            "type": "string",
            "pattern": "^sha256:[a-f0-9]{64}$"
          }
        },
        "vulnFeedSnapshotIds": {
          "type": "array",
          "description": "Identifiers for vulnerability feed snapshots",
          "items": {
            "type": "string"
          }
        },
        "vexDocumentDigests": {
          "type": "array",
          "description": "SHA256 digests of VEX documents considered",
          "items": {
            "type": "string",
            "pattern": "^sha256:[a-f0-9]{64}$"
          }
        },
        "reachabilityGraphIds": {
          "type": "array",
          "description": "Identifiers for call graph snapshots",
          "items": {
            "type": "string"
          }
        },
        "clockCutoff": {
          "type": "string",
          "description": "Timestamp used for freshness calculations",
          "format": "date-time"
        }
      }
    },
    "VerdictResult": {
      "type": "object",
      "description": "The verdict and explanation",
      "required": ["status", "confidence", "explanations"],
      "properties": {
        "status": {
          "type": "string",
          "description": "Final verdict status",
          "enum": ["affected", "not_affected", "fixed", "under_investigation"]
        },
        "confidence": {
          "type": "number",
          "description": "Numeric confidence score",
          "minimum": 0,
          "maximum": 1
        },
        "explanations": {
          "type": "array",
          "description": "Per-source breakdown of scoring",
          "items": {
            "$ref": "#/$defs/VerdictExplanation"
          }
        },
        "evidenceRefs": {
          "type": "array",
          "description": "Links to attestations and proof bundles",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "VerdictExplanation": {
      "type": "object",
      "description": "Explanation of how a source contributed to the verdict",
      "required": ["sourceId", "reason", "claimScore"],
      "properties": {
        "sourceId": {
          "type": "string",
          "description": "Identifier of the VEX source"
        },
        "reason": {
          "type": "string",
          "description": "Human-readable explanation"
        },
        "provenanceScore": {
          "type": "number",
          "description": "Provenance component of trust vector",
          "minimum": 0,
          "maximum": 1
        },
        "coverageScore": {
          "type": "number",
          "description": "Coverage component of trust vector",
          "minimum": 0,
          "maximum": 1
        },
        "replayabilityScore": {
          "type": "number",
          "description": "Replayability component of trust vector",
          "minimum": 0,
          "maximum": 1
        },
        "strengthMultiplier": {
          "type": "number",
          "description": "Claim strength multiplier (M)",
          "minimum": 0,
          "maximum": 1
        },
        "freshnessMultiplier": {
          "type": "number",
          "description": "Freshness decay multiplier (F)",
          "minimum": 0,
          "maximum": 1
        },
        "claimScore": {
          "type": "number",
          "description": "Final claim score = BaseTrust * M * F",
          "minimum": 0,
          "maximum": 1
        }
      }
    }
  }
}