{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stella-ops.org/schemas/reachability-input.schema.json",
  "title": "StellaOps Reachability Input Schema",
  "description": "Schema for reachability/exploitability signals input to Policy Engine. Unblocks POLICY-ENGINE-80-001, POLICY-RISK-66-003.",
  "type": "object",
  "definitions": {
    "ReachabilityInput": {
      "type": "object",
      "description": "Input payload for policy engine reachability evaluation",
      "required": ["subject", "reachability_facts", "timestamp"],
      "properties": {
        "subject": {
          "$ref": "#/definitions/Subject"
        },
        "reachability_facts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ReachabilityFact"
          }
        },
        "exploitability_facts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ExploitabilityFact"
          }
        },
        "callgraph_refs": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/CallgraphRef"
          }
        },
        "runtime_facts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/RuntimeFact"
          }
        },
        "entropy_score": {
          "$ref": "#/definitions/EntropyScore"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "Subject": {
      "type": "object",
      "description": "Subject being evaluated (component + vulnerability)",
      "required": ["purl"],
      "properties": {
        "purl": {
          "type": "string",
          "description": "Package URL of the component"
        },
        "cve_id": {
          "type": "string",
          "pattern": "^CVE-[0-9]{4}-[0-9]+$"
        },
        "ghsa_id": {
          "type": "string",
          "pattern": "^GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}$"
        },
        "vulnerability_id": {
          "type": "string",
          "description": "Internal vulnerability identifier"
        },
        "affected_symbols": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Vulnerable symbols/functions in the component"
        },
        "version_range": {
          "type": "string",
          "description": "Affected version range (e.g., '<1.2.3')"
        }
      }
    },
    "ReachabilityFact": {
      "type": "object",
      "description": "Static reachability analysis result",
      "required": ["state", "confidence"],
      "properties": {
        "state": {
          "type": "string",
          "enum": ["reachable", "unreachable", "potentially_reachable", "unknown"],
          "description": "Reachability state"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Confidence score (0-1)"
        },
        "source": {
          "type": "string",
          "enum": ["static_analysis", "dynamic_analysis", "sbom_inference", "manual", "external"],
          "description": "Source of the reachability determination"
        },
        "analyzer": {
          "type": "string",
          "description": "Analyzer tool that produced this fact"
        },
        "analyzer_version": {
          "type": "string"
        },
        "call_path": {
          "$ref": "#/definitions/CallPath"
        },
        "entry_points": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/EntryPoint"
          }
        },
        "evidence": {
          "$ref": "#/definitions/ReachabilityEvidence"
        },
        "evaluated_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "CallPath": {
      "type": "object",
      "description": "Call path from entry point to vulnerable symbol",
      "properties": {
        "depth": {
          "type": "integer",
          "minimum": 0,
          "description": "Call depth from entry point"
        },
        "nodes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/CallNode"
          }
        },
        "edges": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/CallEdge"
          }
        }
      }
    },
    "CallNode": {
      "type": "object",
      "required": ["id", "symbol"],
      "properties": {
        "id": {
          "type": "string"
        },
        "symbol": {
          "type": "string",
          "description": "Fully qualified symbol name"
        },
        "file": {
          "type": "string"
        },
        "line": {
          "type": "integer"
        },
        "package": {
          "type": "string"
        },
        "is_vulnerable": {
          "type": "boolean"
        },
        "is_entry_point": {
          "type": "boolean"
        }
      }
    },
    "CallEdge": {
      "type": "object",
      "required": ["source", "target"],
      "properties": {
        "source": {
          "type": "string"
        },
        "target": {
          "type": "string"
        },
        "call_type": {
          "type": "string",
          "enum": ["direct", "indirect", "virtual", "reflection", "dynamic"]
        }
      }
    },
    "EntryPoint": {
      "type": "object",
      "description": "Application entry point that can reach vulnerable code",
      "required": ["type", "identifier"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["http_endpoint", "grpc_method", "cli_command", "event_handler", "scheduled_job", "main", "test"]
        },
        "identifier": {
          "type": "string",
          "description": "Entry point identifier (e.g., 'POST /api/users')"
        },
        "file": {
          "type": "string"
        },
        "line": {
          "type": "integer"
        },
        "exposed": {
          "type": "boolean",
          "default": true,
          "description": "Whether this entry point is externally exposed"
        },
        "authentication_required": {
          "type": "boolean"
        }
      }
    },
    "ReachabilityEvidence": {
      "type": "object",
      "description": "Supporting evidence for reachability determination",
      "properties": {
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "evidence_uri": {
          "type": "string",
          "format": "uri"
        },
        "callgraph_digest": {
          "type": "string"
        },
        "sbom_digest": {
          "type": "string"
        },
        "analysis_log_uri": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "ExploitabilityFact": {
      "type": "object",
      "description": "Exploitability assessment",
      "required": ["state", "confidence"],
      "properties": {
        "state": {
          "type": "string",
          "enum": ["exploitable", "not_exploitable", "conditionally_exploitable", "unknown"]
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "source": {
          "type": "string",
          "enum": ["kev", "epss", "vendor_advisory", "internal_analysis", "exploit_db"]
        },
        "epss_score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "EPSS probability score"
        },
        "epss_percentile": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        "kev_listed": {
          "type": "boolean",
          "description": "Listed in CISA Known Exploited Vulnerabilities"
        },
        "kev_due_date": {
          "type": "string",
          "format": "date"
        },
        "exploit_maturity": {
          "type": "string",
          "enum": ["not_defined", "unproven", "poc", "functional", "high"],
          "description": "Exploit maturity level (per CVSS)"
        },
        "exploit_refs": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uri"
          }
        },
        "conditions": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ExploitCondition"
          },
          "description": "Conditions required for exploitation"
        },
        "evaluated_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "ExploitCondition": {
      "type": "object",
      "description": "Condition required for exploitation",
      "required": ["condition", "met"],
      "properties": {
        "condition": {
          "type": "string",
          "description": "Description of the condition"
        },
        "met": {
          "type": "boolean"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "evidence": {
          "type": "string"
        }
      }
    },
    "CallgraphRef": {
      "type": "object",
      "description": "Reference to a stored callgraph",
      "required": ["digest"],
      "properties": {
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "format": {
          "type": "string",
          "enum": ["richgraph-v1", "dot", "json-graph", "sarif"],
          "default": "richgraph-v1"
        },
        "uri": {
          "type": "string",
          "format": "uri"
        },
        "generated_at": {
          "type": "string",
          "format": "date-time"
        },
        "generator": {
          "type": "string"
        },
        "generator_version": {
          "type": "string"
        }
      }
    },
    "RuntimeFact": {
      "type": "object",
      "description": "Runtime observation fact",
      "required": ["type", "observed_at"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["function_called", "function_not_called", "path_executed", "path_not_executed", "module_loaded", "module_not_loaded"]
        },
        "symbol": {
          "type": "string"
        },
        "module": {
          "type": "string"
        },
        "call_count": {
          "type": "integer",
          "minimum": 0
        },
        "last_called": {
          "type": "string",
          "format": "date-time"
        },
        "observed_at": {
          "type": "string",
          "format": "date-time"
        },
        "observation_window": {
          "type": "string",
          "description": "Duration of observation (e.g., '7d', '30d')"
        },
        "environment": {
          "type": "string",
          "enum": ["production", "staging", "development", "test"]
        }
      }
    },
    "EntropyScore": {
      "type": "object",
      "description": "Scanner entropy/trust score for confidence weighting",
      "properties": {
        "overall": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Overall trust score"
        },
        "sbom_completeness": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "callgraph_coverage": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "runtime_coverage": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "analyzer_confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "data_freshness": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "How recent the underlying data is"
        }
      }
    },
    "ReachabilityOutput": {
      "type": "object",
      "description": "Policy engine output after reachability evaluation",
      "required": ["subject", "effective_state", "risk_adjustment"],
      "properties": {
        "subject": {
          "$ref": "#/definitions/Subject"
        },
        "effective_state": {
          "type": "string",
          "enum": ["reachable", "unreachable", "potentially_reachable", "unknown"]
        },
        "effective_exploitability": {
          "type": "string",
          "enum": ["exploitable", "not_exploitable", "conditionally_exploitable", "unknown"]
        },
        "risk_adjustment": {
          "type": "object",
          "properties": {
            "factor": {
              "type": "number",
              "minimum": 0,
              "maximum": 2,
              "description": "Risk multiplier (0 = suppress, 1 = neutral, >1 = amplify)"
            },
            "severity_override": {
              "type": "string",
              "enum": ["critical", "high", "medium", "low", "info"]
            },
            "justification": {
              "type": "string"
            }
          }
        },
        "policy_trace": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "rule_id": { "type": "string" },
              "result": { "type": "string" },
              "reason": { "type": "string" }
            }
          }
        },
        "evaluated_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  },
  "properties": {
    "inputs": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/ReachabilityInput"
      }
    }
  },
  "examples": [
    {
      "inputs": [
        {
          "subject": {
            "purl": "pkg:npm/lodash@4.17.20",
            "cve_id": "CVE-2021-23337",
            "affected_symbols": ["lodash.template"]
          },
          "reachability_facts": [
            {
              "state": "reachable",
              "confidence": 0.95,
              "source": "static_analysis",
              "analyzer": "stellaops-scanner",
              "analyzer_version": "2025.10.0",
              "call_path": {
                "depth": 3,
                "nodes": [
                  { "id": "n1", "symbol": "app.renderTemplate", "is_entry_point": true },
                  { "id": "n2", "symbol": "templateEngine.compile" },
                  { "id": "n3", "symbol": "lodash.template", "is_vulnerable": true }
                ],
                "edges": [
                  { "source": "n1", "target": "n2", "call_type": "direct" },
                  { "source": "n2", "target": "n3", "call_type": "direct" }
                ]
              },
              "entry_points": [
                {
                  "type": "http_endpoint",
                  "identifier": "POST /api/render",
                  "exposed": true,
                  "authentication_required": true
                }
              ],
              "evaluated_at": "2025-12-06T10:00:00Z"
            }
          ],
          "exploitability_facts": [
            {
              "state": "exploitable",
              "confidence": 0.8,
              "source": "epss",
              "epss_score": 0.42,
              "epss_percentile": 87,
              "kev_listed": false,
              "exploit_maturity": "functional",
              "evaluated_at": "2025-12-06T10:00:00Z"
            }
          ],
          "entropy_score": {
            "overall": 0.85,
            "sbom_completeness": 0.95,
            "callgraph_coverage": 0.78,
            "analyzer_confidence": 0.9
          },
          "timestamp": "2025-12-06T10:00:00Z"
        }
      ]
    }
  ]
}