{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://stellaops.dev/schemas/stellaops.suppression.v1.schema.json",
  "title": "StellaOps Suppression Witness v1",
  "description": "A DSSE-signable suppression witness documenting why a vulnerability is not exploitable",
  "type": "object",
  "required": [
    "witness_schema",
    "witness_id",
    "artifact",
    "vuln",
    "suppression_type",
    "evidence",
    "confidence",
    "observed_at"
  ],
  "properties": {
    "witness_schema": {
      "type": "string",
      "const": "stellaops.suppression.v1",
      "description": "Schema version identifier"
    },
    "witness_id": {
      "type": "string",
      "pattern": "^sup:sha256:[a-f0-9]{64}$",
      "description": "Content-addressed witness ID (e.g., 'sup:sha256:...')"
    },
    "artifact": {
      "$ref": "#/definitions/WitnessArtifact",
      "description": "The artifact (SBOM, component) this witness relates to"
    },
    "vuln": {
      "$ref": "#/definitions/WitnessVuln",
      "description": "The vulnerability this witness concerns"
    },
    "suppression_type": {
      "type": "string",
      "enum": [
        "Unreachable",
        "LinkerGarbageCollected",
        "FeatureFlagDisabled",
        "PatchedSymbol",
        "GateBlocked",
        "CompileTimeExcluded",
        "VexNotAffected",
        "FunctionAbsent",
        "VersionNotAffected",
        "PlatformNotAffected"
      ],
      "description": "The type of suppression (unreachable, patched, gate-blocked, etc.)"
    },
    "evidence": {
      "$ref": "#/definitions/SuppressionEvidence",
      "description": "Evidence supporting the suppression claim"
    },
    "confidence": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 1.0,
      "description": "Confidence level in this suppression [0.0, 1.0]"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "Optional expiration date for time-bounded suppressions (UTC ISO-8601)"
    },
    "observed_at": {
      "type": "string",
      "format": "date-time",
      "description": "When this witness was generated (UTC ISO-8601)"
    },
    "justification": {
      "type": "string",
      "description": "Optional justification narrative"
    }
  },
  "additionalProperties": false,
  "definitions": {
    "WitnessArtifact": {
      "type": "object",
      "required": ["sbom_digest", "component_purl"],
      "properties": {
        "sbom_digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "SHA-256 digest of the SBOM"
        },
        "component_purl": {
          "type": "string",
          "pattern": "^pkg:",
          "description": "Package URL of the vulnerable component"
        }
      },
      "additionalProperties": false
    },
    "WitnessVuln": {
      "type": "object",
      "required": ["id", "source", "affected_range"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Vulnerability identifier (e.g., 'CVE-2024-12345')"
        },
        "source": {
          "type": "string",
          "description": "Vulnerability source (e.g., 'NVD', 'OSV', 'GHSA')"
        },
        "affected_range": {
          "type": "string",
          "description": "Affected version range expression"
        }
      },
      "additionalProperties": false
    },
    "SuppressionEvidence": {
      "type": "object",
      "required": ["witness_evidence"],
      "properties": {
        "witness_evidence": {
          "$ref": "#/definitions/WitnessEvidence"
        },
        "unreachability": {
          "$ref": "#/definitions/UnreachabilityEvidence"
        },
        "patched_symbol": {
          "$ref": "#/definitions/PatchedSymbolEvidence"
        },
        "function_absent": {
          "$ref": "#/definitions/FunctionAbsentEvidence"
        },
        "gate_blocked": {
          "$ref": "#/definitions/GateBlockedEvidence"
        },
        "feature_flag": {
          "$ref": "#/definitions/FeatureFlagEvidence"
        },
        "vex_statement": {
          "$ref": "#/definitions/VexStatementEvidence"
        },
        "version_range": {
          "$ref": "#/definitions/VersionRangeEvidence"
        },
        "linker_gc": {
          "$ref": "#/definitions/LinkerGcEvidence"
        }
      },
      "additionalProperties": false
    },
    "WitnessEvidence": {
      "type": "object",
      "required": ["callgraph_digest"],
      "properties": {
        "callgraph_digest": {
          "type": "string",
          "description": "BLAKE3 digest of the call graph used"
        },
        "surface_digest": {
          "type": "string",
          "description": "SHA-256 digest of the attack surface manifest"
        },
        "analysis_config_digest": {
          "type": "string",
          "description": "SHA-256 digest of the analysis configuration"
        },
        "build_id": {
          "type": "string",
          "description": "Build identifier for the analyzed artifact"
        }
      },
      "additionalProperties": false
    },
    "UnreachabilityEvidence": {
      "type": "object",
      "required": ["analyzed_entrypoints", "unreachable_symbol", "analysis_method", "graph_digest"],
      "properties": {
        "analyzed_entrypoints": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of entrypoints analyzed"
        },
        "unreachable_symbol": {
          "type": "string",
          "description": "Vulnerable symbol that was confirmed unreachable"
        },
        "analysis_method": {
          "type": "string",
          "description": "Analysis method (static, dynamic, hybrid)"
        },
        "graph_digest": {
          "type": "string",
          "description": "Graph digest for reproducibility"
        }
      },
      "additionalProperties": false
    },
    "FunctionAbsentEvidence": {
      "type": "object",
      "required": ["function_name", "binary_digest", "verification_method"],
      "properties": {
        "function_name": {
          "type": "string",
          "description": "Vulnerable function name"
        },
        "binary_digest": {
          "type": "string",
          "description": "Binary digest where function was checked"
        },
        "verification_method": {
          "type": "string",
          "description": "Verification method (symbol table scan, disassembly, etc.)"
        }
      },
      "additionalProperties": false
    },
    "GateBlockedEvidence": {
      "type": "object",
      "required": ["detected_gates", "gate_coverage_percent", "effectiveness"],
      "properties": {
        "detected_gates": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/DetectedGate"
          },
          "description": "Detected gates along all paths to vulnerable code"
        },
        "gate_coverage_percent": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "description": "Minimum gate coverage percentage [0, 100]"
        },
        "effectiveness": {
          "type": "string",
          "description": "Gate effectiveness assessment"
        }
      },
      "additionalProperties": false
    },
    "DetectedGate": {
      "type": "object",
      "required": ["type", "guard_symbol", "confidence"],
      "properties": {
        "type": {
          "type": "string",
          "description": "Gate type (authRequired, inputValidation, rateLimited, etc.)"
        },
        "guard_symbol": {
          "type": "string",
          "description": "Symbol that implements the gate"
        },
        "confidence": {
          "type": "number",
          "minimum": 0.0,
          "maximum": 1.0,
          "description": "Confidence level (0.0 - 1.0)"
        },
        "detail": {
          "type": "string",
          "description": "Human-readable detail about the gate"
        }
      },
      "additionalProperties": false
    },
    "PatchedSymbolEvidence": {
      "type": "object",
      "required": ["vulnerable_symbol", "patched_symbol", "symbol_diff"],
      "properties": {
        "vulnerable_symbol": {
          "type": "string",
          "description": "Vulnerable symbol identifier"
        },
        "patched_symbol": {
          "type": "string",
          "description": "Patched symbol identifier"
        },
        "symbol_diff": {
          "type": "string",
          "description": "Symbol diff showing the patch"
        },
        "patch_ref": {
          "type": "string",
          "description": "Patch commit or release reference"
        }
      },
      "additionalProperties": false
    },
    "VexStatementEvidence": {
      "type": "object",
      "required": ["vex_id", "vex_author", "vex_status", "vex_digest"],
      "properties": {
        "vex_id": {
          "type": "string",
          "description": "VEX statement identifier"
        },
        "vex_author": {
          "type": "string",
          "description": "VEX statement author/authority"
        },
        "vex_status": {
          "type": "string",
          "enum": ["not_affected", "fixed"],
          "description": "VEX statement status"
        },
        "vex_digest": {
          "type": "string",
          "description": "Content digest of the VEX document"
        }
      },
      "additionalProperties": false
    },
    "FeatureFlagEvidence": {
      "type": "object",
      "required": ["flag_name", "flag_state", "verification_source"],
      "properties": {
        "flag_name": {
          "type": "string",
          "description": "Feature flag name/key"
        },
        "flag_state": {
          "type": "string",
          "description": "Feature flag state (off, disabled)"
        },
        "verification_source": {
          "type": "string",
          "description": "Source of flag verification (config file, runtime)"
        }
      },
      "additionalProperties": false
    },
    "VersionRangeEvidence": {
      "type": "object",
      "required": ["actual_version", "affected_range", "comparison_method"],
      "properties": {
        "actual_version": {
          "type": "string",
          "description": "Actual version of the component"
        },
        "affected_range": {
          "type": "string",
          "description": "Affected version range from advisory"
        },
        "comparison_method": {
          "type": "string",
          "description": "Version comparison method used"
        }
      },
      "additionalProperties": false
    },
    "LinkerGcEvidence": {
      "type": "object",
      "required": ["removed_symbol", "linker_method", "verification_digest"],
      "properties": {
        "removed_symbol": {
          "type": "string",
          "description": "Symbol removed by linker GC"
        },
        "linker_method": {
          "type": "string",
          "description": "Linker garbage collection method"
        },
        "verification_digest": {
          "type": "string",
          "description": "Digest of final binary for verification"
        }
      },
      "additionalProperties": false
    }
  }
}