f6c22854a4
Some checks failed
AOC Guard CI / aoc-verify (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Findings Ledger CI / build-test (push) Has been cancelled
Findings Ledger CI / migration-validation (push) Has been cancelled
Findings Ledger CI / generate-manifest (push) Has been cancelled
mock-dev-release / package-mock-release (push) Has been cancelled
- Introduced OpenAPI specification for the StellaOps Policy Registry API, covering endpoints for verification policies, policy packs, snapshots, violations, overrides, sealed mode operations, and advisory staleness tracking. - Defined schemas, parameters, and responses for comprehensive API documentation. chore(scanner): Add global usings for scanner analyzers - Created GlobalUsings.cs to simplify namespace usage across analyzer libraries. feat(scanner): Implement Surface Service Collection Extensions - Added SurfaceServiceCollectionExtensions for dependency injection registration of surface analysis services. - Included methods for adding surface analysis, surface collectors, and entry point collectors to the service collection.
565 lines
15 KiB
JSON
565 lines
15 KiB
JSON
{
|
|
"$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"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|