Files
git.stella-ops.org/docs/schemas/signals-integration.schema.json
StellaOps Bot dd0067ea0b
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Refactor code structure for improved readability and maintainability
2025-12-06 21:48:12 +02:00

902 lines
23 KiB
JSON

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stella-ops.org/schemas/signals-integration.schema.json",
"title": "StellaOps Signals Integration Schema",
"description": "Schema for runtime signals integration, callgraph formats, and signal weighting. Unblocks DOCS-SIG-26-001 through DOCS-SIG-26-007.",
"type": "object",
"definitions": {
"SignalState": {
"type": "string",
"enum": [
"active",
"inactive",
"pending",
"stale",
"error",
"unknown"
],
"description": "Current state of a signal"
},
"SignalScore": {
"type": "object",
"description": "Computed signal score with confidence",
"required": ["value", "confidence"],
"properties": {
"value": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Normalized score value (0-1)"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Confidence level in the score"
},
"raw_value": {
"type": "number",
"description": "Original unnormalized value"
},
"components": {
"type": "array",
"items": {
"$ref": "#/definitions/ScoreComponent"
}
}
}
},
"ScoreComponent": {
"type": "object",
"description": "Individual component contributing to score",
"properties": {
"name": {
"type": "string"
},
"weight": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"contribution": {
"type": "number"
},
"source": {
"type": "string"
}
}
},
"RuntimeSignal": {
"type": "object",
"description": "Runtime observation signal from instrumented application",
"required": ["signal_id", "signal_type", "observed_at"],
"properties": {
"signal_id": {
"type": "string",
"format": "uuid"
},
"signal_type": {
"$ref": "#/definitions/RuntimeSignalType"
},
"state": {
"$ref": "#/definitions/SignalState"
},
"score": {
"$ref": "#/definitions/SignalScore"
},
"subject": {
"$ref": "#/definitions/SignalSubject"
},
"observation": {
"$ref": "#/definitions/RuntimeObservation"
},
"environment": {
"$ref": "#/definitions/RuntimeEnvironment"
},
"retention": {
"$ref": "#/definitions/SignalRetention"
},
"observed_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true
}
}
},
"RuntimeSignalType": {
"type": "string",
"enum": [
"function_invocation",
"code_path_execution",
"module_load",
"dependency_resolution",
"network_call",
"file_access",
"database_query",
"crypto_operation",
"serialization",
"reflection",
"dynamic_code",
"process_spawn",
"memory_allocation",
"exception_thrown"
]
},
"SignalSubject": {
"type": "object",
"description": "Subject of the signal (what was observed)",
"properties": {
"purl": {
"type": "string",
"description": "Package URL of component"
},
"symbol": {
"type": "string",
"description": "Fully qualified symbol name"
},
"file": {
"type": "string"
},
"line": {
"type": "integer"
},
"module": {
"type": "string"
},
"class": {
"type": "string"
},
"method": {
"type": "string"
},
"cve_id": {
"type": "string",
"pattern": "^CVE-[0-9]{4}-[0-9]+$"
}
}
},
"RuntimeObservation": {
"type": "object",
"description": "Details of the runtime observation",
"properties": {
"call_count": {
"type": "integer",
"minimum": 0
},
"first_seen": {
"type": "string",
"format": "date-time"
},
"last_seen": {
"type": "string",
"format": "date-time"
},
"observation_window": {
"type": "string",
"description": "Duration of observation (e.g., '7d', '30d')"
},
"sample_rate": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Sampling rate if not 100%"
},
"call_stack": {
"type": "array",
"items": {
"$ref": "#/definitions/StackFrame"
}
},
"arguments": {
"type": "array",
"items": {
"$ref": "#/definitions/ArgumentSummary"
}
}
}
},
"StackFrame": {
"type": "object",
"description": "Stack frame in call stack",
"properties": {
"symbol": {
"type": "string"
},
"file": {
"type": "string"
},
"line": {
"type": "integer"
},
"module": {
"type": "string"
}
}
},
"ArgumentSummary": {
"type": "object",
"description": "Summary of argument (privacy-preserving)",
"properties": {
"position": {
"type": "integer"
},
"type": {
"type": "string"
},
"is_sensitive": {
"type": "boolean",
"default": false
},
"hash": {
"type": "string",
"description": "Hash of value for correlation"
}
}
},
"RuntimeEnvironment": {
"type": "object",
"description": "Runtime environment context",
"properties": {
"environment": {
"type": "string",
"enum": ["production", "staging", "development", "test"]
},
"deployment_id": {
"type": "string"
},
"instance_id": {
"type": "string"
},
"region": {
"type": "string"
},
"runtime": {
"type": "string",
"description": "Runtime platform (e.g., 'node-20.10', 'python-3.12')"
},
"container_id": {
"type": "string"
},
"pod_name": {
"type": "string"
}
}
},
"SignalRetention": {
"type": "object",
"description": "Retention policy for signal data",
"properties": {
"retention_days": {
"type": "integer",
"minimum": 1,
"default": 30
},
"aggregation_after_days": {
"type": "integer",
"description": "Days after which to aggregate raw data"
},
"privacy_policy": {
"type": "string",
"enum": ["full", "anonymized", "aggregated_only"]
}
}
},
"CallgraphFormat": {
"type": "object",
"description": "Callgraph representation format",
"required": ["format", "version"],
"properties": {
"format": {
"type": "string",
"enum": ["richgraph-v1", "dot", "json-graph", "sarif", "spdx-lite"],
"description": "Callgraph serialization format"
},
"version": {
"type": "string"
},
"generator": {
"type": "string"
},
"generator_version": {
"type": "string"
}
}
},
"Callgraph": {
"type": "object",
"description": "Static or dynamic callgraph",
"required": ["callgraph_id", "format", "nodes"],
"properties": {
"callgraph_id": {
"type": "string",
"format": "uuid"
},
"format": {
"$ref": "#/definitions/CallgraphFormat"
},
"analysis_type": {
"type": "string",
"enum": ["static", "dynamic", "hybrid"]
},
"nodes": {
"type": "array",
"items": {
"$ref": "#/definitions/CallgraphNode"
}
},
"edges": {
"type": "array",
"items": {
"$ref": "#/definitions/CallgraphEdge"
}
},
"entry_points": {
"type": "array",
"items": {
"type": "string"
},
"description": "Node IDs of entry points"
},
"vulnerable_nodes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Node IDs of vulnerable symbols"
},
"statistics": {
"$ref": "#/definitions/CallgraphStatistics"
},
"digest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"generated_at": {
"type": "string",
"format": "date-time"
}
}
},
"CallgraphNode": {
"type": "object",
"description": "Node in callgraph",
"required": ["id", "symbol"],
"properties": {
"id": {
"type": "string"
},
"symbol": {
"type": "string",
"description": "Fully qualified symbol name"
},
"type": {
"type": "string",
"enum": ["function", "method", "class", "module", "package", "external"]
},
"file": {
"type": "string"
},
"line_start": {
"type": "integer"
},
"line_end": {
"type": "integer"
},
"package": {
"type": "string"
},
"purl": {
"type": "string"
},
"is_entry_point": {
"type": "boolean",
"default": false
},
"is_vulnerable": {
"type": "boolean",
"default": false
},
"is_sink": {
"type": "boolean",
"default": false
},
"vulnerability_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"attributes": {
"type": "object",
"additionalProperties": true
}
}
},
"CallgraphEdge": {
"type": "object",
"description": "Edge in callgraph",
"required": ["source", "target"],
"properties": {
"source": {
"type": "string",
"description": "Source node ID"
},
"target": {
"type": "string",
"description": "Target node ID"
},
"call_type": {
"type": "string",
"enum": ["direct", "indirect", "virtual", "reflection", "dynamic", "callback", "async"]
},
"weight": {
"type": "number",
"minimum": 0,
"description": "Edge weight for path analysis"
},
"call_site": {
"type": "object",
"properties": {
"file": { "type": "string" },
"line": { "type": "integer" }
}
},
"observed_count": {
"type": "integer",
"description": "Call count if from dynamic analysis"
}
}
},
"CallgraphStatistics": {
"type": "object",
"description": "Statistics about callgraph",
"properties": {
"total_nodes": {
"type": "integer"
},
"total_edges": {
"type": "integer"
},
"entry_point_count": {
"type": "integer"
},
"vulnerable_node_count": {
"type": "integer"
},
"max_depth": {
"type": "integer"
},
"coverage_percent": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"packages_analyzed": {
"type": "integer"
}
}
},
"CallgraphValidationError": {
"type": "object",
"description": "Validation error in callgraph",
"required": ["code", "message"],
"properties": {
"code": {
"type": "string",
"enum": [
"INVALID_FORMAT",
"MISSING_REQUIRED_FIELD",
"INVALID_NODE_REFERENCE",
"CYCLE_DETECTED",
"ORPHAN_NODE",
"DUPLICATE_NODE_ID",
"INVALID_SYMBOL_FORMAT",
"UNSUPPORTED_VERSION",
"INCOMPLETE_COVERAGE"
]
},
"message": {
"type": "string"
},
"path": {
"type": "string",
"description": "JSON path to error location"
},
"node_id": {
"type": "string"
},
"severity": {
"type": "string",
"enum": ["error", "warning", "info"]
}
}
},
"SignalWeightingConfig": {
"type": "object",
"description": "Configuration for signal weighting in policy evaluation",
"required": ["config_id", "weights"],
"properties": {
"config_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"weights": {
"type": "array",
"items": {
"$ref": "#/definitions/SignalWeight"
}
},
"decay_function": {
"$ref": "#/definitions/DecayFunction"
},
"aggregation_method": {
"type": "string",
"enum": ["weighted_average", "max", "min", "product", "custom"],
"default": "weighted_average"
},
"thresholds": {
"$ref": "#/definitions/SignalThresholds"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"effective_from": {
"type": "string",
"format": "date-time"
},
"effective_until": {
"type": "string",
"format": "date-time"
}
}
},
"SignalWeight": {
"type": "object",
"description": "Weight configuration for a signal type",
"required": ["signal_type", "weight"],
"properties": {
"signal_type": {
"$ref": "#/definitions/RuntimeSignalType"
},
"weight": {
"type": "number",
"minimum": 0,
"maximum": 10,
"description": "Weight multiplier for this signal type"
},
"min_observations": {
"type": "integer",
"minimum": 1,
"default": 1,
"description": "Minimum observations before signal is considered"
},
"confidence_boost": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Boost to apply when high confidence"
},
"environment_modifiers": {
"type": "object",
"additionalProperties": {
"type": "number"
},
"description": "Weight modifiers by environment (e.g., production: 1.5)"
}
}
},
"DecayFunction": {
"type": "object",
"description": "Time decay function for signal freshness",
"properties": {
"type": {
"type": "string",
"enum": ["linear", "exponential", "step", "none"],
"default": "exponential"
},
"half_life_hours": {
"type": "integer",
"minimum": 1,
"default": 168,
"description": "Hours for signal to decay to 50% weight"
},
"min_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.1,
"description": "Minimum weight after decay"
},
"max_age_hours": {
"type": "integer",
"description": "Maximum age before signal is ignored"
}
}
},
"SignalThresholds": {
"type": "object",
"description": "Thresholds for signal-based decisions",
"properties": {
"reachable_threshold": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7,
"description": "Score above which symbol is considered reachable"
},
"unreachable_threshold": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.3,
"description": "Score below which symbol is considered unreachable"
},
"confidence_minimum": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.5,
"description": "Minimum confidence to use signal"
}
}
},
"SignalOverlay": {
"type": "object",
"description": "UI overlay data for signal visualization",
"required": ["overlay_id", "component"],
"properties": {
"overlay_id": {
"type": "string",
"format": "uuid"
},
"component": {
"type": "string",
"description": "PURL or component identifier"
},
"display": {
"$ref": "#/definitions/OverlayDisplay"
},
"badges": {
"type": "array",
"items": {
"$ref": "#/definitions/SignalBadge"
}
},
"timeline_events": {
"type": "array",
"items": {
"$ref": "#/definitions/TimelineOverlayEvent"
}
},
"shortcuts": {
"type": "array",
"items": {
"$ref": "#/definitions/OverlayShortcut"
}
}
}
},
"OverlayDisplay": {
"type": "object",
"description": "Display properties for overlay",
"properties": {
"reachability_state": {
"type": "string",
"enum": ["reachable", "unreachable", "potentially_reachable", "unknown"]
},
"reachability_icon": {
"type": "string",
"enum": ["check", "x", "question", "warning"]
},
"reachability_color": {
"type": "string",
"enum": ["green", "red", "yellow", "gray"]
},
"confidence_display": {
"type": "string",
"enum": ["high", "medium", "low"]
},
"last_observed_label": {
"type": "string"
}
}
},
"SignalBadge": {
"type": "object",
"description": "Badge to display on component",
"properties": {
"type": {
"type": "string",
"enum": ["reachability", "runtime", "coverage", "age", "confidence"]
},
"label": {
"type": "string"
},
"value": {
"type": "string"
},
"color": {
"type": "string"
},
"tooltip": {
"type": "string"
}
}
},
"TimelineOverlayEvent": {
"type": "object",
"description": "Event for timeline visualization",
"properties": {
"timestamp": {
"type": "string",
"format": "date-time"
},
"event_type": {
"type": "string"
},
"label": {
"type": "string"
},
"details": {
"type": "string"
}
}
},
"OverlayShortcut": {
"type": "object",
"description": "Keyboard/UI shortcut pattern",
"properties": {
"key": {
"type": "string"
},
"action": {
"type": "string"
},
"description": {
"type": "string"
}
}
},
"SignalAPIEndpoint": {
"type": "object",
"description": "API endpoint specification for signals",
"required": ["path", "method"],
"properties": {
"path": {
"type": "string"
},
"method": {
"type": "string",
"enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
},
"description": {
"type": "string"
},
"request_schema": {
"type": "string",
"description": "JSON Schema reference"
},
"response_schema": {
"type": "string",
"description": "JSON Schema reference"
},
"error_model": {
"$ref": "#/definitions/SignalAPIError"
},
"etag_support": {
"type": "boolean",
"default": true
}
}
},
"SignalAPIError": {
"type": "object",
"description": "API error response",
"required": ["code", "message"],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
},
"request_id": {
"type": "string"
}
}
}
},
"properties": {
"signals": {
"type": "array",
"items": {
"$ref": "#/definitions/RuntimeSignal"
}
},
"callgraphs": {
"type": "array",
"items": {
"$ref": "#/definitions/Callgraph"
}
},
"weighting_config": {
"$ref": "#/definitions/SignalWeightingConfig"
}
},
"examples": [
{
"signals": [
{
"signal_id": "550e8400-e29b-41d4-a716-446655440001",
"signal_type": "function_invocation",
"state": "active",
"score": {
"value": 0.85,
"confidence": 0.92
},
"subject": {
"purl": "pkg:npm/lodash@4.17.21",
"symbol": "lodash.template",
"cve_id": "CVE-2021-23337"
},
"observation": {
"call_count": 1247,
"first_seen": "2025-11-01T00:00:00Z",
"last_seen": "2025-12-06T10:00:00Z",
"observation_window": "30d"
},
"environment": {
"environment": "production",
"runtime": "node-20.10"
},
"observed_at": "2025-12-06T10:00:00Z"
}
],
"weighting_config": {
"config_id": "660e8400-e29b-41d4-a716-446655440002",
"name": "default-production",
"weights": [
{
"signal_type": "function_invocation",
"weight": 2.0,
"min_observations": 10,
"environment_modifiers": {
"production": 1.5,
"staging": 1.0,
"development": 0.5
}
}
],
"decay_function": {
"type": "exponential",
"half_life_hours": 168,
"min_weight": 0.1
},
"thresholds": {
"reachable_threshold": 0.7,
"unreachable_threshold": 0.3,
"confidence_minimum": 0.5
}
}
}
]
}