feat(api): Add Policy Registry API specification
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
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.
This commit is contained in:
StellaOps Bot
564
docs/schemas/reachability-input.schema.json
Normal file
564
docs/schemas/reachability-input.schema.json
Normal file
@@ -0,0 +1,564 @@
|
||||
{
|
||||
"$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"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user