8768c27f30
- 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.
418 lines
11 KiB
JSON
418 lines
11 KiB
JSON
{
|
|
"$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"
|
|
}
|
|
]
|
|
}
|