Add signal contracts for reachability, exploitability, trust, and unknown symbols

- Introduced `ReachabilityState`, `RuntimeHit`, `ExploitabilitySignal`, `ReachabilitySignal`, `SignalEnvelope`, `SignalType`, `TrustSignal`, and `UnknownSymbolSignal` records to define various signal types and their properties. - Implemented JSON serialization attributes for proper data interchange. - Created project files for the new signal contracts library and corresponding test projects. - Added deterministic test fixtures for micro-interaction testing. - Included cryptographic keys for secure operations with cosign.
2025-12-05 00:27:00 +02:00
parent b018949a8d
commit 8768c27f30
192 changed files with 27569 additions and 2552 deletions
--- a/docs/schemas/scanner-surface.schema.json
+++ b/docs/schemas/scanner-surface.schema.json
@@ -0,0 +1,417 @@
+{
+  "$id": "https://stella.ops/schema/scanner-surface.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ScannerSurface",
+  "description": "SCANNER-SURFACE-01 task contract defining scanner job execution, surface analysis, and result reporting",
+  "type": "object",
+  "oneOf": [
+    { "$ref": "#/$defs/ScanTaskRequest" },
+    { "$ref": "#/$defs/ScanTaskResult" },
+    { "$ref": "#/$defs/ScanTaskProgress" }
+  ],
+  "$defs": {
+    "ScanTaskRequest": {
+      "type": "object",
+      "required": ["taskType", "taskId", "subject", "surfaces"],
+      "properties": {
+        "taskType": {
+          "type": "string",
+          "const": "SCAN_REQUEST"
+        },
+        "taskId": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Unique task identifier"
+        },
+        "correlationId": {
+          "type": "string",
+          "description": "Correlation ID for tracing"
+        },
+        "tenantId": {
+          "type": "string",
+          "description": "Tenant scope"
+        },
+        "subject": {
+          "$ref": "#/$defs/ScanSubject",
+          "description": "Subject to scan"
+        },
+        "surfaces": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "VULNERABILITY",
+              "SBOM",
+              "SECRETS",
+              "MALWARE",
+              "COMPLIANCE",
+              "LICENSE",
+              "REACHABILITY"
+            ]
+          },
+          "minItems": 1,
+          "description": "Analysis surfaces to execute"
+        },
+        "options": {
+          "$ref": "#/$defs/ScanOptions"
+        },
+        "priority": {
+          "type": "string",
+          "enum": ["LOW", "NORMAL", "HIGH", "CRITICAL"],
+          "default": "NORMAL"
+        },
+        "deadline": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Optional deadline for task completion"
+        }
+      }
+    },
+    "ScanTaskResult": {
+      "type": "object",
+      "required": ["taskType", "taskId", "status", "completedAt"],
+      "properties": {
+        "taskType": {
+          "type": "string",
+          "const": "SCAN_RESULT"
+        },
+        "taskId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["COMPLETED", "FAILED", "PARTIAL", "CANCELLED"]
+        },
+        "completedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "durationMs": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Task duration in milliseconds"
+        },
+        "subject": {
+          "$ref": "#/$defs/ScanSubject"
+        },
+        "surfaceResults": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/SurfaceResult"
+          }
+        },
+        "summary": {
+          "$ref": "#/$defs/ScanSummary"
+        },
+        "artifacts": {
+          "$ref": "#/$defs/ScanArtifacts"
+        },
+        "attestation": {
+          "$ref": "#/$defs/AttestationRef"
+        },
+        "errors": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ScanError"
+          }
+        }
+      }
+    },
+    "ScanTaskProgress": {
+      "type": "object",
+      "required": ["taskType", "taskId", "phase", "progressPercent"],
+      "properties": {
+        "taskType": {
+          "type": "string",
+          "const": "SCAN_PROGRESS"
+        },
+        "taskId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "phase": {
+          "type": "string",
+          "enum": [
+            "QUEUED",
+            "STARTING",
+            "PULLING_IMAGE",
+            "EXTRACTING",
+            "ANALYZING",
+            "CORRELATING",
+            "FINALIZING"
+          ]
+        },
+        "progressPercent": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "currentSurface": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "ScanSubject": {
+      "type": "object",
+      "required": ["type", "reference"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["IMAGE", "DIRECTORY", "ARCHIVE", "SBOM", "REPOSITORY"],
+          "description": "Type of scan subject"
+        },
+        "reference": {
+          "type": "string",
+          "description": "Subject reference (image ref, path, etc.)"
+        },
+        "digest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "Content digest if known"
+        },
+        "platform": {
+          "type": "string",
+          "description": "Target platform (linux/amd64, etc.)"
+        },
+        "credentials": {
+          "$ref": "#/$defs/CredentialRef",
+          "description": "Credentials for accessing subject"
+        }
+      }
+    },
+    "CredentialRef": {
+      "type": "object",
+      "properties": {
+        "secretName": {
+          "type": "string",
+          "description": "Secret name for credential lookup"
+        },
+        "provider": {
+          "type": "string",
+          "enum": ["VAULT", "K8S_SECRET", "ENV", "FILE"]
+        }
+      }
+    },
+    "ScanOptions": {
+      "type": "object",
+      "properties": {
+        "severityThreshold": {
+          "type": "string",
+          "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW", "UNKNOWN"],
+          "description": "Minimum severity to report"
+        },
+        "includeUnfixed": {
+          "type": "boolean",
+          "default": true,
+          "description": "Include vulnerabilities without fixes"
+        },
+        "sbomFormat": {
+          "type": "string",
+          "enum": ["SPDX_JSON", "CYCLONEDX_JSON", "SYFT_JSON"],
+          "description": "SBOM output format"
+        },
+        "analyzers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Specific analyzers to run"
+        },
+        "skipAnalyzers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Analyzers to skip"
+        },
+        "layerAnalysis": {
+          "type": "boolean",
+          "default": false,
+          "description": "Perform per-layer analysis"
+        },
+        "generateAttestation": {
+          "type": "boolean",
+          "default": true,
+          "description": "Generate signed attestation"
+        }
+      }
+    },
+    "SurfaceResult": {
+      "type": "object",
+      "required": ["surface", "status"],
+      "properties": {
+        "surface": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["SUCCESS", "FAILED", "SKIPPED", "PARTIAL"]
+        },
+        "durationMs": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "artifactDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "findings": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Surface-specific findings summary"
+        },
+        "error": {
+          "$ref": "#/$defs/ScanError"
+        }
+      }
+    },
+    "ScanSummary": {
+      "type": "object",
+      "properties": {
+        "vulnerabilities": {
+          "type": "object",
+          "properties": {
+            "critical": { "type": "integer", "minimum": 0 },
+            "high": { "type": "integer", "minimum": 0 },
+            "medium": { "type": "integer", "minimum": 0 },
+            "low": { "type": "integer", "minimum": 0 },
+            "unknown": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "packages": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total packages discovered"
+        },
+        "secretsDetected": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "complianceViolations": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "licenseIssues": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "ScanArtifacts": {
+      "type": "object",
+      "properties": {
+        "sbom": {
+          "$ref": "#/$defs/ArtifactRef"
+        },
+        "vulnerabilityReport": {
+          "$ref": "#/$defs/ArtifactRef"
+        },
+        "secretsReport": {
+          "$ref": "#/$defs/ArtifactRef"
+        },
+        "complianceReport": {
+          "$ref": "#/$defs/ArtifactRef"
+        },
+        "reachabilityReport": {
+          "$ref": "#/$defs/ArtifactRef"
+        }
+      }
+    },
+    "ArtifactRef": {
+      "type": "object",
+      "required": ["digest", "mediaType"],
+      "properties": {
+        "digest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "mediaType": {
+          "type": "string"
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "location": {
+          "type": "string",
+          "format": "uri",
+          "description": "Storage location"
+        }
+      }
+    },
+    "AttestationRef": {
+      "type": "object",
+      "properties": {
+        "envelopeDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "predicateType": {
+          "type": "string",
+          "format": "uri"
+        },
+        "location": {
+          "type": "string",
+          "format": "uri"
+        },
+        "transparencyLog": {
+          "type": "string",
+          "format": "uri"
+        }
+      }
+    },
+    "ScanError": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "examples": [
+            "IMAGE_PULL_FAILED",
+            "ANALYZER_TIMEOUT",
+            "INSUFFICIENT_RESOURCES",
+            "INVALID_FORMAT"
+          ]
+        },
+        "message": {
+          "type": "string"
+        },
+        "surface": {
+          "type": "string"
+        },
+        "retryable": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "taskType": "SCAN_REQUEST",
+      "taskId": "550e8400-e29b-41d4-a716-446655440000",
+      "correlationId": "pipeline-run-abc123",
+      "tenantId": "acme-corp",
+      "subject": {
+        "type": "IMAGE",
+        "reference": "registry.example.com/app:v1.2.3",
+        "platform": "linux/amd64"
+      },
+      "surfaces": ["VULNERABILITY", "SBOM", "SECRETS"],
+      "options": {
+        "severityThreshold": "LOW",
+        "sbomFormat": "SPDX_JSON",
+        "generateAttestation": true
+      },
+      "priority": "NORMAL"
+    }
+  ]
+}