Refactor code structure for improved readability and maintainability
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

This commit is contained in:
StellaOps Bot
2025-12-06 21:48:12 +02:00
parent f6c22854a4
commit dd0067ea0b
105 changed files with 12662 additions and 427 deletions

View File

@@ -0,0 +1,664 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stella-ops.org/schemas/evidence-pointer.schema.json",
"title": "StellaOps Evidence Pointer Schema",
"description": "Schema for evidence pointers used in timeline events, evidence locker snapshots, and DSSE attestations. Unblocks TASKRUN-OBS-52-001, TASKRUN-OBS-53-001, TASKRUN-OBS-54-001, TASKRUN-OBS-55-001.",
"type": "object",
"definitions": {
"EvidencePointer": {
"type": "object",
"description": "Pointer to evidence artifact in the evidence locker",
"required": ["pointer_id", "artifact_type", "digest", "created_at"],
"properties": {
"pointer_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for this evidence pointer"
},
"artifact_type": {
"$ref": "#/definitions/ArtifactType"
},
"digest": {
"$ref": "#/definitions/Digest"
},
"uri": {
"type": "string",
"format": "uri",
"description": "URI to retrieve the artifact (may be presigned)"
},
"storage_backend": {
"type": "string",
"enum": ["cas", "evidence", "attestation", "local", "s3", "azure-blob", "gcs"],
"description": "Storage backend where artifact resides"
},
"bucket": {
"type": "string",
"description": "Bucket/container name in object storage"
},
"key": {
"type": "string",
"description": "Object key/path within bucket"
},
"size_bytes": {
"type": "integer",
"minimum": 0,
"description": "Size of artifact in bytes"
},
"media_type": {
"type": "string",
"description": "MIME type of the artifact"
},
"compression": {
"type": "string",
"enum": ["none", "gzip", "zstd", "brotli"],
"default": "none"
},
"encryption": {
"$ref": "#/definitions/EncryptionInfo"
},
"chain_position": {
"$ref": "#/definitions/ChainPosition"
},
"provenance": {
"$ref": "#/definitions/EvidenceProvenance"
},
"redaction": {
"$ref": "#/definitions/RedactionInfo"
},
"retention": {
"$ref": "#/definitions/RetentionPolicy"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true
}
}
},
"ArtifactType": {
"type": "string",
"enum": [
"sbom",
"vex",
"attestation",
"signature",
"callgraph",
"scan_result",
"policy_evaluation",
"timeline_transcript",
"evidence_bundle",
"audit_log",
"manifest",
"provenance",
"rekor_receipt",
"runtime_trace",
"coverage_report",
"diff_report"
],
"description": "Type of evidence artifact"
},
"Digest": {
"type": "object",
"description": "Cryptographic digest of artifact content",
"required": ["algorithm", "value"],
"properties": {
"algorithm": {
"type": "string",
"enum": ["sha256", "sha384", "sha512", "sha3-256", "sha3-384", "sha3-512"],
"default": "sha256"
},
"value": {
"type": "string",
"pattern": "^[a-f0-9]+$",
"description": "Hex-encoded digest value"
}
}
},
"EncryptionInfo": {
"type": "object",
"description": "Encryption information for protected artifacts",
"properties": {
"encrypted": {
"type": "boolean",
"default": false
},
"algorithm": {
"type": "string",
"enum": ["AES-256-GCM", "ChaCha20-Poly1305"],
"description": "Encryption algorithm used"
},
"key_id": {
"type": "string",
"description": "Key identifier for decryption"
},
"key_provider": {
"type": "string",
"enum": ["kms", "vault", "local"],
"description": "Key management provider"
}
}
},
"ChainPosition": {
"type": "object",
"description": "Position in evidence hash chain for tamper detection",
"properties": {
"chain_id": {
"type": "string",
"format": "uuid",
"description": "Evidence chain identifier"
},
"sequence": {
"type": "integer",
"minimum": 0,
"description": "Sequence number in chain"
},
"previous_digest": {
"$ref": "#/definitions/Digest"
},
"merkle_root": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Merkle tree root at this position"
},
"merkle_proof": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"description": "Merkle inclusion proof"
},
"anchored_at": {
"type": "string",
"format": "date-time",
"description": "When chain was anchored to transparency log"
},
"anchor_receipt": {
"type": "string",
"description": "Receipt from transparency log (e.g., Rekor)"
}
}
},
"EvidenceProvenance": {
"type": "object",
"description": "Provenance information for evidence artifact",
"properties": {
"producer": {
"type": "string",
"description": "Service/component that produced the evidence"
},
"producer_version": {
"type": "string"
},
"build_id": {
"type": "string",
"description": "CI/CD build identifier"
},
"source_ref": {
"type": "string",
"description": "Source reference (e.g., git commit)"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"correlation_id": {
"type": "string",
"format": "uuid",
"description": "Trace correlation ID"
},
"parent_pointers": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Parent evidence pointers this derives from"
},
"attestation_id": {
"type": "string",
"format": "uuid",
"description": "Associated attestation if signed"
}
}
},
"RedactionInfo": {
"type": "object",
"description": "Redaction policy for evidence artifact",
"properties": {
"redaction_applied": {
"type": "boolean",
"default": false
},
"redaction_policy": {
"type": "string",
"description": "Policy identifier that was applied"
},
"redacted_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "JSON paths of redacted fields"
},
"original_digest": {
"$ref": "#/definitions/Digest"
},
"redaction_timestamp": {
"type": "string",
"format": "date-time"
}
}
},
"RetentionPolicy": {
"type": "object",
"description": "Retention policy for evidence artifact",
"properties": {
"policy_id": {
"type": "string"
},
"retention_days": {
"type": "integer",
"minimum": 1
},
"legal_hold": {
"type": "boolean",
"default": false
},
"deletion_scheduled_at": {
"type": "string",
"format": "date-time"
},
"immutable_until": {
"type": "string",
"format": "date-time",
"description": "Cannot be modified/deleted until this time"
}
}
},
"EvidenceSnapshot": {
"type": "object",
"description": "Point-in-time snapshot of evidence locker state",
"required": ["snapshot_id", "timestamp", "pointers"],
"properties": {
"snapshot_id": {
"type": "string",
"format": "uuid"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"snapshot_type": {
"type": "string",
"enum": ["full", "incremental", "incident"],
"default": "incremental"
},
"pointers": {
"type": "array",
"items": {
"$ref": "#/definitions/EvidencePointer"
}
},
"aggregate_digest": {
"$ref": "#/definitions/Digest"
},
"previous_snapshot_id": {
"type": "string",
"format": "uuid"
},
"statistics": {
"$ref": "#/definitions/SnapshotStatistics"
},
"manifest_uri": {
"type": "string",
"format": "uri"
},
"attestation": {
"$ref": "#/definitions/SnapshotAttestation"
}
}
},
"SnapshotStatistics": {
"type": "object",
"description": "Statistics about evidence snapshot",
"properties": {
"total_artifacts": {
"type": "integer",
"minimum": 0
},
"total_size_bytes": {
"type": "integer",
"minimum": 0
},
"artifacts_by_type": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"new_since_last": {
"type": "integer"
},
"modified_since_last": {
"type": "integer"
},
"deleted_since_last": {
"type": "integer"
}
}
},
"SnapshotAttestation": {
"type": "object",
"description": "DSSE attestation for snapshot integrity",
"properties": {
"attestation_id": {
"type": "string",
"format": "uuid"
},
"predicate_type": {
"type": "string",
"default": "https://stella-ops.org/attestations/evidence-snapshot/v1"
},
"signature": {
"type": "string",
"description": "Base64-encoded signature"
},
"key_id": {
"type": "string"
},
"signed_at": {
"type": "string",
"format": "date-time"
},
"rekor_log_index": {
"type": "integer",
"description": "Rekor transparency log index"
},
"rekor_log_id": {
"type": "string"
}
}
},
"TimelineEvidenceEntry": {
"type": "object",
"description": "Evidence entry in timeline event stream",
"required": ["entry_id", "event_type", "timestamp", "pointer"],
"properties": {
"entry_id": {
"type": "string",
"format": "uuid"
},
"event_type": {
"type": "string",
"enum": [
"evidence.created",
"evidence.updated",
"evidence.accessed",
"evidence.deleted",
"evidence.redacted",
"evidence.exported",
"evidence.verified",
"evidence.anchored",
"snapshot.created",
"snapshot.verified",
"incident.started",
"incident.ended"
]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"pointer": {
"$ref": "#/definitions/EvidencePointer"
},
"actor": {
"$ref": "#/definitions/Actor"
},
"context": {
"type": "object",
"properties": {
"pack_run_id": {
"type": "string",
"format": "uuid"
},
"scan_id": {
"type": "string",
"format": "uuid"
},
"job_id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
}
}
},
"previous_entry_id": {
"type": "string",
"format": "uuid"
}
}
},
"Actor": {
"type": "object",
"description": "Actor who performed the action",
"properties": {
"type": {
"type": "string",
"enum": ["user", "service", "system", "automation"]
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"tenant_id": {
"type": "string",
"format": "uuid"
}
}
},
"IncidentModeConfig": {
"type": "object",
"description": "Configuration for incident mode evidence capture",
"required": ["incident_id", "started_at"],
"properties": {
"incident_id": {
"type": "string",
"format": "uuid"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"ended_at": {
"type": "string",
"format": "date-time"
},
"severity": {
"type": "string",
"enum": ["critical", "high", "medium", "low"]
},
"capture_mode": {
"type": "string",
"enum": ["all", "selective", "enhanced"],
"default": "enhanced",
"description": "Level of evidence capture during incident"
},
"enhanced_retention_days": {
"type": "integer",
"minimum": 1,
"default": 365,
"description": "Extended retention for incident evidence"
},
"legal_hold": {
"type": "boolean",
"default": true
},
"snapshot_interval_minutes": {
"type": "integer",
"minimum": 1,
"default": 15,
"description": "How often to take snapshots during incident"
},
"affected_tenants": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"affected_components": {
"type": "array",
"items": {
"type": "string"
}
},
"root_cause_evidence": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Pointer IDs of root cause evidence"
}
}
},
"EvidenceQuery": {
"type": "object",
"description": "Query parameters for evidence retrieval",
"properties": {
"artifact_types": {
"type": "array",
"items": {
"$ref": "#/definitions/ArtifactType"
}
},
"digest": {
"$ref": "#/definitions/Digest"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"correlation_id": {
"type": "string",
"format": "uuid"
},
"time_range": {
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
}
}
},
"include_redacted": {
"type": "boolean",
"default": false
},
"include_expired": {
"type": "boolean",
"default": false
},
"chain_id": {
"type": "string",
"format": "uuid"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 100
},
"cursor": {
"type": "string"
}
}
},
"EvidenceQueryResult": {
"type": "object",
"description": "Result of evidence query",
"required": ["pointers", "total_count"],
"properties": {
"pointers": {
"type": "array",
"items": {
"$ref": "#/definitions/EvidencePointer"
}
},
"total_count": {
"type": "integer"
},
"next_cursor": {
"type": "string"
},
"query_time_ms": {
"type": "integer"
}
}
}
},
"properties": {
"evidence": {
"type": "array",
"items": {
"$ref": "#/definitions/EvidencePointer"
}
}
},
"examples": [
{
"evidence": [
{
"pointer_id": "550e8400-e29b-41d4-a716-446655440001",
"artifact_type": "sbom",
"digest": {
"algorithm": "sha256",
"value": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
},
"uri": "s3://stellaops-evidence/sbom/2025/12/06/sbom-abc123.json",
"storage_backend": "evidence",
"bucket": "stellaops-evidence",
"key": "sbom/2025/12/06/sbom-abc123.json",
"size_bytes": 45678,
"media_type": "application/vnd.cyclonedx+json",
"compression": "gzip",
"chain_position": {
"chain_id": "660e8400-e29b-41d4-a716-446655440002",
"sequence": 42,
"merkle_root": "b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef1234567a"
},
"provenance": {
"producer": "stellaops-scanner",
"producer_version": "2025.10.0",
"tenant_id": "770e8400-e29b-41d4-a716-446655440003",
"correlation_id": "880e8400-e29b-41d4-a716-446655440004"
},
"retention": {
"retention_days": 365,
"legal_hold": false
},
"created_at": "2025-12-06T10:00:00Z"
}
]
}
]
}

View File

@@ -0,0 +1,901 @@
{
"$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
}
}
}
]
}