semi implemented and features implemented save checkpoint

This commit is contained in:
master
2026-02-08 18:00:49 +02:00
parent 04360dff63
commit 1bf6bbf395
20895 changed files with 716795 additions and 64 deletions

View File

@@ -0,0 +1,40 @@
# 3-Bit Reachability Gate
## Module
Scanner
## Status
IMPLEMENTED
## Description
Gate-based reachability system with multiple gate detectors (auth, admin-only, feature flags, non-default config), gate multiplier calculator, and rich graph annotation for gate-aware reachability.
## Implementation Details
- **Gate Detectors** (each implements `IGateDetector`):
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/Detectors/AuthGateDetector.cs` - Detects authentication gates on paths
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/Detectors/AdminOnlyDetector.cs` - Detects admin-only access restrictions
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/Detectors/FeatureFlagDetector.cs` - Detects feature flag conditions
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/Detectors/NonDefaultConfigDetector.cs` - Detects non-default configuration gates
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/Detectors/FileSystemCodeContentProvider.cs` - Provides file system code content for detection
- **Gate Composition & Scoring**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/CompositeGateDetector.cs` - Combines multiple gate detectors
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/GateMultiplierCalculator.cs` - Calculates gate multipliers for risk scoring
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/GateModels.cs` - Gate data models
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/GatePatterns.cs` - Pattern matching rules for gate detection
- **Rich Graph Annotation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/RichGraphGateAnnotator.cs` - Annotates rich graphs with gate information
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/RichGraph.cs` - Core rich graph model
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/RichGraphWriter.cs` - Writes gate-annotated rich graphs
- **SmartDiff Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/ReachabilityGateBridge.cs` - Bridges gate detection into smart diff analysis
- **PR Gate**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Cache/PrReachabilityGate.cs` - PR-level reachability gate evaluation
## E2E Test Plan
- [ ] Set up a scan target image containing a web application with authenticated routes, admin-only endpoints, feature-flagged code, and non-default config paths
- [ ] Trigger a scan via `POST /api/v1/scans` with reachability analysis enabled
- [ ] Verify each gate detector identifies its respective gate type in the reachability graph via `GET /api/v1/scans/{scanId}/reachability`
- [ ] Verify `GateMultiplierCalculator` reduces risk scores for gated paths (auth-gated vulns score lower than ungated)
- [ ] Verify the rich graph response includes gate annotations on affected nodes and edges
- [ ] Verify SmartDiff output includes gate-aware reachability context via the `ReachabilityGateBridge`
- [ ] Verify PR gate evaluation correctly blocks/allows based on gate-modified reachability status

View File

@@ -0,0 +1,31 @@
# AI Governance Policy Loader for ML-BOM Scanning
## Module
Scanner
## Status
IMPLEMENTED
## Description
Configurable AI governance policies for scanner-level enforcement of model card requirements, training data lineage thresholds, and EU AI Act compliance categories during SBOM analysis.
## Implementation Details
- **Policy Loader**:
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Policy/AiGovernancePolicyLoader.cs` - Loads and validates AI governance policy configurations
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Policy/AiGovernancePolicy.cs` - Policy model defining model card requirements, training data lineage thresholds, and EU AI Act compliance categories
- **Enforcement Analyzers**:
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/ModelCardCompletenessAnalyzer.cs` - Enforces model card completeness requirements from policy
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/ModelCardScoring.cs` - Scores model cards against policy thresholds
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/TrainingDataProvenanceAnalyzer.cs` - Validates training data lineage against policy thresholds
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/AiSafetyRiskAnalyzer.cs` - EU AI Act risk classification
- **Worker Integration**:
- `src/Scanner/StellaOps.Scanner.Worker/Processing/AiMlSecurity/AiMlSecurityStageExecutor.cs` - Stage executor that loads governance policy and runs analyzers during scan
- **Models**: `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Models/AiMlSecurityModels.cs`
## E2E Test Plan
- [ ] Configure an AI governance policy with specific model card requirements (e.g., require description, intended use, limitations fields)
- [ ] Scan an image containing an ML model with incomplete model card metadata
- [ ] Verify the scan produces findings for missing model card fields per policy
- [ ] Configure training data lineage threshold and verify scan flags models below threshold
- [ ] Configure EU AI Act compliance category and verify classification is applied to findings
- [ ] Verify policy changes are picked up on subsequent scans without service restart

View File

@@ -0,0 +1,43 @@
# AI/ML Supply Chain Security Analysis Module
## Module
Scanner
## Status
IMPLEMENTED
## Description
Dedicated scanner module for AI/ML supply chain security including EU AI Act risk classification, model card completeness analysis, training data provenance verification, bias/fairness analysis, and AI governance policy enforcement. Distinct from the existing "AI Authority Classification Engine" which focuses on VEX/advisory AI classification, not ML-BOM supply chain scanning.
## Implementation Details
- **Core Analyzer**:
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/AiMlSecurityAnalyzer.cs` - `IAiMlSecurityAnalyzer` / `AiMlSecurityAnalyzer` orchestrates all AI/ML security checks
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/AiMlSecurityServiceCollectionExtensions.cs` - DI registration
- **Analysis Context & Results**:
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/AiMlSecurityContext.cs` - `AiMlSecurityContext` input model
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/AiMlSecurityResult.cs` - `AiMlSecurityResult`, `IAiMlSecurityCheck` interface for pluggable checks
- **Individual Analyzers** (each implements `IAiMlSecurityCheck`):
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/AiSafetyRiskAnalyzer.cs` - EU AI Act risk classification
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/ModelCardCompletenessAnalyzer.cs` - Model card completeness scoring
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/ModelCardScoring.cs` - Scoring logic for model card fields
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/TrainingDataProvenanceAnalyzer.cs` - Training data lineage verification
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/BiasFairnessAnalyzer.cs` - Bias and fairness analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/ModelBinaryAnalyzer.cs` - Model binary format analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/ModelProvenanceVerifier.cs` - Model provenance verification
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/AiModelInventoryGenerator.cs` - Generates inventory of discovered AI/ML models
- **Governance Policy**:
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Policy/AiGovernancePolicyLoader.cs` - Policy configuration loader
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Policy/AiGovernancePolicy.cs` - Policy model
- **Reporting**: `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Reporting/AiMlSecurityReportFormatter.cs`
- **Models**: `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Models/AiMlSecurityModels.cs`
- **Worker Stage**: `src/Scanner/StellaOps.Scanner.Worker/Processing/AiMlSecurity/AiMlSecurityStageExecutor.cs`
## E2E Test Plan
- [ ] Scan a container image containing ML model artifacts (e.g., ONNX, TensorFlow SavedModel, PyTorch)
- [ ] Verify `AiModelInventoryGenerator` discovers and lists all ML models in the scan results
- [ ] Verify `ModelCardCompletenessAnalyzer` produces findings for models with missing/incomplete model cards
- [ ] Verify `AiSafetyRiskAnalyzer` assigns EU AI Act risk classification (unacceptable, high, limited, minimal)
- [ ] Verify `TrainingDataProvenanceAnalyzer` flags models without verifiable training data lineage
- [ ] Verify `BiasFairnessAnalyzer` produces bias/fairness findings where applicable
- [ ] Verify `ModelBinaryAnalyzer` identifies model format and potential binary-level issues
- [ ] Verify all findings appear in the unified scan report and SARIF export

View File

@@ -0,0 +1,31 @@
# API Gateway Boundary Extractor (Kong, Envoy/Istio, AWS API Gateway, Traefik)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Parses API gateway configurations from Kong, Envoy/Istio, AWS API Gateway, and Traefik to extract route-level boundary information for reachability analysis. Determines which internal services are exposed through gateway routes.
## Implementation Details
- **Core Extractor**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/GatewayBoundaryExtractor.cs` - `GatewayBoundaryExtractor` implements `IBoundaryProofExtractor`; parses Kong, Envoy/Istio, AWS API Gateway, and Traefik configurations
- Includes gateway-specific auth detection: `DetectKongAuth()`, `DetectEnvoyAuth()` (including Istio JWT/AuthorizationPolicy), `DetectTraefikAuth()`
- Identifies Istio mesh internal routes and external ingress routes
- **Supporting Infrastructure**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/IacBoundaryExtractor.cs` - Infrastructure-as-code boundary extraction
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/BoundaryServiceCollectionExtensions.cs` - DI registration for boundary extractors
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/BoundaryExtractionContext.cs` - Context model for boundary extraction
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/RichGraphBoundaryExtractor.cs` - Integrates boundary data into rich graphs
- **Tests**:
- `src/Scanner/__Tests/StellaOps.Scanner.Reachability.Tests/GatewayBoundaryExtractorTests.cs`
## E2E Test Plan
- [ ] Provide a Kong configuration file with routes exposing internal services and verify extracted boundary information includes route paths, upstream services, and auth requirements
- [ ] Provide an Envoy/Istio configuration with VirtualService and AuthorizationPolicy and verify correct route-to-service mappings and auth detection
- [ ] Provide an AWS API Gateway configuration and verify correct extraction of REST/HTTP API routes with Lambda/ECS integrations
- [ ] Provide a Traefik configuration with middleware auth and verify correct route extraction with authentication metadata
- [ ] Verify extracted boundaries are reflected in the reachability rich graph via `GET /api/v1/scans/{scanId}/reachability`
- [ ] Verify that gated gateway routes (auth-required) reduce reachability risk scores compared to ungated routes

View File

@@ -0,0 +1,32 @@
# Auto-VEX Generation from Smart-Diff
## Module
Scanner
## Status
IMPLEMENTED
## Description
VEX candidate emission from SmartDiff detection results, generating VEX statements backed by delta evidence.
## Implementation Details
- **VEX Candidate Emission**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/VexCandidateEmitter.cs` - Emits VEX candidates from SmartDiff detection results
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/VexCandidateModels.cs` - VEX candidate data models
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/VexEvidence.cs` - Delta evidence backing VEX statements
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/Repositories.cs` - Repository interfaces for VEX candidate persistence
- **SmartDiff Predicate**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/SmartDiffPredicate.cs` - SmartDiff predicate model including VEX data
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/ReachabilityGateBridge.cs` - Bridges reachability gate data into SmartDiff VEX candidates
- **SARIF Output**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Output/SarifOutputGenerator.cs` - SARIF export including VEX candidate data
- **API Endpoint**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/SmartDiffEndpoints.cs` - `SmartDiffEndpoints` exposes VEX candidates via REST (`VexCandidatesResponse`, `VexCandidateDto`, `ReviewRequest`)
## E2E Test Plan
- [ ] Scan two versions of the same image to produce a smart-diff delta
- [ ] Call `GET /api/v1/smart-diff/{scanId}/vex-candidates` and verify VEX candidates are returned
- [ ] Verify each VEX candidate includes evidence links referencing the specific delta changes
- [ ] Submit a review decision via `POST /api/v1/smart-diff/{scanId}/vex-candidates/review` and verify the candidate status updates
- [ ] Export the SARIF output and verify VEX candidate data is embedded in the SARIF report
- [ ] Verify VEX candidates include reachability gate context when gates are detected

View File

@@ -0,0 +1,31 @@
# Base Image Detection and Recommendations
## Module
Scanner
## Status
IMPLEMENTED
## Description
Base image detection via layer diffID fingerprinting with PostgreSQL-backed fingerprint database, in-memory index, exact layer match and fuzzy matching, and bulk detection support. Interface `IBaseImageDetector` with full `BaseImageDetector` implementation.
## Implementation Details
- **Core Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Resolution/IBaseImageDetector.cs` - `IBaseImageDetector` interface
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Resolution/BaseImageDetector.cs` - `BaseImageDetector` with exact layer match and fuzzy matching, bulk detection support
- **Layer Resolution**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Resolution/ILayerDigestResolver.cs` - Interface for resolving layer digests
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Resolution/LayerDigestResolver.cs` - Resolves layer diffIDs for fingerprint matching
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Resolution/LayerProvenance.cs` - Layer provenance tracking for base image attribution
- **Layer Reuse Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Reuse/ILayerReuseDetector.cs` - Interface for layer reuse detection
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Reuse/LayerReuseDetector.cs` - Detects shared layers between images for base image identification
- **DI Registration**: `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/ManifestServiceCollectionExtensions.cs`
## E2E Test Plan
- [ ] Scan an image built on a known base image (e.g., `debian:bookworm`) and verify `IBaseImageDetector` identifies the correct base image
- [ ] Verify exact layer match identifies base images by diffID fingerprint comparison
- [ ] Test fuzzy matching with a slightly modified base image (e.g., additional layer) and verify partial match is returned with confidence score
- [ ] Test bulk detection by submitting multiple image references and verify all base images are identified in a single operation
- [ ] Verify base image detection results appear in the scan report and SBOM metadata
- [ ] Verify layer provenance tracking attributes vulnerability findings to base image vs application layers

View File

@@ -0,0 +1,35 @@
# Binary Intelligence Engine (Function-Level Code Fingerprinting)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Function-level binary code fingerprinting with symbol recovery for stripped binaries, vulnerable function matching against a fingerprint corpus, and source-to-binary correlation. Extends existing binary fingerprint capabilities with intelligence-grade analysis for entrypoint-scoped binary reachability.
## Implementation Details
- **Core Analyzer**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Binary/BinaryIntelligenceAnalyzer.cs` - Main analyzer for function-level binary code fingerprinting
- **Symbol Recovery**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Binary/ISymbolRecovery.cs` - Interface for recovering symbols from stripped binaries
- **Fingerprint Index**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Binary/IFingerprintIndex.cs` - Interface for fingerprint corpus lookup
- **Vulnerable Function Matching**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Binary/VulnerableFunctionMatcher.cs` - Matches binary functions against known vulnerable function fingerprints
- **Analysis Results**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Binary/BinaryAnalysisResult.cs` - Result models for binary intelligence analysis
- **Risk Scoring**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Risk/IRiskScorer.cs` - Risk scorer integrating binary intelligence into entrypoint risk assessment
- **Worker Integration**:
- `src/Scanner/StellaOps.Scanner.Worker/Processing/EntryTraceExecutionService.cs` - Executes entry trace analysis including binary intelligence during scan
- `src/Scanner/StellaOps.Scanner.Worker/Processing/IEntryTraceExecutionService.cs` - Interface for entry trace execution
## E2E Test Plan
- [ ] Scan a container image containing stripped ELF binaries and verify symbol recovery identifies function boundaries
- [ ] Verify fingerprint matching identifies known library functions in the binary via the `IFingerprintIndex`
- [ ] Scan an image with a binary containing a known vulnerable function and verify `VulnerableFunctionMatcher` flags it
- [ ] Verify binary intelligence results include source-to-binary correlation where debug info is available
- [ ] Verify binary analysis results appear in the entry trace response via `GET /api/v1/scans/{scanId}/entry-trace`
- [ ] Verify binary-level reachability findings contribute to the overall risk score

View File

@@ -0,0 +1,46 @@
# Binary SBOM and Build-ID to PURL Mapping
## Module
Scanner
## Status
IMPLEMENTED
## Description
Binary call graph extraction, patch verification with signature stores and evidence models, and binary index service extensions for the scanner worker.
## Implementation Details
- **Binary Call Graph Extraction**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/BinaryCallGraphExtractor.cs` - Extracts call graphs from native binaries
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/DependencyInjection/CallGraphServiceCollectionExtensions.cs` - DI registration
- **Patch Verification**:
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/IPatchVerificationOrchestrator.cs` - Orchestrator interface
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/PatchVerificationOrchestrator.cs` - Orchestrates patch verification workflow
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Services/IPatchSignatureStore.cs` - Interface for patch signature storage
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Services/InMemoryPatchSignatureStore.cs` - In-memory signature store implementation
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Services/EvidenceIdGenerator.cs` - Generates evidence IDs for patch verification results
- **Patch Verification Models**:
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Models/PatchVerificationResult.cs` - Result model
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Models/PatchVerificationEvidence.cs` - Evidence model
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Models/PatchVerificationContext.cs` - Context model
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Models/PatchVerificationStatus.cs` - Status enum
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Models/PatchVerificationOptions.cs` - Options
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Models/DsseEnvelopeRef.cs` - DSSE envelope reference
- **Worker Integration**:
- `src/Scanner/StellaOps.Scanner.Worker/Extensions/BinaryIndexServiceExtensions.cs` - `BinaryIndexServiceExtensions` registering `IBinaryVulnerabilityService`, `IBinaryFeatureExtractor`
- `src/Scanner/StellaOps.Scanner.Worker/Processing/BinaryLookupStageExecutor.cs` - Binary lookup stage during scan
- `src/Scanner/StellaOps.Scanner.Worker/Processing/BinaryVulnerabilityAnalyzer.cs` - Binary vulnerability analysis
- `src/Scanner/StellaOps.Scanner.Worker/Processing/BinaryFindingMapper.cs` - Maps binary findings to unified finding model
- **Build-ID Index**:
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/Index/OfflineBuildIdIndex.cs` - Offline build-ID to PURL index
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/Index/IBuildIdIndex.cs` - Interface for build-ID index
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/Index/BuildIdIndexEntry.cs` - Index entry model
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/Index/BuildIdLookupResult.cs` - Lookup result model
## E2E Test Plan
- [ ] Scan a container image with native binaries containing ELF build-IDs and verify build-ID to PURL mapping resolves correctly
- [ ] Verify binary call graph extraction produces a valid call graph for native binaries via `BinaryCallGraphExtractor`
- [ ] Trigger patch verification on a scanned binary and verify `PatchVerificationOrchestrator` produces evidence with status and signature references
- [ ] Verify binary vulnerability findings are mapped to the unified finding model and appear in scan results
- [ ] Verify the offline build-ID index (`OfflineBuildIdIndex`) can resolve build-IDs without network access
- [ ] Export scan results as SBOM and verify binary components include PURL identifiers derived from build-ID mapping

View File

@@ -0,0 +1,30 @@
# Bug ID to CVE Mapping in Changelog Parsing
## Module
Scanner
## Status
IMPLEMENTED
## Description
Regex-based extraction of bug tracker references (Debian "Closes: #123456", RHBZ#123456, Launchpad "LP: #123456") from changelogs, with cross-reference to CVE IDs for Tier 2 backport evidence.
## Implementation Details
- **Changelog Parsing (OS Analyzers)**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Rpm/RpmPackageAnalyzer.cs` - RPM package analyzer with changelog parsing
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Rpm/Internal/RpmHeaderParser.cs` - Parses RPM headers including changelog entries
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Rpm/Internal/RpmHeader.cs` - RPM header model with changelog tags
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Rpm/Internal/RpmTags.cs` - RPM tag definitions including changelog-related tags
- **Pedigree & Commit Mapping**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Pedigree/FeedserPedigreeDataProvider.cs` - Provides pedigree data including changelog-derived CVE references
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Pedigree/CommitInfoBuilder.cs` - Builds commit info with bug tracker cross-references
- **Material Changes Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.MaterialChanges/CardGenerators.cs` - Generates material change cards including changelog-derived bug-to-CVE mappings
## E2E Test Plan
- [ ] Scan a container image with Debian packages containing changelogs with "Closes: #NNNNNN" references and verify bug IDs are extracted
- [ ] Scan an image with RPM packages containing changelogs with RHBZ# references and verify extraction
- [ ] Verify extracted bug IDs are cross-referenced to CVE IDs and appear as Tier 2 backport evidence
- [ ] Verify the pedigree data includes changelog-derived CVE mappings in the scan report
- [ ] Verify material change cards reference changelog bug-to-CVE correlations
- [ ] Verify Launchpad "LP: #NNNNNN" references are extracted from Ubuntu package changelogs

View File

@@ -0,0 +1,43 @@
# Build Provenance Verification Module with SLSA Level Evaluator
## Module
Scanner
## Status
IMPLEMENTED
## Description
Scanner stage that evaluates SLSA provenance levels (L0-L4) for artifacts, verifies builder identity against trusted builder lists, checks reproducibility claims, and builds provenance chains. Integrates as a dedicated pipeline stage in the scanner worker.
## Implementation Details
- **Core Analyzer**:
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Analyzers/BuildProvenanceAnalyzer.cs` - Main orchestrator for build provenance analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/BuildProvenanceServiceCollectionExtensions.cs` - DI registration
- **SLSA Level Evaluation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Analyzers/SlsaLevelEvaluator.cs` - Evaluates SLSA provenance levels (L0-L4)
- **Builder Verification**:
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Analyzers/BuilderVerifier.cs` - Verifies builder identity against trusted builder lists
- **Reproducibility**:
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Analyzers/ReproducibilityVerifier.cs` - Checks reproducibility claims
- **Provenance Chain**:
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Analyzers/BuildProvenanceChainBuilder.cs` - Builds provenance chains linking build steps
- **Additional Verifiers**:
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Analyzers/BuildInputIntegrityChecker.cs` - Verifies integrity of build inputs
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Analyzers/BuildConfigVerifier.cs` - Verifies build configuration
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Analyzers/SourceVerifier.cs` - Verifies source provenance
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Analyzers/BuildProvenancePatternMatcher.cs` - Pattern matching for provenance artifacts
- **Policy**:
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Policy/BuildProvenancePolicyLoader.cs` - Loads build provenance policies
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Policy/BuildProvenancePolicy.cs` - Policy model
- **Models**: `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Models/BuildProvenanceModels.cs`
- **Reporting**: `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Reporting/BuildProvenanceReportFormatter.cs`
- **Worker Stage**: `src/Scanner/StellaOps.Scanner.Worker/Processing/BuildProvenance/BuildProvenanceStageExecutor.cs`
## E2E Test Plan
- [ ] Scan an artifact with SLSA L1 provenance and verify `SlsaLevelEvaluator` assigns level L1
- [ ] Scan an artifact with full SLSA L3 provenance (signed, non-falsifiable) and verify level L3 assignment
- [ ] Provide a trusted builder list and verify `BuilderVerifier` validates/rejects builder identities
- [ ] Scan an artifact with reproducibility claims and verify `ReproducibilityVerifier` validates them
- [ ] Verify `BuildProvenanceChainBuilder` links build steps into a verifiable chain
- [ ] Verify build provenance findings appear in scan report with SLSA level, builder identity, and chain details
- [ ] Scan an artifact with no provenance and verify it is assigned SLSA L0

View File

@@ -0,0 +1,28 @@
# Bun Call Graph Extractor
## Module
Scanner
## Status
IMPLEMENTED
## Description
Static call graph extraction for Bun runtime JavaScript/TypeScript codebases, extending the multi-language extractor framework with Bun-specific entrypoint detection and sink matching.
## Implementation Details
- **Call Graph Extractor**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Bun/BunCallGraphExtractor.cs` - Static call graph extraction for Bun runtime codebases
- **Entrypoint Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Bun/BunEntrypointClassifier.cs` - Classifies Bun-specific entrypoints (e.g., `Bun.serve`, macros, plugins)
- **Sink Matching**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Bun/BunSinkMatcher.cs` - Matches Bun-specific security-sensitive sinks (file I/O, shell exec, FFI, etc.)
- **DI Registration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/DependencyInjection/CallGraphServiceCollectionExtensions.cs`
## E2E Test Plan
- [ ] Scan a container image containing a Bun application with `Bun.serve` entrypoints
- [ ] Verify call graph extraction produces nodes for Bun-specific entrypoints (HTTP handlers, macros, plugins)
- [ ] Verify `BunSinkMatcher` identifies Bun-specific sinks (e.g., `Bun.file`, `Bun.spawn`, `Bun.ffi`)
- [ ] Verify the extracted call graph links entrypoints to sinks through the application code
- [ ] Verify call graph data is available in reachability analysis via `GET /api/v1/scans/{scanId}/reachability`
- [ ] Verify TypeScript and JavaScript files are both analyzed correctly in mixed Bun projects

View File

@@ -0,0 +1,52 @@
# Bun Language Analyzer
## Module
Scanner
## Status
IMPLEMENTED
## Description
Full language analyzer for the Bun JavaScript runtime including bun.lockb binary lockfile parser, installed package collector, workspace/monorepo support, scope classification (dev/prod/peer), symlink safety checks, CLI verbs, and WebService endpoints for Worker integration.
## Implementation Details
- **Analyzer Plugin**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/BunAnalyzerPlugin.cs` - Plugin entry point for Bun analyzer
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/BunLanguageAnalyzer.cs` - Main language analyzer implementation
- **Lockfile Parsing**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunLockParser.cs` - Parses `bun.lockb` binary lockfiles
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunLockData.cs` - Parsed lock data model
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunLockEntry.cs` - Individual lock entry model
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunLockInventory.cs` - Inventory built from lockfile
- **Package Collection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunInstalledCollector.cs` - Collects installed packages from filesystem
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunDeclaredDependencyCollector.cs` - Collects declared dependencies from package.json
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunPackage.cs` - Package model
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunPackageNormalizer.cs` - Package normalization
- **Scope & Classification**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunLockScopeClassifier.cs` - Classifies dependencies as dev/prod/peer
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunInputClassification.cs` - Input file classification
- **Workspace/Monorepo**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunWorkspaceHelper.cs` - Workspace and monorepo support
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunProjectDiscoverer.cs` - Discovers Bun projects in filesystem
- **Input & Config**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunInputNormalizer.cs` - Normalizes input for determinism
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunConfigHelper.cs` - Configuration helpers
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunVersionSpec.cs` - Version specification parsing
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/Internal/BunEvidenceHasher.cs` - Evidence hashing for determinism
- **Worker Integration**:
- `src/Scanner/StellaOps.Scanner.Worker/Processing/Surface/BunPackageInventoryBuilder.cs` - Builds package inventory during scan
- **Storage**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Services/BunPackageInventoryStore.cs` - Package inventory store
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Repositories/BunPackageInventoryRepository.cs` - Repository
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Catalog/BunPackageInventoryDocument.cs` - Document model
- **WebService**: `src/Scanner/StellaOps.Scanner.WebService/Contracts/BunContracts.cs` - API contracts for Bun scan results
## E2E Test Plan
- [ ] Scan a container image containing a Bun project with `bun.lockb` and verify all packages are parsed correctly
- [ ] Verify scope classification distinguishes dev, prod, and peer dependencies
- [ ] Scan a Bun workspace/monorepo and verify all workspace packages are discovered and analyzed
- [ ] Verify installed package collection from node_modules matches lockfile data
- [ ] Verify the scan results include PURL identifiers for all Bun packages
- [ ] Verify symlink safety checks flag potentially unsafe symlinks in node_modules
- [ ] Verify Bun scan results are available via the WebService API contracts

View File

@@ -0,0 +1,34 @@
# BYOS (Bring Your Own SBOM) Ingestion Workflow
## Module
Scanner
## Status
IMPLEMENTED
## Description
Allows users to upload externally-generated SBOMs (CycloneDX 1.4-1.6, SPDX 2.3/3.0) via REST API. Includes automatic format detection, schema validation, component normalization, quality scoring (PURL/version/license coverage weighted 40/30/30), SHA-256 digest computation, and automatic scan/analysis triggering. Supports both inline JSON and base64-encoded payloads with CI context metadata.
## Implementation Details
- **Upload Endpoints**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/SbomUploadEndpoints.cs` - `SbomUploadEndpoints` for REST upload API
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/SbomEndpoints.cs` - Additional SBOM query endpoints
- **Contracts**:
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/SbomContracts.cs` - `SbomUploadRequestDto`, `SbomUploadResponseDto`, `SbomValidationSummaryDto`, `SbomFormats`, `SbomAncestryDto`, `SbomUploadSourceDto`, `SbomUploadCiContextDto`
- **Ingestion Service**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/ISbomIngestionService.cs` - `ISbomIngestionService`, `SbomIngestionResult`, `SbomValidationResult`
- `src/Scanner/StellaOps.Scanner.WebService/Services/SbomIngestionService.cs` - Format detection, schema validation, component normalization, quality scoring, digest computation
- **BYOS Upload Service**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/SbomByosUploadService.cs` - `ISbomByosUploadService` / `SbomByosUploadService` for external SBOM ingestion
- **Upload Store**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/SbomUploadStore.cs` - `ISbomUploadStore`, `InMemorySbomUploadStore`, `SbomUploadRecord`
## E2E Test Plan
- [ ] Upload a CycloneDX 1.6 JSON SBOM via `POST /api/v1/sbom/upload` with inline JSON payload and verify acceptance
- [ ] Upload an SPDX 2.3 SBOM via base64-encoded payload with CI context metadata and verify ingestion
- [ ] Verify automatic format detection correctly identifies CycloneDX vs SPDX format
- [ ] Verify schema validation rejects an invalid SBOM with appropriate error details
- [ ] Verify quality scoring returns PURL/version/license coverage percentages (40/30/30 weighted)
- [ ] Verify SHA-256 digest is computed and returned in the response
- [ ] Verify automatic scan/analysis is triggered after successful ingestion
- [ ] Query the uploaded SBOM status via `GET /api/v1/sbom/uploads/{id}` and verify metadata

View File

@@ -0,0 +1,35 @@
# Canonical Node-Hash and Path-Hash Recipes for Reachability
## Module
Scanner
## Status
IMPLEMENTED
## Description
Canonical node-hash (PURL/symbol normalization + SHA-256) and path-hash (top-K selection + PathFingerprint) recipes for deterministic static/runtime evidence joins. Extended PathWitness, RichGraph, SARIF export with hash fields.
## Implementation Details
- **Path Witness with Hash Fields**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitness.cs` - `PathWitness` model with node-hash and path-hash fields
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitnessBuilder.cs` - `PathWitnessBuilder` computes canonical hashes during witness construction
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/IPathWitnessBuilder.cs` - Interface
- **Rich Graph Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/RichGraph.cs` - RichGraph model extended with hash fields on nodes
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Ordering/DeterministicGraphOrderer.cs` - Deterministic ordering for canonical hash computation
- **Witness Matching & Verification**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/WitnessMatcher.cs` - Matches witnesses using canonical hashes for deterministic joins
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/WitnessSchema.cs` - Schema validation for witness hash fields
- **Slice Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceExtractor.cs` - Slice extraction with path-hash for top-K selection
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceModels.cs` - Slice models with hash fields
- **Subgraph Extraction**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Subgraph/ReachabilitySubgraphModels.cs` - Subgraph models with hash fields
## E2E Test Plan
- [ ] Scan an image and verify PathWitness results include canonical node-hash fields (SHA-256 of normalized PURL/symbol)
- [ ] Verify path-hash is computed using top-K selection and PathFingerprint algorithm
- [ ] Run the same scan twice and verify node-hash and path-hash values are deterministically identical
- [ ] Verify RichGraph response includes hash fields on nodes via `GET /api/v1/scans/{scanId}/reachability`
- [ ] Verify static/runtime evidence join works correctly using canonical hashes as join keys
- [ ] Verify SARIF export includes hash fields in reachability-related results

View File

@@ -0,0 +1,48 @@
# CBOM Cryptographic Bill of Materials Analysis with Post-Quantum Readiness Assessment
## Module
Scanner
## Status
IMPLEMENTED
## Description
Scanner analyzes cryptographic assets declared in CycloneDX CBOM (cryptoProperties), detects weak/deprecated algorithms, enforces crypto compliance policies (FIPS 140-2/3, PCI-DSS, NIST), inventories all crypto assets, and assesses post-quantum readiness with a dedicated PostQuantumAnalyzer.
## Implementation Details
- **Core Analyzer**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/CryptoAnalysisAnalyzer.cs` - Main orchestrator for crypto analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/CryptoAnalysisServiceCollectionExtensions.cs` - DI registration
- **Algorithm Analysis**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Analyzers/AlgorithmStrengthAnalyzer.cs` - Detects weak/deprecated algorithms
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Analyzers/CryptoAlgorithmCatalog.cs` - Catalog of known algorithms with strength metadata
- **Post-Quantum Readiness**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Analyzers/PostQuantumAnalyzer.cs` - Assesses post-quantum readiness of crypto assets
- **Compliance Checking**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Analyzers/FipsComplianceChecker.cs` - FIPS 140-2/3 compliance validation
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Analyzers/RegionalComplianceChecker.cs` - Regional crypto compliance (eIDAS, GOST, SM)
- **Crypto Inventory**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Analyzers/CryptoInventoryGenerator.cs` - Inventories all crypto assets
- **Certificate & Protocol Analysis**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Analyzers/CertificateAnalyzer.cs` - X.509 certificate analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Analyzers/ProtocolAnalyzer.cs` - TLS/crypto protocol version analysis
- **Context & Results**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Analyzers/CryptoAnalysisContext.cs` - Analysis context
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Analyzers/CryptoAnalysisResult.cs` - Analysis results
- **Policy**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Policy/CryptoPolicyLoader.cs` - Loads crypto compliance policies
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Policy/CryptoPolicy.cs` - Policy model (FIPS, PCI-DSS, NIST)
- **Models**: `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Models/CryptoAnalysisModels.cs`
- **Reporting**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Reporting/CryptoAnalysisReportFormatter.cs` - Report formatting
- `src/Scanner/__Libraries/StellaOps.Scanner.CryptoAnalysis/Reporting/CryptoInventoryExporter.cs` - Inventory export
- **Worker Stage**: `src/Scanner/StellaOps.Scanner.Worker/Processing/CryptoAnalysis/CryptoAnalysisStageExecutor.cs`
## E2E Test Plan
- [ ] Scan a container image with a CycloneDX SBOM containing `cryptoProperties` and verify crypto assets are inventoried
- [ ] Verify `AlgorithmStrengthAnalyzer` flags weak algorithms (e.g., MD5, SHA-1, DES) with appropriate severity
- [ ] Verify `PostQuantumAnalyzer` assesses quantum readiness and flags algorithms vulnerable to quantum attacks (e.g., RSA-2048)
- [ ] Configure a FIPS 140-3 compliance policy and verify `FipsComplianceChecker` validates/rejects algorithms accordingly
- [ ] Verify certificate analysis identifies expired/weak certificates
- [ ] Verify crypto inventory export produces a complete listing of all discovered crypto assets
- [ ] Verify crypto analysis findings appear in the unified scan report

View File

@@ -0,0 +1,34 @@
# Claim ID Generator for Static-Runtime Linkage
## Module
Scanner
## Status
IMPLEMENTED
## Description
Deterministic claim ID generator using format `claim:<artifact-digest>:<path-hash>` to link runtime observations to static reachability claims, with ObservationType enum (Static/Runtime/Confirmed).
## Implementation Details
- **Claim ID Generator**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/ClaimIdGenerator.cs` - Generates deterministic claim IDs in `claim:<artifact-digest>:<path-hash>` format
- **Observation Type**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/ObservationType.cs` - `ObservationType` enum (Static/Runtime/Confirmed)
- **Path Witness Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitness.cs` - PathWitness model carries claim IDs for static-runtime linkage
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitnessBuilder.cs` - Builder sets claim IDs during witness construction
- **Runtime Witness**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/RuntimeWitnessRequest.cs` - Runtime witness request carrying claim IDs
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/RuntimeWitnessPredicateTypes.cs` - Predicate types for runtime witnesses
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/IRuntimeWitnessGenerator.cs` - Interface for runtime witness generation
- **Claim Verification**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/FunctionMap/Verification/ClaimVerifier.cs` - Verifies claim IDs match between static and runtime evidence
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/FunctionMap/Verification/IClaimVerifier.cs` - Interface
## E2E Test Plan
- [ ] Scan an image and verify claim IDs are generated in `claim:<artifact-digest>:<path-hash>` format for each reachability path
- [ ] Verify the same scan produces identical claim IDs deterministically
- [ ] Submit runtime observation data with claim IDs and verify linkage to static reachability claims
- [ ] Verify `ClaimVerifier` validates matching claim IDs between static and runtime evidence
- [ ] Verify ObservationType transitions from Static to Confirmed when runtime evidence matches
- [ ] Verify mismatched claim IDs are rejected by the verifier with appropriate error

View File

@@ -0,0 +1,36 @@
# Composition Recipe API for SBOM Determinism Verification
## Module
Scanner
## Status
IMPLEMENTED
## Description
API endpoint (GET /scans/{id}/composition-recipe) that exposes the SBOM composition recipe with Merkle root and layer digest verification, enabling downstream verification that SBOMs are deterministically composed from layer fragments.
## Implementation Details
- **Composition Recipe Service**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/CompositionRecipeService.cs` - Core service computing composition recipes with Merkle root
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/SbomCompositionResult.cs` - Composition result model with Merkle root and layer digests
- **Layer SBOM Composition**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/LayerSbomComposer.cs` - Composes full SBOM from per-layer SBOM fragments
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/LayerSbomRef.cs` - Layer SBOM reference with digest
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/CycloneDxComposer.cs` - CycloneDX-specific composition
- **API Endpoints**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/LayerSbomEndpoints.cs` - `LayerSbomEndpoints` exposing composition recipe and layer SBOM data
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/LayerSbomContracts.cs` - API contracts
- **Layer SBOM Service**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/ILayerSbomService.cs` - `ILayerSbomService` with `LayerSummary`, `SbomLayerFragment`
- `src/Scanner/StellaOps.Scanner.WebService/Services/LayerSbomService.cs` - Implementation
- **Surface Manifest**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Surface.FS/SurfaceManifestDeterminismVerifier.cs` - Verifies determinism of surface manifests
- `src/Scanner/__Libraries/StellaOps.Scanner.Surface.FS/FacetSealExtractor.cs` - Extracts facet seals for composition verification
## E2E Test Plan
- [ ] Scan an image and call `GET /api/v1/scans/{scanId}/composition-recipe` to retrieve the composition recipe
- [ ] Verify the response includes Merkle root and per-layer digest values
- [ ] Verify each layer fragment digest matches the actual layer SBOM content hash
- [ ] Re-compose the SBOM from layer fragments and verify the Merkle root matches the recipe
- [ ] Scan the same image twice and verify composition recipe values are deterministically identical
- [ ] Verify the composition recipe can be used to verify SBOM integrity in an offline/air-gap environment

View File

@@ -0,0 +1,36 @@
# Compositional Library-Aware Call-Graph Reachability
## Module
Scanner
## Status
IMPLEMENTED
## Description
Multi-layer reachability analysis combining call-graph extraction, dependency-aware analysis, surface-aware analysis, and conditional reachability with ReachGraph integration.
## Implementation Details
- **Dependency-Aware Reachability**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/ConditionalReachabilityAnalyzer.cs` - Conditional reachability analysis considering library dependencies
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/DependencyReachabilityModels.cs` - Models for dependency-aware reachability
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/ReachGraphReachabilityCombiner.cs` - Combines ReachGraph data with local reachability analysis
- **Dependency Reporting**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/Reporting/DependencyReachabilityReporter.cs` - Generates dependency reachability reports
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/Reporting/DependencyReachabilityReport.cs` - Report model
- **Surface-Aware Analysis**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Surfaces/SurfaceAwareReachabilityAnalyzer.cs` - Surface-aware reachability analysis combining attack surface with call graph
- **Call Graph Extraction** (multi-language):
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/` - Multi-language call graph extractors
- **Worker Integration**:
- `src/Scanner/StellaOps.Scanner.Worker/Processing/Reachability/ReachabilityBuildStageExecutor.cs` - Builds reachability during scan
- `src/Scanner/StellaOps.Scanner.Worker/Processing/Reachability/SbomReachabilityStageExecutor.cs` - SBOM-level reachability analysis
- **API**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/ReachabilityEndpoints.cs` - `ReachabilityEndpoints` for querying reachability results
## E2E Test Plan
- [ ] Scan an image with a multi-library application and verify call graph extraction captures inter-library calls
- [ ] Verify `ConditionalReachabilityAnalyzer` considers conditional dependencies (optional/feature-flagged)
- [ ] Verify `SurfaceAwareReachabilityAnalyzer` combines attack surface data with call graph to produce accurate reachability verdicts
- [ ] Verify `ReachGraphReachabilityCombiner` integrates external ReachGraph data with local analysis
- [ ] Query reachability results via `GET /api/v1/scans/{scanId}/reachability` and verify library-aware paths are included
- [ ] Verify the dependency reachability report includes per-library reachability status

View File

@@ -0,0 +1,34 @@
# Container Layout Discovery Contract
## Module
Scanner
## Status
IMPLEMENTED
## Description
Standardized contract for discovering and mapping container filesystem layouts, enabling analyzers to locate language-specific artifacts across different container image structures.
## Implementation Details
- **Root File System Abstraction**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/FileSystem/IRootFileSystem.cs` - Interface for abstract root filesystem access
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/FileSystem/DirectoryRootFileSystem.cs` - Directory-backed root filesystem implementation
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/FileSystem/LayeredRootFileSystem.cs` - Layered (OCI) root filesystem implementation
- **OCI Image Context**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Oci/OciImageConfig.cs` - OCI image config model for container layout discovery
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntryTraceImageContextFactory.cs` - Creates image context for entrypoint analysis
- **Entry Trace Analyzer**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/IEntryTraceAnalyzer.cs` - Interface for entry trace analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntryTraceAnalyzer.cs` - Main analyzer discovering container layout and locating language-specific artifacts
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntryTraceContext.cs` - Context model with discovered layout info
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntryTraceTypes.cs` - Type definitions for discovered artifacts
- **Entrypoint Specification**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntrypointSpecification.cs` - Specifies expected entrypoints per container layout
- **DI**: `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/ServiceCollectionExtensions.cs`
## E2E Test Plan
- [ ] Scan a container image and verify the `EntryTraceAnalyzer` discovers the filesystem layout (root paths, language directories)
- [ ] Verify `LayeredRootFileSystem` correctly merges multiple OCI layers into a unified filesystem view
- [ ] Verify language-specific artifacts are located across different base images (Alpine, Debian, Ubuntu, distroless)
- [ ] Verify the OCI image config is parsed to determine CMD/ENTRYPOINT for entrypoint analysis
- [ ] Verify the layout discovery works for multi-stage build images with non-standard directory structures

View File

@@ -0,0 +1,35 @@
# Cross-Analyzer Identity Safety Contract
## Module
Scanner
## Status
IMPLEMENTED
## Description
Formal contract enforcing PURL vs explicit-key identity rules across all language analyzers, ensuring consistent component identification regardless of analyzer source.
## Implementation Details
- **Core Identity Types**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang/Core/LanguageExplicitKey.cs` - Explicit key identity model for non-PURL components
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang/Core/LanguageComponentRecord.cs` - Component record enforcing PURL or explicit-key identity
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang/Core/LanguageAnalyzerResult.cs` - Analyzer result with identity-safe component records
- **Language Analyzers** (all enforce the identity contract):
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet/DotNetLanguageAnalyzer.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/JavaLanguageAnalyzer.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node/NodeLanguageAnalyzer.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python/PythonLanguageAnalyzer.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Go/GoLanguageAnalyzer.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Rust/RustLanguageAnalyzer.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Ruby/RubyLanguageAnalyzer.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Php/PhpLanguageAnalyzer.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun/BunLanguageAnalyzer.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Deno/DenoLanguageAnalyzer.cs`
## E2E Test Plan
- [ ] Scan an image with packages from multiple ecosystems (npm, pip, NuGet, Maven) and verify all components have either a valid PURL or explicit-key identity
- [ ] Verify no component has both PURL and explicit-key set simultaneously (mutual exclusion)
- [ ] Verify components from the same package across different analyzers produce the same identity
- [ ] Verify PURL normalization is consistent (lowercase scheme, correct type mapping)
- [ ] Scan with a package that has no PURL mapping and verify explicit-key is used as fallback
- [ ] Verify the identity contract is enforced in SBOM output (all components have valid identifiers)

View File

@@ -0,0 +1,27 @@
# CycloneDX 1.7 CBOM (Cryptographic Bill of Materials) Support
## Module
Scanner
## Status
IMPLEMENTED
## Description
Cryptographic Bill of Materials support with crypto asset extraction for .NET, Java, and Node.js ecosystems. Includes CBOM aggregation service, serializer, and policy crypto risk rules. Distinct from standard SBOM support -- this inventories cryptographic algorithms and primitives across components.
## Implementation Details
- **CBOM Aggregation & Serialization**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Cbom/CbomAggregationService.cs` - Aggregates crypto assets from all analyzers into unified CBOM
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Cbom/CbomSerializer.cs` - Serializes CBOM data to CycloneDX format
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/CycloneDxCbomWriter.cs` - Writes CycloneDX 1.7 CBOM output
- **Per-Ecosystem Crypto Extractors**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet/Internal/Crypto/DotNetCryptoExtractor.cs` - .NET crypto asset extraction
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Crypto/JavaCryptoExtractor.cs` - Java crypto asset extraction
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node/Internal/Crypto/NodeCryptoExtractor.cs` - Node.js crypto asset extraction
## E2E Test Plan
- [ ] Scan a container image with .NET, Java, or Node.js applications and verify CBOM extraction identifies cryptographic assets
- [ ] Verify the CBOM aggregation service merges crypto assets from multiple ecosystem analyzers
- [ ] Export the scan results as CycloneDX 1.7 and verify `cryptoProperties` fields are populated
- [ ] Verify crypto algorithms (AES, RSA, SHA-256, etc.) are inventoried with correct metadata
- [ ] Verify policy crypto risk rules flag weak or deprecated algorithms in the CBOM

View File

@@ -0,0 +1,30 @@
# CycloneDX 1.7 Native Evidence Field Population
## Module
Scanner
## Status
IMPLEMENTED
## Description
Replaces custom `stellaops:evidence[n]` properties with spec-compliant CycloneDX 1.7 `component.evidence.*` structures (Identity, Occurrences, Licenses, Copyright). Ensures SBOM evidence data uses standard fields instead of vendor extensions.
## Implementation Details
- **Evidence Builders**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Evidence/IdentityEvidenceBuilder.cs` - Builds `component.evidence.identity` fields
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Evidence/OccurrenceEvidenceBuilder.cs` - Builds `component.evidence.occurrences` fields
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Evidence/LicenseEvidenceBuilder.cs` - Builds `component.evidence.licenses` fields
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Evidence/CallstackEvidenceBuilder.cs` - Builds callstack evidence fields
- **Evidence Mapping**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Evidence/CycloneDxEvidenceMapper.cs` - Maps internal evidence data to CycloneDX 1.7 evidence structures
- **Composition Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/CycloneDxComposer.cs` - Composes evidence into CycloneDX output
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/CycloneDxLayerWriter.cs` - Per-layer CycloneDX writer with evidence fields
## E2E Test Plan
- [ ] Scan a container image and export as CycloneDX 1.7 JSON
- [ ] Verify `component.evidence.identity` fields are populated for components with identity evidence
- [ ] Verify `component.evidence.occurrences` fields contain file location evidence
- [ ] Verify `component.evidence.licenses` fields contain license evidence
- [ ] Verify no custom `stellaops:evidence[n]` properties remain in the output
- [ ] Validate the output against the CycloneDX 1.7 JSON schema

View File

@@ -0,0 +1,42 @@
# Dataflow-Aware Diffs (Entrypoint-to-Sink Reachability)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Semantic entrypoint orchestrator with dataflow boundary analysis, data boundary mapping, and service security dataflow analyzer for entrypoint-to-sink reachability.
## Implementation Details
- **Semantic Entrypoint Orchestrator**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/SemanticEntrypointOrchestrator.cs` - Orchestrates semantic entrypoint analysis across languages
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/ISemanticEntrypointAnalyzer.cs` - Interface for semantic analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/SemanticEntryTraceAnalyzer.cs` - Trace analyzer for dataflow
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/SemanticEntrypoint.cs` - Entrypoint model
- **Data Boundary Analysis**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/Analysis/DataBoundaryMapper.cs` - Maps data flow boundaries
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/DataFlowBoundary.cs` - Data flow boundary model
- **Capability & Threat Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/Analysis/CapabilityDetector.cs` - Detects capabilities (network, file, crypto, etc.)
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/Analysis/ThreatVectorInferrer.cs` - Infers threat vectors from entrypoint-to-sink paths
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/CapabilityClass.cs` - Capability class model
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/ThreatVector.cs` - Threat vector model
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/ApplicationIntent.cs` - Application intent model
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/SemanticConfidence.cs` - Confidence scoring
- **Language Adapters**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/Adapters/DotNetSemanticAdapter.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/Adapters/JavaSemanticAdapter.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/Adapters/NodeSemanticAdapter.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/Adapters/PythonSemanticAdapter.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/Adapters/GoSemanticAdapter.cs`
- **Service Security**: `src/Scanner/__Libraries/StellaOps.Scanner.ServiceSecurity/` - Service-level dataflow security analysis
## E2E Test Plan
- [ ] Scan a container image with a web application and verify entrypoint-to-sink dataflow paths are detected
- [ ] Verify `DataBoundaryMapper` identifies data flow boundaries (e.g., user input -> database, network -> filesystem)
- [ ] Verify `CapabilityDetector` identifies application capabilities (network access, file I/O, crypto usage)
- [ ] Verify `ThreatVectorInferrer` infers threat vectors from detected dataflow paths
- [ ] Verify language-specific semantic adapters work for .NET, Java, Node.js, Python, and Go applications
- [ ] Verify dataflow-aware diff results appear in the scan report

View File

@@ -0,0 +1,34 @@
# Delta Layer Scanning Engine
## Module
Scanner
## Status
IMPLEMENTED
## Description
Container image delta scanning engine that scans only changed layers between image versions by diffID comparison, reusing cached per-layer SBOMs for unchanged layers. Produces DSSE-wrapped delta evidence with Rekor anchoring. Targets 70%+ CVE churn reduction on minor base image bumps.
## Implementation Details
- **Core Delta Scanner**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Delta/IDeltaLayerScanner.cs` - Interface for delta layer scanning
- `src/Scanner/__Libraries/StellaOps.Scanner.Delta/DeltaLayerScanner.cs` - Scans only changed layers by diffID comparison, reuses cached per-layer SBOMs
- **Delta Evidence**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Delta/Evidence/IDeltaEvidenceComposer.cs` - Interface for composing delta evidence
- `src/Scanner/__Libraries/StellaOps.Scanner.Delta/Evidence/DeltaEvidenceComposer.cs` - Composes DSSE-wrapped delta evidence with Rekor anchoring
- `src/Scanner/__Libraries/StellaOps.Scanner.Delta/Evidence/DeltaScanPredicate.cs` - Delta scan predicate model
- **WebService Integration**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/IDeltaScanRequestHandler.cs` - Delta scan request handler interface
- `src/Scanner/StellaOps.Scanner.WebService/Services/DeltaScanRequestHandler.cs` - Handles delta scan API requests
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/DeltaCompareEndpoints.cs` - Delta comparison API endpoints
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/DeltaEvidenceEndpoints.cs` - Delta evidence API endpoints
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/DeltaCompareContracts.cs` - API contracts
## E2E Test Plan
- [ ] Scan two versions of the same image with minor base image changes
- [ ] Verify only changed layers are scanned (unchanged layers reuse cached SBOMs)
- [ ] Verify delta evidence is DSSE-wrapped and includes Rekor anchoring reference
- [ ] Call `GET /api/v1/delta/{baselineScanId}/{currentScanId}` and verify delta comparison results
- [ ] Call `GET /api/v1/delta/{scanId}/evidence` and verify delta evidence bundle
- [ ] Verify CVE churn is reduced (only changed-layer CVEs appear as new findings)
- [ ] Verify the delta scan completes significantly faster than a full scan

View File

@@ -0,0 +1,32 @@
# Derivative Distro Mapping for Backport Detection
## Module
Scanner
## Status
IMPLEMENTED
## Description
Cross-distro OVAL/CSAF mapping that enables fetching backport rules from derivative distros (RHEL->Alma/Rocky/CentOS, Ubuntu->LinuxMint/Pop!_OS, Debian->Ubuntu) with confidence penalty multipliers (0.95x for same-major, 0.80x for cross-family).
## Implementation Details
- **Pedigree & Backport Evidence**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Pedigree/FeedserPedigreeDataProvider.cs` - Provides pedigree data with cross-distro backport rules
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Pedigree/CycloneDxPedigreeMapper.cs` - Maps pedigree data including derivative distro mappings
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Pedigree/PatchInfoBuilder.cs` - Builds patch info with backport detection data
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Pedigree/PedigreeNotesGenerator.cs` - Generates pedigree notes with confidence levels
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Pedigree/IPedigreeDataProvider.cs` - Interface
- **Version Comparison Evidence**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Evidence/Models/VersionComparisonEvidence.cs` - Version comparison evidence for backport detection
- `src/Scanner/__Libraries/StellaOps.Scanner.Evidence/Models/DeltaSignatureEvidence.cs` - Delta signature evidence
- `src/Scanner/__Libraries/StellaOps.Scanner.Evidence/Models/EvidenceBundle.cs` - Evidence bundle model
- **VEX Gate Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Gate/VexGateService.cs` - VEX gate service considering backport status
- `src/Scanner/__Libraries/StellaOps.Scanner.Gate/VexGatePolicyEvaluator.cs` - Policy evaluator with backport awareness
## E2E Test Plan
- [ ] Scan an AlmaLinux image and verify backport rules are fetched from RHEL OVAL data with 0.95x confidence
- [ ] Scan a Linux Mint image and verify backport rules map from Ubuntu with appropriate confidence penalty
- [ ] Verify cross-family mapping (e.g., Debian rules applied to Ubuntu) uses 0.80x confidence multiplier
- [ ] Verify pedigree output includes derivative distro source attribution
- [ ] Verify backport evidence reduces false positive vulnerability counts for patched packages

View File

@@ -0,0 +1,42 @@
# Deterministic Diff-Aware Rescans (SmartDiff / Diff-Native CI)
## Module
Scanner
## Status
IMPLEMENTED
## Description
SmartDiff with golden fixture tests, schema validation, state comparison, reachability gates, SARIF output, performance benchmarks, and layer caching for diff-native CI capability.
## Implementation Details
- **SmartDiff Core**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/SmartDiffPredicate.cs` - SmartDiff predicate model
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/SmartDiffJsonSerializer.cs` - JSON serialization for determinism
- **Detection Engine**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/MaterialRiskChangeDetector.cs` - Detects material risk changes between scans
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/MaterialRiskChangeResult.cs` - Detection result model
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/RiskStateSnapshot.cs` - Risk state snapshot for comparison
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/SmartDiffScoringConfig.cs` - Scoring configuration
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/BoundaryProof.cs` - Boundary proof model
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/ReachabilityGateBridge.cs` - Reachability gate integration
- **VEX Candidate Emission**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/VexCandidateEmitter.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/VexCandidateModels.cs`
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/VexEvidence.cs`
- **SARIF Output**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Output/SarifOutputGenerator.cs` - SARIF 2.1.0 output for CI integration
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Output/SarifModels.cs` - SARIF models
- **Attestation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Attestation/DeltaVerdictBuilder.cs` - Builds delta verdicts
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Attestation/DeltaVerdictOciPublisher.cs` - Publishes delta verdicts to OCI
- **API**: `src/Scanner/StellaOps.Scanner.WebService/Endpoints/SmartDiffEndpoints.cs` - SmartDiff REST API
## E2E Test Plan
- [ ] Run a SmartDiff between two scan versions and verify material risk changes are detected
- [ ] Verify golden fixture tests produce deterministic SmartDiff output
- [ ] Verify SmartDiff schema validation passes for generated predicates
- [ ] Verify SARIF output contains diff-aware findings suitable for CI integration
- [ ] Verify reachability gate context is included in SmartDiff results
- [ ] Verify VEX candidates are emitted from SmartDiff detection results
- [ ] Verify delta verdicts can be published to OCI registry

View File

@@ -0,0 +1,32 @@
# eBPF Capture Abstraction
## Module
Scanner
## Status
IMPLEMENTED
## Description
Platform-level eBPF capture adapter for Linux with runtime evidence aggregation, plus dedicated eBPF library at `src/Signals/__Libraries/StellaOps.Signals.Ebpf/` with probe loaders, parsers, and air-gap support.
## Implementation Details
- **Runtime Capture Adapters** (platform-specific):
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/IRuntimeCaptureAdapter.cs` - Interface for platform-specific runtime capture
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/LinuxEbpfCaptureAdapter.cs` - Linux eBPF capture adapter
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/MacOsDyldCaptureAdapter.cs` - macOS dyld capture adapter
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/WindowsEtwCaptureAdapter.cs` - Windows ETW capture adapter
- **Runtime Evidence**:
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/RuntimeEvidence.cs` - Runtime evidence model
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/RuntimeEvidenceAggregator.cs` - Aggregates runtime evidence from capture adapters
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/StackTraceCapture.cs` - Stack trace capture model
- **Capture Configuration**:
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/RuntimeCaptureOptions.cs` - Capture options
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/CaptureDurationTimer.cs` - Duration timer for capture sessions
## E2E Test Plan
- [ ] Configure eBPF capture on a Linux host and verify `LinuxEbpfCaptureAdapter` collects runtime library loading events
- [ ] Verify `RuntimeEvidenceAggregator` aggregates captured events into structured runtime evidence
- [ ] Verify stack trace capture captures function call chains from eBPF probes
- [ ] Verify capture duration timer correctly limits capture sessions
- [ ] Verify the capture adapter interface allows switching between eBPF (Linux), ETW (Windows), and dyld (macOS)
- [ ] Verify runtime evidence can be used to confirm/deny static reachability claims

View File

@@ -0,0 +1,27 @@
# Ecosystem-Specific Version Comparator Factory
## Module
Scanner
## Status
IMPLEMENTED
## Description
Factory providing ecosystem-specific version comparison logic for accurate vulnerability matching across different package ecosystems.
## Implementation Details
- **Version Comparators**:
- `src/Scanner/__Libraries/StellaOps.Scanner.ServiceSecurity/Analyzers/ServiceVersionComparer.cs` - Service-level version comparison
- `src/Scanner/__Libraries/StellaOps.Scanner.ServiceSecurity/Analyzers/ServiceVulnerabilityMatcher.cs` - Matches vulnerabilities using ecosystem-aware version comparison
- **Per-Language Conflict Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Conflicts/VersionConflictDetector.cs` - Java version conflict detection
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python/Internal/Conflicts/VersionConflictDetector.cs` - Python version conflict detection
- **Evidence Models**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Evidence/Models/VersionComparisonEvidence.cs` - Evidence model for version comparisons
## E2E Test Plan
- [ ] Scan an image with Java packages and verify Maven version semantics are used for vulnerability matching (e.g., `1.0.0-SNAPSHOT` vs `1.0.0`)
- [ ] Scan an image with Python packages and verify PEP 440 version comparison is applied
- [ ] Verify version conflict detection flags incompatible version ranges in dependencies
- [ ] Verify ecosystem-specific version comparison produces correct vulnerability match/no-match decisions
- [ ] Verify version comparison evidence is included in scan results

View File

@@ -0,0 +1,35 @@
# Entropy Analysis for Binaries
## Module
Scanner
## Status
IMPLEMENTED
## Description
Shannon entropy analysis pass integrated into the binary scanning pipeline, detecting packed/encrypted/obfuscated sections in ELF and PE binaries to flag suspicious artifacts.
## Implementation Details
- **Core Entropy Calculator**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Entropy/EntropyCalculator.cs` - Shannon entropy calculation
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Entropy/EntropyReportBuilder.cs` - Builds entropy analysis reports
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Entropy/EntropyReportModels.cs` - Report models
- **Worker Stage**:
- `src/Scanner/StellaOps.Scanner.Worker/Processing/Entropy/EntropyStageExecutor.cs` - Entropy analysis stage in scan pipeline
- **PE Hardening Integration**:
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/Hardening/PeHardeningExtractor.cs` - PE hardening extraction including entropy analysis
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/Hardening/HardeningFlags.cs` - Hardening flags model
- **API Contracts**:
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/EntropyContracts.cs` - Entropy analysis API contracts
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/ScanEndpoints.cs` - Exposes entropy data in scan results
- **Secrets Detection Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Secrets/Detectors/EntropyCalculator.cs` - Entropy calculator for secret detection
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Secrets/Detectors/EntropyDetector.cs` - High-entropy string detection for secrets
## E2E Test Plan
- [ ] Scan a container image containing packed/UPX-compressed ELF binaries and verify high entropy sections are flagged
- [ ] Scan an image with standard (non-packed) binaries and verify entropy values are within normal range
- [ ] Verify PE binary analysis includes entropy data for each section
- [ ] Verify entropy analysis results appear in scan API response
- [ ] Verify the `EntropyStageExecutor` runs as part of the scan pipeline
- [ ] Verify entropy-based secret detection flags high-entropy strings as potential secrets

View File

@@ -0,0 +1,44 @@
# EntryTrace Unified Entrypoint Analysis Framework
## Module
Scanner
## Status
IMPLEMENTED
## Description
Unified entrypoint detection and analysis framework that orchestrates semantic, temporal, mesh, speculative, binary, and risk analysis into a single EntryTrace pipeline with baseline comparison, caching, and serialization support.
## Implementation Details
- **Core Analyzer**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/IEntryTraceAnalyzer.cs` - Interface
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntryTraceAnalyzer.cs` - Main analyzer orchestrating all sub-analyses
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntryTraceContext.cs` - Context model
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntryTraceResult.cs` - Result model
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntryTraceTypes.cs` - Type definitions
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntryTraceAnalyzerOptions.cs` - Options
- **Semantic Analysis**: `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Semantic/` - Semantic entrypoint analysis with language adapters
- **Temporal Analysis**: `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Temporal/` - Temporal entrypoint drift detection
- **Mesh Analysis**: `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Mesh/` - Docker Compose and Kubernetes mesh entrypoint analysis
- **Speculative Execution**: `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Speculative/` - Symbolic execution for path enumeration
- **Binary Intelligence**: `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Binary/` - Function-level binary analysis
- **Risk Scoring**: `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Risk/` - Composite risk scoring
- **Baseline Comparison**: `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Baseline/` - Baseline analysis and comparison
- **Caching**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntryTraceCacheEnvelope.cs` - Cache envelope model
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntryTraceCacheSerializer.cs` - Cache serialization
- **Serialization**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Serialization/EntryTraceGraphSerializer.cs` - Graph serialization
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Serialization/EntryTraceNdjsonWriter.cs` - NDJSON writer
- **Worker Integration**:
- `src/Scanner/StellaOps.Scanner.Worker/Processing/EntryTraceExecutionService.cs` - Entry trace execution during scan
- **API**: `src/Scanner/StellaOps.Scanner.WebService/Contracts/EntryTraceResponse.cs` - API response contracts
## E2E Test Plan
- [ ] Scan a container image and verify the EntryTrace pipeline produces unified results combining semantic, binary, and mesh analysis
- [ ] Verify temporal drift detection identifies changed entrypoints between scan versions
- [ ] Verify mesh analysis discovers Docker Compose / Kubernetes service entrypoints
- [ ] Verify speculative execution enumerates possible execution paths from entrypoints
- [ ] Verify baseline comparison highlights new/removed/changed entrypoints
- [ ] Verify caching reduces analysis time on subsequent scans of the same image
- [ ] Verify entry trace results are available via `GET /api/v1/scans/{scanId}/entry-trace`

View File

@@ -0,0 +1,39 @@
# EPSS Change Events for Reanalysis Triggers
## Module
Scanner
## Status
IMPLEMENTED
## Description
Deterministic EPSS change events with per-CVE deltas, priority bands, idempotent event IDs, and scan manifests extended with tool versions and evidence digests for policy fingerprinting.
## Implementation Details
- **EPSS Change Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Epss/EpssChangeDetector.cs` - Detects EPSS score changes per CVE
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Epss/EpssChangeRecord.cs` - Change record model with deltas
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Epss/EpssChangeEvent.cs` - Deterministic change event with idempotent event ID
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Epss/Events/EpssUpdatedEvent.cs` - Updated event for signal dispatch
- **EPSS Provider & Caching**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Epss/IEpssProvider.cs` - Interface for EPSS data access
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Epss/EpssProvider.cs` - PostgreSQL-backed EPSS provider
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Epss/CachingEpssProvider.cs` - Cached EPSS provider
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Epss/EpssPriorityBand.cs` - Priority band classification
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Epss/EpssEvidence.cs` - EPSS evidence model
- **Signal Publishing**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Epss/IEpssSignalPublisher.cs` - Signal publisher interface
- **Worker Jobs**:
- `src/Scanner/StellaOps.Scanner.Worker/Processing/EpssEnrichmentJob.cs` - EPSS enrichment job
- `src/Scanner/StellaOps.Scanner.Worker/Processing/EpssIngestJob.cs` - EPSS data ingestion job
- `src/Scanner/StellaOps.Scanner.Worker/Processing/EpssSignalJob.cs` - EPSS signal dispatch job
- `src/Scanner/StellaOps.Scanner.Worker/Processing/EpssEnrichmentStageExecutor.cs` - Stage executor for scan pipeline
- **API**: `src/Scanner/StellaOps.Scanner.WebService/Endpoints/EpssEndpoints.cs` - `EpssEndpoints` with batch lookup, history, and status
## E2E Test Plan
- [ ] Ingest EPSS data and verify change detection identifies CVEs with score deltas
- [ ] Verify idempotent event IDs are deterministic for the same CVE/delta combination
- [ ] Verify priority band classification (critical, high, medium, low) based on EPSS score thresholds
- [ ] Verify EPSS change events trigger scan reanalysis for affected artifacts
- [ ] Call `POST /api/v1/epss/batch` with CVE IDs and verify EPSS scores are returned
- [ ] Call `GET /api/v1/epss/{cveId}/history` and verify EPSS score history with change events

View File

@@ -0,0 +1,29 @@
# ETW (Event Tracing for Windows) Collector for Runtime Traces
## Module
Scanner
## Status
IMPLEMENTED
## Description
ETW-based function tracing collector for Windows using CLR runtime provider and stack walking for call chains, with container-aware process isolation and DbgHelp symbol resolution.
## Implementation Details
- **ETW Capture Adapter**:
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/WindowsEtwCaptureAdapter.cs` - Windows ETW capture adapter implementing `IRuntimeCaptureAdapter`
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/IRuntimeCaptureAdapter.cs` - Platform-agnostic capture interface
- **Runtime Evidence**:
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/RuntimeEvidence.cs` - Runtime evidence model
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/RuntimeEvidenceAggregator.cs` - Aggregates ETW events into runtime evidence
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/StackTraceCapture.cs` - Stack trace capture from ETW stack walking
- **Capture Configuration**:
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/RuntimeCaptureOptions.cs` - Configuration options
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/CaptureDurationTimer.cs` - Duration timer
## E2E Test Plan
- [ ] Configure ETW capture on a Windows host and verify `WindowsEtwCaptureAdapter` collects CLR runtime events
- [ ] Verify stack walking captures call chains with correct function names via DbgHelp symbol resolution
- [ ] Verify container-aware process isolation filters events to the target container only
- [ ] Verify runtime evidence aggregation produces structured evidence from ETW events
- [ ] Verify ETW-collected runtime evidence can be used to confirm static reachability claims

View File

@@ -0,0 +1,23 @@
# Evidence Privacy Controls (Redaction Service)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Role-based evidence redaction with three levels: Full (no redaction for security_admin/evidence:full), Standard (redacts source code from reachability paths and call stack arguments/locals, keeps hashes and line ranges), and Minimal (strips reachability paths entirely, removes call stacks, reduces provenance to build ID/digest/verified flag, preserves VEX and EPSS public data). Supports field-level selective redaction (SourceCode, CallArguments flags). Determines redaction level from ClaimsPrincipal.
## Implementation Details
- **Redaction Service**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Evidence/Privacy/EvidenceRedactionService.cs` - Core redaction service with role-based level determination from ClaimsPrincipal
- `src/Scanner/__Libraries/StellaOps.Scanner.Evidence/Privacy/EvidenceRedactionLevel.cs` - Redaction level enum (Full, Standard, Minimal)
## E2E Test Plan
- [ ] Authenticate as `security_admin` and verify Full redaction level returns all evidence fields
- [ ] Authenticate as a standard user and verify Standard redaction level redacts source code and call stack arguments
- [ ] Authenticate with minimal permissions and verify Minimal redaction level strips reachability paths and call stacks
- [ ] Verify VEX and EPSS public data is preserved at all redaction levels
- [ ] Verify field-level selective redaction (SourceCode, CallArguments flags) works correctly
- [ ] Verify hash values and line ranges are preserved at Standard level

View File

@@ -0,0 +1,38 @@
# Explainable triage UX with evidence-linked findings
## Module
Scanner
## Status
IMPLEMENTED
## Description
Tabbed evidence panel with policy, binary diff, confidence meter, and SBOM evidence tabs provides expandable evidence views per finding.
## Implementation Details
- **Explainability Library**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Explainability/` - Explainability services for evidence-linked findings
- `src/Scanner/__Libraries/StellaOps.Scanner.Explainability/Dsse/ExplainabilityPredicateSerializer.cs` - Serializes explainability predicates
- `src/Scanner/__Libraries/StellaOps.Scanner.Explainability/Falsifiability/FalsifiabilityGenerator.cs` - Generates falsification criteria
- `src/Scanner/__Libraries/StellaOps.Scanner.Explainability/Falsifiability/FalsifiabilityCriteria.cs` - Criteria model
- **Triage Services**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Triage/` - Triage domain services
- `src/Scanner/__Libraries/StellaOps.Scanner.Triage/Models/ExploitPath.cs` - Exploit path model for evidence linking
- **Evidence Composition**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/EvidenceCompositionService.cs` - Composes multi-source evidence per finding
- `src/Scanner/StellaOps.Scanner.WebService/Services/IEvidenceCompositionService.cs` - Interface
- **Finding Rationale**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/FindingRationaleService.cs` - Provides rationale explanations per finding
- `src/Scanner/StellaOps.Scanner.WebService/Services/IFindingRationaleService.cs` - Interface
- **API**:
- `src/Scanner/StellaOps.Scanner.WebService/Controllers/FindingsEvidenceController.cs` - Evidence controller
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/FindingEvidenceContracts.cs` - Evidence API contracts
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/RationaleContracts.cs` - Rationale contracts
## E2E Test Plan
- [ ] Query finding evidence via the FindingsEvidenceController and verify tabbed evidence is returned
- [ ] Verify policy evidence tab includes applicable policy rules and evaluation results
- [ ] Verify binary diff evidence tab includes delta analysis when available
- [ ] Verify confidence meter shows score breakdown with contributing factors
- [ ] Verify SBOM evidence tab includes component provenance and version data
- [ ] Verify finding rationale service provides human-readable explanations

View File

@@ -0,0 +1,26 @@
# Exploit Path Grouping Service (Attack Chain Triage)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Groups vulnerability findings into exploit paths based on (artifact, package, vulnerable symbol, entry point) tuples with deterministic SHA-256 path IDs. Correlates reachability evidence, VEX status, and active exceptions per path. Falls back to package-level grouping when no reachability data is available. Sorted by aggregated risk score.
## Implementation Details
- **Core Service**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Triage/Services/IExploitPathGroupingService.cs` - Interface for exploit path grouping
- `src/Scanner/__Libraries/StellaOps.Scanner.Triage/Models/ExploitPath.cs` - Exploit path model with deterministic SHA-256 path IDs
- **API Integration**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/Triage/TriageInboxEndpoints.cs` - Triage inbox with exploit path grouping
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/Triage/ProofBundleEndpoints.cs` - Proof bundle endpoints including exploit path summaries (`ExploitPathSummary`)
## E2E Test Plan
- [ ] Scan an image with multiple vulnerabilities sharing the same entry point and verify they are grouped into a single exploit path
- [ ] Verify exploit path IDs are deterministic SHA-256 hashes of (artifact, package, vulnerable symbol, entry point) tuples
- [ ] Verify each exploit path correlates reachability evidence, VEX status, and active exceptions
- [ ] Verify fallback to package-level grouping when no reachability data is available
- [ ] Verify exploit paths are sorted by aggregated risk score (highest first)
- [ ] Query the triage inbox via API and verify grouped findings are returned

View File

@@ -0,0 +1,27 @@
# False-negative drift (FN-Drift) tracking and metrics
## Module
Scanner
## Status
IMPLEMENTED
## Description
FN-Drift calculation, metrics export, and classification change history tracking with dedicated Postgres migration.
## Implementation Details
- **FN-Drift Calculation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Services/FnDriftCalculator.cs` - Calculates false-negative drift metrics
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Services/FnDriftMetricsExporter.cs` - Exports FN-Drift metrics for telemetry
- **Classification Change Tracking**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Services/ClassificationChangeTracker.cs` - Tracks classification changes over time
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Models/ClassificationChangeModels.cs` - Change models
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Repositories/IClassificationHistoryRepository.cs` - Repository interface
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Repositories/ClassificationHistoryRepository.cs` - PostgreSQL repository
## E2E Test Plan
- [ ] Run multiple scans over time and verify `FnDriftCalculator` computes drift metrics based on classification changes
- [ ] Verify classification change history is persisted and queryable
- [ ] Verify FN-Drift metrics are exported to the telemetry system
- [ ] Verify classification changes (e.g., vulnerable -> not_affected -> vulnerable) are tracked with timestamps
- [ ] Verify drift metrics accurately reflect the rate of false-negative changes over time

View File

@@ -0,0 +1,26 @@
# Falsification Conditions Per Finding
## Module
Scanner
## Status
IMPLEMENTED
## Description
Each vulnerability finding includes falsification conditions -- specific criteria that would disprove the finding, enabling evidence-based triage and automatic dismissal when conditions are met.
## Implementation Details
- **Core Models**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Models/FalsificationConditions.cs` - Falsification conditions model attached to findings
- **Falsifiability Generation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Explainability/Falsifiability/FalsifiabilityGenerator.cs` - Generates falsification criteria per finding
- `src/Scanner/__Libraries/StellaOps.Scanner.Explainability/Falsifiability/FalsifiabilityCriteria.cs` - Criteria model defining what would disprove a finding
- **DSSE Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Explainability/Dsse/ExplainabilityPredicateSerializer.cs` - Serializes falsification conditions in DSSE predicates
## E2E Test Plan
- [ ] Scan an image and verify vulnerability findings include falsification conditions
- [ ] Verify falsification criteria specify concrete conditions (e.g., "function X is not called", "package Y is not in runtime classpath")
- [ ] Verify automatic dismissal occurs when falsification conditions are met by evidence (e.g., reachability proves function is unreachable)
- [ ] Verify falsification conditions are serialized in explainability predicates
- [ ] Verify triage UI displays falsification conditions to help analysts evaluate findings

View File

@@ -0,0 +1,30 @@
# Feature Flag Gate Conditions in Reachability Verdicts
## Module
Scanner
## Status
IMPLEMENTED
## Description
Detects feature flag gates on reachability paths and marks paths as "conditionally reachable" with specific flag name/condition requirements. Gated paths receive 0.5x confidence multiplier.
## Implementation Details
- **Feature Flag Detector**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/Detectors/FeatureFlagDetector.cs` - Detects feature flag conditions on reachability paths
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/Detectors/IGateDetector.cs` - Gate detector interface
- **Gate Models & Scoring**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/GateModels.cs` - Gate models including feature flag conditions
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/GatePatterns.cs` - Pattern matching for feature flag detection
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/GateMultiplierCalculator.cs` - Applies 0.5x confidence multiplier for feature-flag-gated paths
- **Rich Graph Annotation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Gates/RichGraphGateAnnotator.cs` - Annotates rich graph with feature flag gate information
- **Conditional Reachability**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/ConditionalReachabilityAnalyzer.cs` - Marks paths as "conditionally reachable"
## E2E Test Plan
- [ ] Scan an image with code behind feature flags (e.g., `if (featureEnabled("X"))`) and verify paths are detected as conditionally reachable
- [ ] Verify the feature flag name/condition is captured in the reachability verdict
- [ ] Verify gated paths receive 0.5x confidence multiplier in risk scoring
- [ ] Verify rich graph annotations include feature flag gate details
- [ ] Verify reachability status shows "conditionally reachable" vs "reachable" distinction

View File

@@ -0,0 +1,31 @@
# Finding Evidence API Contracts (BoundaryProof, VexEvidence, ScoreExplanation)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Unified evidence API data contracts defining FindingEvidenceResponse, BoundaryProof (surface, exposure, auth, controls), VexEvidence (status, justification, source), and ScoreExplanation (additive risk score breakdown with contributions) as immutable record types with JSON serialization.
## Implementation Details
- **Evidence Contracts**:
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/FindingEvidenceContracts.cs` - `FindingEvidenceResponse`, `BoundaryProof`, `VexEvidence`, `ScoreExplanation` as immutable record types
- **Unified Evidence Contracts**:
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/UnifiedEvidenceContracts.cs` - Unified evidence response contracts
- **Controller**:
- `src/Scanner/StellaOps.Scanner.WebService/Controllers/FindingsEvidenceController.cs` - `FindingsEvidenceController` serving evidence data
- **Evidence Service**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/IUnifiedEvidenceService.cs` - `IUnifiedEvidenceService` interface
- `src/Scanner/StellaOps.Scanner.WebService/Services/UnifiedEvidenceService.cs` - Assembles unified evidence per finding
- **SmartDiff Boundary Proof**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/BoundaryProof.cs` - Boundary proof model
## E2E Test Plan
- [ ] Query finding evidence via the FindingsEvidenceController and verify `FindingEvidenceResponse` is returned
- [ ] Verify `BoundaryProof` includes surface, exposure, auth, and controls data
- [ ] Verify `VexEvidence` includes status, justification, and source information
- [ ] Verify `ScoreExplanation` includes additive risk score breakdown with individual contributions
- [ ] Verify all contracts serialize as immutable JSON records
- [ ] Verify unified evidence endpoint aggregates all evidence types per finding

View File

@@ -0,0 +1,31 @@
# FindingEvidence Composition API Endpoint
## Module
Scanner
## Status
IMPLEMENTED
## Description
REST API endpoint that composes per-finding evidence bundles by aggregating SBOM slices, reachability proofs, VEX documents, and attestation chains into a unified evidence response. EvidenceCompositionService orchestrates multi-source evidence assembly on demand.
## Implementation Details
- **Evidence Composition Service**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/IEvidenceCompositionService.cs` - `IEvidenceCompositionService` interface
- `src/Scanner/StellaOps.Scanner.WebService/Services/EvidenceCompositionService.cs` - Orchestrates multi-source evidence assembly (SBOM slices, reachability, VEX, attestations)
- `src/Scanner/StellaOps.Scanner.WebService/Services/EvidenceCompositionService.cs` - `EvidenceCompositionOptions` for configuring evidence sources
- **Evidence Endpoints**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/EvidenceEndpoints.cs` - `EvidenceEndpoints` for listing and querying evidence
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/ReachabilityEvidenceEndpoints.cs` - Reachability-specific evidence endpoints
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/DeltaEvidenceEndpoints.cs` - Delta evidence endpoints
- **Evidence Export**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/IEvidenceBundleExporter.cs` - Evidence bundle export interface
- `src/Scanner/StellaOps.Scanner.WebService/Services/EvidenceBundleExporter.cs` - Exports evidence bundles in multiple formats
## E2E Test Plan
- [ ] Call the evidence composition endpoint for a specific finding and verify a unified evidence response is returned
- [ ] Verify the response includes SBOM slice data for the affected component
- [ ] Verify the response includes reachability proof when reachability analysis was performed
- [ ] Verify the response includes VEX document references when VEX data is available
- [ ] Verify the response includes attestation chain verification status
- [ ] Verify evidence bundle export works in supported formats

View File

@@ -0,0 +1,37 @@
# FuncProof Pipeline (Function-Level Proof Generation, DSSE Signing, OCI Publishing)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Complete pipeline for generating function-level proof objects from binary analysis. Includes DWARF/symbol/heuristic function boundary detection, BLAKE3/SHA-256 function-range hashing, DSSE envelope signing, Rekor transparency log integration, OCI referrer publishing, CycloneDX 1.6 callflow evidence linking, PostgreSQL storage, and configurable generation options.
## Implementation Details
- **Binary Function Analysis**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Binary/BinaryIntelligenceAnalyzer.cs` - Function boundary detection (DWARF/symbol/heuristic)
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Binary/CodeFingerprint.cs` - Code fingerprint model
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Binary/IFingerprintGenerator.cs` - Fingerprint generation interface
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Binary/FingerprintCorpusBuilder.cs` - Builds fingerprint corpus
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Binary/SymbolInfo.cs` - Symbol info model
- **Proof of Exposure**:
- `src/Scanner/StellaOps.Scanner.Worker/Orchestration/PoEOrchestrator.cs` - Proof-of-Exposure orchestrator
- `src/Scanner/StellaOps.Scanner.Worker/Processing/PoE/PoEGenerationStageExecutor.cs` - PoE generation stage executor
- **DSSE Signing**:
- `src/Scanner/StellaOps.Scanner.Worker/Processing/Surface/HmacDsseEnvelopeSigner.cs` - HMAC-based DSSE signing
- `src/Scanner/StellaOps.Scanner.Worker/Processing/Surface/IDsseEnvelopeSigner.cs` - DSSE signing interface
- **OCI Publishing**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/IOciAttestationPublisher.cs` - OCI attestation publisher interface
- `src/Scanner/StellaOps.Scanner.WebService/Services/OciAttestationPublisher.cs` - Publishes attestations to OCI registries
- **Evidence Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Evidence/CallstackEvidenceBuilder.cs` - CycloneDX callflow evidence linking
## E2E Test Plan
- [ ] Scan a container image with native binaries and verify function-level proof objects are generated
- [ ] Verify function boundary detection works for DWARF debug info, symbol tables, and heuristic detection
- [ ] Verify function-range hashing produces BLAKE3/SHA-256 fingerprints
- [ ] Verify DSSE envelope signing wraps proof objects
- [ ] Verify OCI referrer publishing attaches proofs to the image manifest
- [ ] Verify CycloneDX callflow evidence links proofs to vulnerability findings

View File

@@ -0,0 +1,32 @@
# Gated Triage Contracts (Quiet-by-Design Backend)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Backend contracts for Quiet-by-Design Triage that expose why findings are hidden by default (unreachable, policy_dismissed, backported, vex_not_affected) with links to evidence artifacts and gated bucket count summaries in bulk queries.
## Implementation Details
- **Gating Contracts**:
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/GatingContracts.cs` - Gating reason contracts (unreachable, policy_dismissed, backported, vex_not_affected)
- **Gating Reason Service**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/IGatingReasonService.cs` - Interface for gating reason queries
- `src/Scanner/StellaOps.Scanner.WebService/Services/GatingReasonService.cs` - Provides gating reasons with evidence links
- **Triage API**:
- `src/Scanner/StellaOps.Scanner.WebService/Controllers/TriageController.cs` - `TriageController` with `BulkGatingStatusRequest` for bulk queries
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/Triage/TriageStatusEndpoints.cs` - Triage status endpoints
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/TriageContracts.cs` - Triage API contracts
- **VEX Gate Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Gate/VexGateService.cs` - VEX gate service for determining gating status
- `src/Scanner/__Libraries/StellaOps.Scanner.Gate/VexGateResult.cs` - Gate result model
## E2E Test Plan
- [ ] Query findings and verify gated findings include the gating reason (unreachable, policy_dismissed, backported, vex_not_affected)
- [ ] Verify each gating reason includes links to supporting evidence artifacts
- [ ] Submit a bulk gating status request and verify gated bucket count summaries are returned
- [ ] Verify unreachable findings are gated with reachability evidence links
- [ ] Verify backported findings are gated with backport evidence links
- [ ] Verify VEX not_affected findings are gated with VEX document references

View File

@@ -0,0 +1,26 @@
# GitHub Code Scanning Endpoints (Backend)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Backend endpoints for triggering SARIF uploads to GitHub Code Scanning are implemented, with a null service for environments without GitHub integration.
## Implementation Details
- **Endpoints**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/GitHubCodeScanningEndpoints.cs` - `GitHubCodeScanningEndpoints` with `SarifUploadRequest`, `SarifUploadResponse`, `SarifUploadStatusResponse`, `AlertsListResponse`, `AlertResponse`
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/GitHubCodeScanningEndpoints.cs` - `IGitHubCodeScanningService` interface, `GitHubUploadResult`, `GitHubUploadStatus`
- **Null Service**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/NullGitHubCodeScanningService.cs` - Null implementation for environments without GitHub
- **SARIF Export**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/ScanFindingsSarifExportService.cs` - Exports scan findings as SARIF for GitHub upload
## E2E Test Plan
- [ ] Upload a SARIF report to GitHub Code Scanning via the endpoint and verify acceptance
- [ ] Query upload status and verify it returns the correct status (pending, complete, error)
- [ ] Query alerts list and verify findings appear as GitHub Code Scanning alerts
- [ ] Verify the null service returns appropriate responses when GitHub integration is not configured
- [ ] Verify SARIF export includes all scan findings with correct location and severity mapping

View File

@@ -0,0 +1,27 @@
# Ground Truth Corpus and Benchmark Evaluator
## Module
Scanner
## Status
IMPLEMENTED
## Description
Benchmark infrastructure with corpus manifests and metrics calculation exists for measuring scanner precision.
## Implementation Details
- **Corpus Management**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Benchmark/Corpus/CorpusManifest.cs` - Corpus manifest model for benchmark datasets
- `src/Scanner/__Libraries/StellaOps.Scanner.Benchmark/Corpus/FindingClassification.cs` - Finding classification (TP/FP/FN/TN) for ground truth comparison
- **Benchmark Libraries**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Benchmark/` - Benchmark infrastructure
- `src/Scanner/__Libraries/StellaOps.Scanner.Benchmarks/` - Additional benchmark utilities
- **Benchmark Tests**:
- `src/Scanner/__Benchmarks/` - Performance benchmarks
## E2E Test Plan
- [ ] Load a ground truth corpus manifest and verify it defines expected findings with classifications
- [ ] Run the scanner against a benchmark corpus and verify precision/recall metrics are computed
- [ ] Verify TP/FP/FN/TN classifications match the ground truth
- [ ] Verify benchmark results are deterministic across runs
- [ ] Verify corpus manifests can be versioned for regression tracking

View File

@@ -0,0 +1,27 @@
# Human Approval Attestation Service (stella.ops/human-approval@v1 predicate)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Generates DSSE-signed attestations for human approval decisions with 30-day TTL auto-expiry. Uses stella.ops/human-approval@v1 predicate. Integrates with the Approvals API (POST/GET/DELETE /api/v1/scans/{scanId}/approvals).
## Implementation Details
- **Attestation Service**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/IHumanApprovalAttestationService.cs` - `IHumanApprovalAttestationService`, `HumanApprovalAttestationInput`, `HumanApprovalAttestationResult`
- `src/Scanner/StellaOps.Scanner.WebService/Services/HumanApprovalAttestationService.cs` - Generates DSSE-signed attestations with 30-day TTL
- **Contracts**:
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/HumanApprovalStatement.cs` - `stella.ops/human-approval@v1` predicate model
- **API Endpoints**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/ApprovalEndpoints.cs` - `ApprovalEndpoints` with `CreateApprovalRequest`, `RevokeApprovalRequest`, `ApprovalResponse`, `ApprovalListResponse`
## E2E Test Plan
- [ ] Create a human approval via `POST /api/v1/scans/{scanId}/approvals` and verify a DSSE-signed attestation is generated
- [ ] Verify the attestation uses `stella.ops/human-approval@v1` predicate type
- [ ] Verify the attestation includes the approver identity, timestamp, and scope
- [ ] List approvals via `GET /api/v1/scans/{scanId}/approvals` and verify active approvals are returned
- [ ] Verify 30-day TTL auto-expiry removes expired approvals
- [ ] Revoke an approval via `DELETE /api/v1/scans/{scanId}/approvals/{approvalId}` and verify it is removed

View File

@@ -0,0 +1,29 @@
# Java Dependency Scope Classification
## Module
Scanner
## Status
IMPLEMENTED
## Description
Classifies Java dependencies into compile, test, provided, runtime, and system scopes from Maven/Gradle declarations, enabling scope-aware SBOM generation and reachability filtering.
## Implementation Details
- **Build Metadata**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/BuildMetadata/JavaDependencyDeclaration.cs` - Dependency declaration model with scope classification
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/BuildMetadata/JavaProjectMetadata.cs` - Project metadata with declared scopes
- **Maven POM Parsing**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Maven/MavenPomParser.cs` - Parses dependency scopes from POM files
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Maven/MavenBomImporter.cs` - Imports BOM dependencies with scope
- **Gradle Parsing**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Gradle/GradleGroovyParser.cs` - Parses compile/test/runtime configurations
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Gradle/GradleKotlinParser.cs` - Kotlin DSL scope extraction
- **Language Analyzer**: `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/JavaLanguageAnalyzer.cs`
## E2E Test Plan
- [ ] Scan a Maven project and verify dependencies are classified into compile, test, provided, runtime, and system scopes
- [ ] Scan a Gradle project and verify implementation/api/testImplementation/compileOnly configurations map to correct scopes
- [ ] Verify scope information is included in the generated SBOM
- [ ] Verify test-scope dependencies are excluded from reachability analysis by default
- [ ] Verify provided-scope dependencies are correctly handled for runtime vs compile-time analysis

View File

@@ -0,0 +1,28 @@
# Java Gradle Build File Parsing (Groovy/Kotlin/TOML)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Parses Gradle build files in three DSL formats (Groovy build.gradle, Kotlin build.gradle.kts, TOML version catalogs libs.versions.toml) to extract declared dependencies, plugins, and version constraints.
## Implementation Details
- **Gradle Parsers**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Gradle/GradleGroovyParser.cs` - Groovy `build.gradle` parser
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Gradle/GradleKotlinParser.cs` - Kotlin `build.gradle.kts` parser
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Gradle/GradleVersionCatalogParser.cs` - TOML `libs.versions.toml` version catalog parser
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Gradle/GradlePropertiesParser.cs` - `gradle.properties` parser for version variables
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Gradle/TomlParser.cs` - Generic TOML parser
- **Build File Discovery**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Discovery/JavaBuildFileDiscovery.cs` - Discovers build files in project structure
## E2E Test Plan
- [ ] Scan a container with a Groovy `build.gradle` project and verify dependencies are extracted with group, artifact, and version
- [ ] Scan a Kotlin `build.gradle.kts` project and verify dependencies are correctly parsed
- [ ] Scan a project using TOML version catalog (`libs.versions.toml`) and verify version references are resolved
- [ ] Verify plugin declarations are extracted from build files
- [ ] Verify version constraints (e.g., `strictly`, `prefer`, ranges) are captured
- [ ] Verify `gradle.properties` variables are interpolated in dependency versions

View File

@@ -0,0 +1,23 @@
# Java License Metadata with SPDX Normalization
## Module
Scanner
## Status
IMPLEMENTED
## Description
Extracts license metadata from Maven POM license blocks, Gradle metadata, and JAR META-INF/LICENSE files, normalizing free-text license names to SPDX expression identifiers.
## Implementation Details
- **License Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/License/JavaLicenseDetector.cs` - Detects licenses from POM, Gradle metadata, and META-INF/LICENSE files
- **SPDX Normalization**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/License/SpdxLicenseNormalizer.cs` - Normalizes free-text license names to SPDX expression identifiers
## E2E Test Plan
- [ ] Scan a Maven project and verify license metadata is extracted from POM `<licenses>` blocks
- [ ] Verify free-text license names (e.g., "The Apache License, Version 2.0") are normalized to SPDX identifiers (e.g., "Apache-2.0")
- [ ] Verify JAR META-INF/LICENSE file content is analyzed for license detection
- [ ] Verify license information appears in the generated SBOM
- [ ] Verify multi-license components produce valid SPDX expressions (e.g., "MIT OR Apache-2.0")

View File

@@ -0,0 +1,23 @@
# Java Lockfile Collector and CLI Validator
## Module
Scanner
## Status
IMPLEMENTED
## Description
Collects and validates Java dependency lockfiles (Gradle lockfile, Maven dependency:tree output) providing a CLI-accessible integrity check for pinned dependency versions.
## Implementation Details
- **Lockfile Collection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/JavaLockFileCollector.cs` - `JavaLockFileCollector` collects and validates Gradle lockfiles and Maven dependency:tree outputs for pinned dependency versions
- **Language Analyzer Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/JavaLanguageAnalyzer.cs` - `JavaLanguageAnalyzer` integrates lockfile collection into the analysis pipeline
## E2E Test Plan
- [ ] Scan a container image with a Gradle project containing `gradle.lockfile` and verify pinned dependency versions are collected
- [ ] Scan a Maven project with `dependency:tree` output and verify the lockfile collector parses resolved versions
- [ ] Verify lockfile integrity validation detects tampered or inconsistent lockfile entries
- [ ] Verify lockfile-collected versions take precedence over declared versions when both are available
- [ ] Verify missing lockfile scenarios are handled gracefully with appropriate warnings

View File

@@ -0,0 +1,28 @@
# Java Maven Parent POM Resolution with Property Interpolation
## Module
Scanner
## Status
IMPLEMENTED
## Description
Resolves Maven parent POM inheritance chains and interpolates ${property} placeholders in version, groupId, and artifactId fields across the effective POM hierarchy.
## Implementation Details
- **Parent POM Resolution**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Maven/MavenParentResolver.cs` - `MavenParentResolver` resolves parent POM inheritance chains by following `<parent>` declarations
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Maven/MavenEffectivePomBuilder.cs` - `MavenEffectivePomBuilder` constructs the effective POM by merging parent and child POM properties, dependencies, and plugin configurations
- **Property Interpolation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/PropertyResolution/JavaPropertyResolver.cs` - `JavaPropertyResolver` resolves `${property}` placeholders in version, groupId, and artifactId fields across the POM hierarchy
- **POM Parsing**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Maven/MavenPomParser.cs` - `MavenPomParser` parses POM XML files extracting dependency declarations, properties, and parent references
- **Language Analyzer**: `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/JavaLanguageAnalyzer.cs`
## E2E Test Plan
- [ ] Scan a Maven project with a parent POM hierarchy (child -> parent -> grandparent) and verify dependency versions inherited from parent are resolved
- [ ] Verify `${property}` placeholders in dependency versions are interpolated using properties from the effective POM hierarchy
- [ ] Verify `${project.version}` and `${project.groupId}` built-in properties are resolved correctly
- [ ] Verify `<dependencyManagement>` sections from parent POMs are applied to child dependency declarations without explicit versions
- [ ] Verify BOM imports (`<scope>import</scope>` in `<dependencyManagement>`) are resolved transitively
- [ ] Verify circular parent references are detected and handled gracefully

View File

@@ -0,0 +1,23 @@
# Java Multi-Version Conflict Detection
## Module
Scanner
## Status
IMPLEMENTED
## Description
Detects version conflicts where multiple versions of the same groupId:artifactId appear in the resolved dependency tree, flagging Maven nearest-wins and Gradle forced-version resolutions.
## Implementation Details
- **Conflict Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Conflicts/VersionConflictDetector.cs` - `VersionConflictDetector` identifies version conflicts where multiple versions of the same `groupId:artifactId` are resolved in the dependency tree, flagging Maven nearest-wins and Gradle forced-version resolution strategies
- **Language Analyzer Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/JavaLanguageAnalyzer.cs` - `JavaLanguageAnalyzer` integrates conflict detection into the analysis pipeline
## E2E Test Plan
- [ ] Scan a Maven project with diamond dependency conflicts (A depends on B:1.0 and C which depends on B:2.0) and verify the conflict is detected
- [ ] Verify Maven "nearest-wins" resolution strategy is correctly identified and the winning version is reported
- [ ] Scan a Gradle project with forced version constraints (`!!` or `force = true`) and verify forced resolutions are flagged
- [ ] Verify conflict detection results include both the requested and resolved versions for each conflicting dependency
- [ ] Verify conflict information appears in scan findings with appropriate severity classification

View File

@@ -0,0 +1,27 @@
# Java OSGi Bundle Manifest Parsing
## Module
Scanner
## Status
IMPLEMENTED
## Description
Parses OSGi bundle MANIFEST.MF headers (Bundle-SymbolicName, Import-Package, Export-Package, Require-Bundle) to discover embedded dependencies and version ranges in Eclipse/Karaf/Felix deployments.
## Implementation Details
- **OSGi Bundle Parsing**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Osgi/OsgiBundleParser.cs` - `OsgiBundleParser` parses MANIFEST.MF headers including `Bundle-SymbolicName`, `Import-Package`, `Export-Package`, and `Require-Bundle` to discover embedded dependencies and version ranges
- **Signature Manifest Analysis**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Signature/JavaSignatureManifestAnalyzer.cs` - Analyzes JAR signature manifests alongside bundle manifests
- **Entrypoint Resolution**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Resolver/JavaEntrypointResolution.cs` - Resolves entrypoints from bundle exports
- **Language Analyzer**: `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/JavaLanguageAnalyzer.cs`
## E2E Test Plan
- [ ] Scan a container image with an OSGi-based deployment (Eclipse/Karaf/Felix) and verify bundles are discovered from MANIFEST.MF files
- [ ] Verify `Bundle-SymbolicName` is extracted and mapped to component identifiers in the SBOM
- [ ] Verify `Import-Package` and `Export-Package` headers are parsed to identify inter-bundle dependencies with version ranges
- [ ] Verify `Require-Bundle` declarations are resolved to concrete bundle dependencies
- [ ] Verify version ranges in OSGi format (e.g., `[1.0,2.0)`) are correctly parsed and represented
- [ ] Verify embedded JAR bundles within OSGi containers are detected and attributed

View File

@@ -0,0 +1,25 @@
# Java Shaded/Shadow JAR Detection
## Module
Scanner
## Status
IMPLEMENTED
## Description
Detects Maven Shade plugin and Gradle Shadow plugin fat/uber JARs by analyzing relocated packages, service-provider rewrites, and embedded dependency manifests to attribute inner components.
## Implementation Details
- **Shaded JAR Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/Shading/ShadedJarDetector.cs` - `ShadedJarDetector` identifies Maven Shade and Gradle Shadow fat/uber JARs by analyzing relocated packages, service-provider rewrites, and embedded dependency manifests
- **Analysis Results**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/Internal/ShadedJarAnalysisResult.cs` - `ShadedJarAnalysisResult` model capturing detected shading details including relocated packages and embedded components
- **Language Analyzer Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/JavaLanguageAnalyzer.cs` - Integrates shaded JAR detection into the analysis pipeline
## E2E Test Plan
- [ ] Scan a container image with a Maven Shade plugin-produced uber JAR and verify embedded dependencies are attributed as inner components
- [ ] Scan a Gradle Shadow plugin-produced fat JAR and verify relocated packages are detected
- [ ] Verify service-provider rewrites (META-INF/services) from shading are identified and the original component is attributed
- [ ] Verify relocated package prefixes (e.g., `com.google.common` relocated to `shaded.com.google.common`) are detected and mapped back to the original dependency
- [ ] Verify the SBOM includes both the outer shaded JAR and the inner embedded dependencies with correct attribution

View File

@@ -0,0 +1,31 @@
# Kubernetes Boundary Extraction for Reachability and Proof Analysis
## Module
Scanner
## Status
IMPLEMENTED
## Description
Extracts network boundary information from Kubernetes Ingress, Service, and NetworkPolicy manifests to determine external exposure, cluster exposure level, and network controls (WAF/rate-limiting). Feeds boundary data into the reachability graph and produces boundary proof for internet-facing vs internal-only path classification. Priority 200 in extractor pipeline.
## Implementation Details
- **Kubernetes Boundary Extractor**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/K8sBoundaryExtractor.cs` - `K8sBoundaryExtractor` (implements `IBoundaryProofExtractor`) extracts boundary info from Kubernetes Ingress, Service, and NetworkPolicy manifests
- **Boundary Extraction Framework**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/IBoundaryProofExtractor.cs` - `IBoundaryProofExtractor` interface defining the boundary extraction contract
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/BoundaryExtractionContext.cs` - `BoundaryExtractionContext` provides context (manifest files, image metadata) for extraction
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/CompositeBoundaryExtractor.cs` - `CompositeBoundaryExtractor` composes multiple extractors (K8s, API Gateway, IaC) into a pipeline
- **Related Extractors**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/GatewayBoundaryExtractor.cs` - API gateway boundary extraction
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/IacBoundaryExtractor.cs` - Infrastructure-as-code boundary extraction
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/RichGraphBoundaryExtractor.cs` - Rich graph integration for boundary data
- **DI Registration**: `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/BoundaryServiceCollectionExtensions.cs`
## E2E Test Plan
- [ ] Provide a Kubernetes Ingress manifest referencing a scanned service and verify the K8s boundary extractor identifies it as internet-facing
- [ ] Provide a Kubernetes NetworkPolicy that restricts ingress to specific namespaces and verify the extractor classifies the service as internal-only
- [ ] Verify WAF annotations on Ingress resources (e.g., nginx WAF, ModSecurity) are detected as network controls
- [ ] Verify the composite boundary extractor aggregates results from K8s, API Gateway, and IaC extractors
- [ ] Verify boundary proof is produced and feeds into the reachability graph for path classification
- [ ] Verify Kubernetes Services without Ingress or LoadBalancer type are classified as cluster-internal

View File

@@ -0,0 +1,32 @@
# Layer-Aware SBOM Diff Engine
## Module
Scanner
## Status
IMPLEMENTED
## Description
Extension of the SBOM diff engine with layer attribution, tracking which container layer (by diffID) introduced each component change. Enables "blame" queries to identify which layer introduced a specific vulnerability. While "SBOM Delta / Component Diffing" exists in known features, layer-attributed diffing with per-layer blame is a distinct capability.
## Implementation Details
- **SBOM Diff Engine**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Lineage/SbomDiffEngine.cs` - `SbomDiffEngine` performs SBOM-level diffing with layer attribution, tracking which container layer (by diffID) introduced each component change
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Lineage/SbomDiff.cs` - `SbomDiff` model representing component changes with layer attribution
- **Lineage Infrastructure**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Lineage/SbomLineage.cs` - `SbomLineage` tracks the history of SBOMs across image versions for lineage-based diff
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Lineage/ISbomStore.cs` - `ISbomStore` interface for SBOM storage used by lineage tracking
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Lineage/RebuildProof.cs` - `RebuildProof` for reproducible rebuild verification
- **Component Diffing**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Diff/ComponentDiffer.cs` - `ComponentDiffer` performs component-level diff analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.Diff/ComponentDiffModels.cs` - Models for component diff results
- **Delta Layer Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Delta/DeltaLayerScanner.cs` - `DeltaLayerScanner` scans individual layers for delta analysis
## E2E Test Plan
- [ ] Scan two versions of a container image and verify the SBOM diff engine produces a layer-attributed diff showing which layer introduced each change
- [ ] Verify added components are attributed to the specific layer (by diffID) that introduced them
- [ ] Verify removed components are attributed to the layer where they were present in the previous image
- [ ] Run a "blame" query for a specific vulnerable component and verify it returns the layer that introduced it
- [ ] Verify lineage tracking correctly associates multiple image versions for historical diff analysis
- [ ] Verify the diff engine handles base image layer changes separately from application layer changes

View File

@@ -0,0 +1,41 @@
# Layer-SBOM Cache with Hash-Based Reuse
## Module
Scanner
## Status
IMPLEMENTED
## Description
Layer-level SBOM caching is implemented with a dedicated cache store, cache entries, put requests, maintenance service, and a LayerSbomService that integrates with the scanner pipeline.
## Implementation Details
- **Cache Abstractions**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/Abstractions/ILayerCacheStore.cs` - `ILayerCacheStore` interface defining cache operations (get, put, evict)
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/Abstractions/LayerCacheEntry.cs` - `LayerCacheEntry` model for cached layer SBOM data keyed by layer hash
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/Abstractions/LayerCachePutRequest.cs` - `LayerCachePutRequest` model for inserting new cache entries
- **Cache Store**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/LayerCache/LayerCacheStore.cs` - `LayerCacheStore` implementation with hash-based lookup and TTL-based eviction
- **Content-Addressable Storage**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/LayerSbomCas/ILayerSbomCas.cs` - `ILayerSbomCas` interface for content-addressable SBOM storage
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/LayerSbomCas/PostgresLayerSbomCas.cs` - `PostgresLayerSbomCas` PostgreSQL-backed content-addressable store for layer SBOMs
- **Maintenance**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/Maintenance/ScannerCacheMaintenanceService.cs` - `ScannerCacheMaintenanceService` handles cache cleanup, TTL-based eviction, and storage management
- **DI Registration**: `src/Scanner/__Libraries/StellaOps.Scanner.Cache/ScannerCacheServiceCollectionExtensions.cs`
- **WebService Integration**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/ILayerSbomService.cs` - `ILayerSbomService` interface for layer SBOM operations
- `src/Scanner/StellaOps.Scanner.WebService/Services/LayerSbomService.cs` - `LayerSbomService` integrates cache with the scanner pipeline
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/LayerSbomEndpoints.cs` - REST endpoints for layer SBOM retrieval
- **Layer Composition**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/LayerSbomComposer.cs` - Composes per-layer SBOMs
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/ILayerSbomWriter.cs` - Interface for writing per-layer SBOMs
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/SpdxLayerWriter.cs` - SPDX format layer writer
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/CycloneDxLayerWriter.cs` - CycloneDX format layer writer
## E2E Test Plan
- [ ] Scan an image and verify layer SBOMs are cached by layer hash in the content-addressable store
- [ ] Rescan an image sharing cached layers and verify cached layer SBOMs are reused (cache hit) without re-analysis
- [ ] Verify cache entries include correct TTL metadata and are evicted after expiry by the maintenance service
- [ ] Retrieve a per-layer SBOM via the `LayerSbomEndpoints` REST API and verify it contains the correct components for that layer
- [ ] Verify cache put requests correctly store new layer SBOM data with content-addressed keys
- [ ] Verify the maintenance service runs periodic cleanup and removes stale cache entries

View File

@@ -0,0 +1,40 @@
# Layered Resolver Pipeline (ELF/PE Feature Extraction)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Binary analysis with call graph extraction for ELF/PE formats and patch verification orchestration.
## Implementation Details
- **Binary Call Graph Extraction**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/BinaryCallGraphExtractor.cs` - `BinaryCallGraphExtractor` extracts call graphs from ELF/PE binaries
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/BinaryEntrypointClassifier.cs` - Classifies binary entrypoints (main, DllMain, init/fini)
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/FunctionBoundaryDetector.cs` - Detects function boundaries in binary code
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/DwarfDebugReader.cs` - Reads DWARF debug information from ELF binaries
- **Disassembly**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Disassembly/X86Disassembler.cs` - x86/x64 disassembly for call graph extraction
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Disassembly/Arm64Disassembler.cs` - ARM64 disassembly support
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Disassembly/DirectCallExtractor.cs` - Extracts direct call targets from disassembled code
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Disassembly/BinaryTextSectionReader.cs` - Reads .text sections from binaries
- **Binary Analysis**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Analysis/BinaryDynamicLoadDetector.cs` - Detects dlopen/LoadLibrary dynamic loading patterns
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Analysis/BinaryStringLiteralScanner.cs` - Scans string literals for library references
- **Patch Verification**:
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/PatchVerificationOrchestrator.cs` - `PatchVerificationOrchestrator` coordinates patch verification steps
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/IPatchVerificationOrchestrator.cs` - Interface for orchestrator
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Models/PatchVerificationResult.cs` - Verification result with status and evidence
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Models/PatchVerificationEvidence.cs` - Evidence collected during verification
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Services/IPatchSignatureStore.cs` - Interface for patch signature storage
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/Services/InMemoryPatchSignatureStore.cs` - In-memory patch signature store
## E2E Test Plan
- [ ] Scan a container image containing ELF binaries and verify call graph extraction produces function nodes and call edges
- [ ] Scan a container with PE (Windows) binaries and verify PE-specific features (DllMain, exports) are extracted
- [ ] Verify DWARF debug information is used to enrich function names when available
- [ ] Verify dynamic loading patterns (dlopen/LoadLibrary) are detected and reported
- [ ] Verify patch verification orchestrator validates that a claimed patch is present in the binary
- [ ] Verify patch signature store records and retrieves known patch signatures for comparison

View File

@@ -0,0 +1,29 @@
# macOS Bundle Inspector with Capability Overlays
## Module
Scanner
## Status
IMPLEMENTED
## Description
Inspects macOS .app/.framework bundles, parsing Info.plist for metadata and entitlements for security capability analysis (sandbox, hardened runtime, network access flags).
## Implementation Details
- **Bundle Analyzer**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.MacOsBundle/MacOsBundleAnalyzer.cs` - `MacOsBundleAnalyzer` inspects macOS .app/.framework bundles, extracting metadata and security capabilities
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.MacOsBundle/MacOsBundleAnalyzerPlugin.cs` - Plugin registration for the macOS bundle analyzer
- **Parsers**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.MacOsBundle/InfoPlistParser.cs` - `InfoPlistParser` parses Info.plist files for bundle metadata (CFBundleIdentifier, version, minimum OS)
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.MacOsBundle/EntitlementsParser.cs` - `EntitlementsParser` parses entitlements XML for security capability analysis (sandbox, hardened runtime, network access)
- **Mach-O Analysis**:
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/MachOReader.cs` - `MachOReader` reads Mach-O binary format headers and load commands
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/MachOCodeSignature.cs` - `MachOCodeSignature` extracts code signature information from Mach-O binaries
## E2E Test Plan
- [ ] Scan a container image containing a macOS .app bundle and verify Info.plist metadata is extracted (bundle identifier, version, minimum OS version)
- [ ] Verify entitlements are parsed and security capabilities (sandbox, hardened runtime) are identified
- [ ] Verify network access entitlements (com.apple.security.network.client/server) are detected and reported as capability overlays
- [ ] Verify .framework bundles are also inspected with the same metadata extraction
- [ ] Verify Mach-O code signature information is extracted and linked to the bundle analysis
- [ ] Verify bundles without entitlements are handled gracefully with appropriate defaults

View File

@@ -0,0 +1,22 @@
# macOS Homebrew Package Analyzer
## Module
Scanner
## Status
IMPLEMENTED
## Description
OS-level analyzer that discovers Homebrew-installed packages by parsing Cellar receipts, producing SBOM components with version, tap source, and installed-on-request metadata.
## Implementation Details
- **Homebrew Analyzer**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Homebrew/HomebrewPackageAnalyzer.cs` - `HomebrewPackageAnalyzer` discovers Homebrew-installed packages by parsing Cellar receipts, producing SBOM components with version, tap source, and installed-on-request metadata
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Homebrew/HomebrewAnalyzerPlugin.cs` - Plugin registration for the Homebrew analyzer
## E2E Test Plan
- [ ] Scan a macOS container image with Homebrew-installed packages and verify packages are discovered from Cellar receipts
- [ ] Verify each discovered package includes version, tap source (e.g., homebrew/core), and installed-on-request status
- [ ] Verify SBOM components are produced with correct PURL format for Homebrew packages
- [ ] Verify packages installed as dependencies (not on-request) are correctly distinguished from explicitly installed packages
- [ ] Verify custom tap packages are correctly attributed to their source tap

View File

@@ -0,0 +1,25 @@
# macOS pkgutil Receipt Analyzer
## Module
Scanner
## Status
IMPLEMENTED
## Description
Parses macOS pkgutil receipt database and BOM files to discover Apple installer packages, producing SBOM components with package identifier, version, and installed volume.
## Implementation Details
- **Package Analyzer**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Pkgutil/PkgutilPackageAnalyzer.cs` - `PkgutilPackageAnalyzer` discovers Apple installer packages from pkgutil receipt database
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Pkgutil/PkgutilAnalyzerPlugin.cs` - Plugin registration for the pkgutil analyzer
- **Parsers**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Pkgutil/PkgutilReceiptParser.cs` - `PkgutilReceiptParser` parses pkgutil receipt plist files extracting package identifier, version, and install metadata
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Pkgutil/BomParser.cs` - `BomParser` parses macOS BOM (Bill of Materials) files listing installed file manifests
## E2E Test Plan
- [ ] Scan a macOS container image and verify Apple installer packages are discovered from pkgutil receipts
- [ ] Verify each discovered package includes package identifier (e.g., `com.apple.pkg.CLTools_Executables`), version, and installed volume
- [ ] Verify BOM file parsing correctly identifies the files installed by each package
- [ ] Verify SBOM components are produced with correct PURL format for macOS system packages
- [ ] Verify packages from third-party PKG installers are also discovered alongside Apple system packages

View File

@@ -0,0 +1,28 @@
# Material Changes Orchestrator (Unified Cross-Module Diff Report)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Unified orchestration service that chains Scanner SmartDiff, BinaryIndex fingerprint diffs, and Unknowns tracking into a single "material changes" report with compact card-style output (what changed, why it matters, next action). Enables one-stop review of all changes across layers.
## Implementation Details
- **Orchestrator**:
- `src/Scanner/__Libraries/StellaOps.Scanner.MaterialChanges/IMaterialChangesOrchestrator.cs` - `IMaterialChangesOrchestrator` interface defining the material changes workflow
- `src/Scanner/__Libraries/StellaOps.Scanner.MaterialChanges/MaterialChangesOrchestrator.cs` - `MaterialChangesOrchestrator` chains SmartDiff, BinaryIndex fingerprint diffs, and Unknowns tracking into a unified report
- **Report Model**:
- `src/Scanner/__Libraries/StellaOps.Scanner.MaterialChanges/MaterialChangesReport.cs` - `MaterialChangesReport` model with compact card-style output (what changed, why it matters, next action)
- **Card Generation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.MaterialChanges/CardGenerators.cs` - `CardGenerators` produces compact card-style summaries for each type of material change
- **DI Registration**: `src/Scanner/__Libraries/StellaOps.Scanner.MaterialChanges/MaterialChangesServiceExtensions.cs`
## E2E Test Plan
- [ ] Trigger a rescan of a container image with known changes and verify the material changes orchestrator produces a unified report
- [ ] Verify the report includes SmartDiff results (component additions, removals, version changes)
- [ ] Verify the report includes BinaryIndex fingerprint diff results when binary changes are detected
- [ ] Verify the report includes Unknowns tracking deltas (newly unknown vs newly resolved)
- [ ] Verify card-style output includes "what changed", "why it matters", and "next action" for each change
- [ ] Verify the report correctly aggregates changes across all container layers

View File

@@ -0,0 +1,27 @@
# Mesh Entrypoint Graph (Multi-Container Reachability)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Cross-container entrypoint reachability analysis that parses Kubernetes and Docker Compose manifests to build a mesh graph of service-to-service connections, enabling vulnerability impact analysis across multi-container deployments.
## Implementation Details
- **Mesh Entrypoint Analysis**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Mesh/MeshEntrypointAnalyzer.cs` - `MeshEntrypointAnalyzer` performs cross-container entrypoint reachability analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Mesh/MeshEntrypointGraph.cs` - `MeshEntrypointGraph` represents the service-to-service connection graph across containers
- **Manifest Parsers**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Mesh/IManifestParser.cs` - `IManifestParser` interface for container orchestration manifest parsing
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Mesh/KubernetesManifestParser.cs` - `KubernetesManifestParser` parses Kubernetes Deployment, Service, and Ingress manifests to extract service topology
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Mesh/DockerComposeParser.cs` - `DockerComposeParser` parses Docker Compose files to extract service connections, port mappings, and network topology
## E2E Test Plan
- [ ] Provide a Kubernetes deployment with multiple services and verify the mesh graph correctly maps service-to-service connections
- [ ] Provide a Docker Compose file with linked services and verify cross-container connections are identified
- [ ] Verify a vulnerability in an internet-facing service is classified with higher exposure than one in an internal-only service
- [ ] Verify the mesh graph identifies transitive reachability (service A -> service B -> vulnerable service C)
- [ ] Verify port mappings and network policies are factored into the mesh connectivity analysis
- [ ] Verify the mesh graph handles service discovery (DNS-based and environment variable-based) for connection resolution

View File

@@ -0,0 +1,28 @@
# Model Version Change Detection
## Module
Scanner
## Status
IMPLEMENTED
## Description
Change detection for EPSS model version updates that suppresses noisy deltas when the underlying model changes, preventing false signal cascades.
## Implementation Details
- **EPSS Model Version Tracking**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Epss/EpssCsvStreamParser.cs` - `EpssCsvStreamParser` detects model version tags (e.g., `v2024.01.15`) from EPSS CSV data feeds and tracks version changes
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Epss/EpssExplainHashCalculator.cs` - `EpssExplainHashCalculator` includes `ModelVersion` in explain hash calculations to distinguish model-driven vs real-world score changes
- **Change Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Epss/EpssChangeDetector.cs` - `EpssChangeDetector` detects score changes between EPSS updates
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Epss/EpssChangeRecord.cs` - `EpssChangeRecord` model for recording detected changes with model version context
- **Events**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Epss/Events/EpssUpdatedEvent.cs` - `EpssUpdatedEvent` includes `ModelVersionTag` to flag model-version-driven updates
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Epss/EpssReplayService.cs` - `EpssReplayService` replays EPSS data with model version awareness for noise suppression
## E2E Test Plan
- [ ] Ingest two EPSS CSV feeds with the same model version and verify genuine score changes are detected
- [ ] Ingest an EPSS CSV feed with a new model version tag and verify the model version change is detected
- [ ] Verify that when a model version changes, score deltas are flagged as model-driven rather than generating false signal cascades
- [ ] Verify the explain hash includes model version so that model-change deltas are distinguishable from real-world changes
- [ ] Verify the replay service correctly handles model version transitions without generating spurious change events

View File

@@ -0,0 +1,53 @@
# Multi-Ecosystem Vulnerability Surface Builder
## Module
Scanner
## Status
IMPLEMENTED
## Description
Per-ecosystem method-level vulnerability surface computation with fingerprinters for NuGet (Cecil), npm (Babel), Maven (ASM), and PyPI (Python AST). Includes VulnSurfaceBuilder, MethodDiffEngine, and PostgresVulnSurfaceRepository. 24/24 tasks DONE.
## Implementation Details
- **VulnSurface Builder**:
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Builder/IVulnSurfaceBuilder.cs` - `IVulnSurfaceBuilder` interface for building vulnerability surfaces
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Builder/VulnSurfaceBuilder.cs` - `VulnSurfaceBuilder` computes per-ecosystem method-level vulnerability surfaces
- **Per-Ecosystem Fingerprinters** (each implements `IMethodFingerprinter`):
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Fingerprint/CecilMethodFingerprinter.cs` - NuGet/.NET method fingerprinting using Cecil IL analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Fingerprint/JavaScriptMethodFingerprinter.cs` - npm/JavaScript method fingerprinting using Babel AST
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Fingerprint/JavaBytecodeFingerprinter.cs` - Maven/Java method fingerprinting using ASM bytecode analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Fingerprint/PythonAstFingerprinter.cs` - PyPI/Python method fingerprinting using Python AST
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Fingerprint/IMethodFingerprinter.cs` - Common fingerprinter interface
- **Method Diff Engine**:
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Fingerprint/MethodDiffEngine.cs` - `MethodDiffEngine` compares method fingerprints across versions to detect vulnerable method changes
- **Method Key Builders** (per-ecosystem):
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/MethodKeys/DotNetMethodKeyBuilder.cs` - .NET method key generation
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/MethodKeys/JavaMethodKeyBuilder.cs` - Java method key generation
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/MethodKeys/NodeMethodKeyBuilder.cs` - Node.js method key generation
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/MethodKeys/PythonMethodKeyBuilder.cs` - Python method key generation
- **Package Downloaders** (per-ecosystem):
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Download/NuGetPackageDownloader.cs` - NuGet package download
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Download/NpmPackageDownloader.cs` - npm package download
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Download/MavenPackageDownloader.cs` - Maven package download
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Download/PyPIPackageDownloader.cs` - PyPI package download
- **Internal Call Graph Builders**:
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/CallGraph/CecilInternalGraphBuilder.cs` - .NET internal call graph via Cecil
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/CallGraph/JavaInternalGraphBuilder.cs` - Java internal call graph
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/CallGraph/JavaScriptInternalGraphBuilder.cs` - JavaScript internal call graph
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/CallGraph/PythonInternalGraphBuilder.cs` - Python internal call graph
- **Storage**:
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Storage/IVulnSurfaceRepository.cs` - Repository interface
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Storage/PostgresVulnSurfaceRepository.cs` - PostgreSQL-backed vulnerability surface repository
- **Trigger Method Extraction**:
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Triggers/ITriggerMethodExtractor.cs` - Interface for extracting vulnerable trigger methods
- `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Triggers/TriggerMethodExtractor.cs` - Extracts trigger methods from vulnerability advisories
## E2E Test Plan
- [ ] Scan a .NET project and verify NuGet vulnerability surfaces are computed using Cecil method fingerprinting
- [ ] Scan a Node.js project and verify npm vulnerability surfaces are computed using JavaScript AST fingerprinting
- [ ] Scan a Java project and verify Maven vulnerability surfaces are computed using bytecode fingerprinting
- [ ] Scan a Python project and verify PyPI vulnerability surfaces are computed using Python AST fingerprinting
- [ ] Verify the MethodDiffEngine detects method-level changes between vulnerable and patched package versions
- [ ] Verify vulnerability surfaces are persisted in PostgreSQL and retrievable for subsequent scans
- [ ] Verify trigger method extraction correctly identifies the specific vulnerable functions from advisories

View File

@@ -0,0 +1,48 @@
# Multi-Language Call Graph Extractors and Analyzers (.NET, Go, Java, JS, Python, Ruby, PHP, Bun, Deno)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Call graph extractors for .NET, Go, Java, JavaScript, Python, Ruby, PHP, Bun, and Deno. .NET has dedicated language analyzer with entrypoint resolver and capability scanner. Includes capability scanning, sink matching, and binary call graph extraction.
## Implementation Details
- **Extractor Framework**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/ICallGraphExtractor.cs` - `ICallGraphExtractor` interface for language-specific call graph extraction
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/ICallGraphExtractorRegistry.cs` - `ICallGraphExtractorRegistry` for registering and resolving extractors by language
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/CallGraphExtractorRegistry.cs` - Registry implementation
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/GuardDetector.cs` - Detects security guards (auth, admin, feature flags) in call paths
- **Per-Language Extractors** (each with extractor, entrypoint classifier, and sink matcher):
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/DotNet/DotNetCallGraphExtractor.cs` - .NET call graph via Cecil IL analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Go/GoCallGraphExtractor.cs` - Go call graph via SSA analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Java/JavaCallGraphExtractor.cs` - Java call graph via bytecode analysis
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/JavaScript/JavaScriptCallGraphExtractor.cs` - JavaScript call graph
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Node/NodeCallGraphExtractor.cs` - Node.js call graph with Babel parsing
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Python/PythonCallGraphExtractor.cs` - Python call graph via AST
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Ruby/RubyCallGraphExtractor.cs` - Ruby call graph
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Php/PhpCallGraphExtractor.cs` - PHP call graph
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Bun/BunCallGraphExtractor.cs` - Bun call graph
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Deno/DenoCallGraphExtractor.cs` - Deno call graph
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/BinaryCallGraphExtractor.cs` - Binary (ELF/PE) call graph via disassembly
- **Sink Matchers** (per-language):
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Go/GoSinkMatcher.cs`, `Java/JavaSinkMatcher.cs`, `JavaScript/JsSinkMatcher.cs`, `Python/PythonSinkMatcher.cs`, `Ruby/RubySinkMatcher.cs`, `Php/PhpSinkMatcher.cs`, `Bun/BunSinkMatcher.cs`, `Deno/DenoSinkMatcher.cs`
- **Entrypoint Classifiers** (per-language):
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Go/GoEntrypointClassifier.cs`, `Java/JavaEntrypointClassifier.cs`, `JavaScript/JsEntrypointClassifier.cs`, `Python/PythonEntrypointClassifier.cs`, `Ruby/RubyEntrypointClassifier.cs`, `Php/PhpEntrypointClassifier.cs`, `Bun/BunEntrypointClassifier.cs`, `Deno/DenoEntrypointClassifier.cs`, `Binary/BinaryEntrypointClassifier.cs`
- **Reachability Analysis**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Analysis/ReachabilityAnalyzer.cs` - `ReachabilityAnalyzer` determines reachability from entrypoints to vulnerable sinks
- **Caching**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Caching/ICallGraphCacheService.cs` - Cache interface for call graph results
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Caching/ValkeyCallGraphCacheService.cs` - Valkey-backed cache for call graph data
## E2E Test Plan
- [ ] Scan a multi-language container image and verify call graphs are extracted for each detected language runtime
- [ ] Verify .NET call graph extraction identifies entrypoints (controllers, Main) and traces calls to vulnerable methods
- [ ] Verify Go call graph extraction uses SSA analysis to resolve interface dispatch targets
- [ ] Verify Java call graph extraction analyzes bytecode to extract method call relationships
- [ ] Verify sink matchers correctly identify known dangerous functions (e.g., `Runtime.exec`, `eval`, `os.system`) in each language
- [ ] Verify entrypoint classifiers correctly identify web handlers, CLI entry points, and background workers
- [ ] Verify the reachability analyzer produces reachability verdicts by tracing paths from entrypoints through call graphs to vulnerable sinks
- [ ] Verify call graph caching avoids re-extraction on rescan of unchanged layers

View File

@@ -0,0 +1,24 @@
# OCI Ancestry Extraction
## Module
Scanner
## Status
IMPLEMENTED
## Description
Extract base image references from OCI manifest config.history to populate lineage parent relationships.
## Implementation Details
- **Ancestry Extractor**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/IOciAncestryExtractor.cs` - `IOciAncestryExtractor` interface defining the ancestry extraction contract
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/OciAncestryExtractor.cs` - `OciAncestryExtractor` extracts base image references from OCI manifest config.history to populate lineage parent relationships
- **Layer Dependency Graph**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Models/LayerDependencyGraph.cs` - `LayerDependencyGraph` models parent-child layer relationships from ancestry data
## E2E Test Plan
- [ ] Scan a container image built from a known base image and verify the OCI ancestry extractor identifies the base image reference from config.history
- [ ] Verify lineage parent relationships are populated correctly linking child image to base image
- [ ] Verify multi-stage build ancestry is correctly resolved (identifying intermediate build stages)
- [ ] Verify images with `LABEL` or `org.opencontainers.image.base.name` annotations use those for ancestry when available
- [ ] Verify images without config.history (scratch-based) are handled gracefully with no parent relationship

View File

@@ -0,0 +1,26 @@
# OCI Artifact Storage for Reachability Slices
## Module
Scanner
## Status
IMPLEMENTED
## Description
OCI artifact storage with custom media types (application/vnd.stellaops.slice.v1+json) for reachability slices, supporting push/pull with DSSE signature verification, referrer-based linking, and caching.
## Implementation Details
- **OCI Slice Storage**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/SlicePushService.cs` - `SlicePushService` pushes reachability slices as OCI artifacts with custom media types
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/SlicePullService.cs` - `SlicePullService` pulls reachability slices from OCI registries with DSSE signature verification
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/SliceOciManifestBuilder.cs` - `SliceOciManifestBuilder` constructs OCI manifests for reachability slice artifacts
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/OciMediaTypes.cs` - Defines custom media types (`application/vnd.stellaops.slice.v1+json`)
- **Slice Schema**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceSchema.cs` - `SliceSchema` defines the schema for reachability slice data
## E2E Test Plan
- [ ] Push a reachability slice to an OCI registry and verify the artifact is stored with the correct custom media type
- [ ] Pull a previously pushed reachability slice and verify integrity and DSSE signature verification passes
- [ ] Verify referrer-based linking connects the slice artifact to its parent image manifest
- [ ] Verify pulling a tampered slice fails DSSE signature verification
- [ ] Verify caching avoids redundant pushes for unchanged slices

View File

@@ -0,0 +1,26 @@
# OCI Image Inspector Service (IOciImageInspector)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Service for inspecting OCI images including multi-arch manifest resolution, layer enumeration, platform detection, and digest extraction without pulling full image content.
## Implementation Details
- **Image Inspector**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/IOciImageInspector.cs` - `IOciImageInspector` interface for inspecting OCI images without pulling full content
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/OciImageInspector.cs` - `OciImageInspector` implementation supporting multi-arch manifest resolution, layer enumeration, platform detection, and digest extraction
- **Inspection Models**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Contracts/OciInspectionModels.cs` - `OciInspectionModels` defining inspection result types (layers, platforms, digests)
- **DI Registration**: `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/ServiceCollectionExtensions.cs`
## E2E Test Plan
- [ ] Inspect a single-arch OCI image and verify layer enumeration returns correct layer digests and sizes
- [ ] Inspect a multi-arch OCI image and verify platform detection identifies all available architectures (amd64, arm64, etc.)
- [ ] Verify multi-arch manifest resolution selects the correct platform-specific manifest based on the runtime platform
- [ ] Verify digest extraction returns the correct content-addressable digest for the image manifest
- [ ] Verify inspection works without pulling full image content (manifest-only operation)
- [ ] Verify inspection handles private registries with authentication

View File

@@ -0,0 +1,34 @@
# OCI Layer Manifest Infrastructure for Delta Scanning
## Module
Scanner
## Status
IMPLEMENTED
## Description
Infrastructure for OCI manifest snapshotting with layer digest resolution and diffID-based layer tracking. Provides layer reuse detection across image versions and a registry client abstraction to support delta scanning workflows. Distinct from generic "OCI Ancestry Extraction" in known features.
## Implementation Details
- **Manifest Snapshot Service**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/IOciManifestSnapshotService.cs` - `IOciManifestSnapshotService` interface for manifest snapshot operations
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/OciManifestSnapshotService.cs` - `OciManifestSnapshotService` captures and compares OCI manifest snapshots for delta scanning
- **Manifest Models**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Models/OciManifestSnapshot.cs` - `OciManifestSnapshot` representing a point-in-time manifest state with layer digests
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Models/ManifestComparisonResult.cs` - `ManifestComparisonResult` identifies added, removed, and unchanged layers between snapshots
- **Layer Digest Resolution**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Resolution/ILayerDigestResolver.cs` - Interface for resolving layer digests to diffIDs
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Resolution/LayerDigestResolver.cs` - `LayerDigestResolver` resolves compressed layer digests to uncompressed diffIDs for consistent tracking
- **Layer Reuse Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Reuse/LayerReuseDetector.cs` - `LayerReuseDetector` identifies unchanged layers across image versions to skip re-analysis
- **Persistence**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Persistence/IManifestSnapshotRepository.cs` - Repository interface for snapshot storage
- `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/Persistence/ManifestSnapshotRepository.cs` - PostgreSQL-backed snapshot persistence
- **DI Registration**: `src/Scanner/__Libraries/StellaOps.Scanner.Manifest/ManifestServiceCollectionExtensions.cs`
## E2E Test Plan
- [ ] Scan an image and verify a manifest snapshot is captured with all layer digests and diffIDs
- [ ] Rescan a newer version of the same image and verify manifest comparison correctly identifies added, removed, and unchanged layers
- [ ] Verify layer reuse detection skips unchanged layers in subsequent scans, reducing scan time
- [ ] Verify diffID-based tracking correctly matches layers across manifest versions despite compressed digest differences
- [ ] Verify manifest snapshots are persisted and retrievable for historical comparison

View File

@@ -0,0 +1,37 @@
# Offline Kit Import and Attestation Verification
## Module
Scanner
## Status
IMPLEMENTED
## Description
Offline kit import service and offline attestation verifier with test coverage in Scanner module, enabling verification of DSSE-signed attestations without network access.
## Implementation Details
- **Offline Kit Import**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/OfflineKitImportService.cs` - `OfflineKitImportService` imports offline vulnerability data kits
- `src/Scanner/StellaOps.Scanner.WebService/Services/OfflineKitManifestService.cs` - `OfflineKitManifestService` manages offline kit manifests
- `src/Scanner/StellaOps.Scanner.WebService/Services/OfflineKitContracts.cs` - Contract models for offline kit operations
- `src/Scanner/StellaOps.Scanner.WebService/Services/OfflineKitStateStore.cs` - State tracking for imported kits
- `src/Scanner/StellaOps.Scanner.WebService/Services/OfflineKitMetricsStore.cs` - Metrics tracking for import operations
- **Attestation Verification**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/IOfflineAttestationVerifier.cs` - `IOfflineAttestationVerifier` interface for verifying DSSE-signed attestations offline
- `src/Scanner/StellaOps.Scanner.WebService/Services/OfflineAttestationVerifier.cs` - `OfflineAttestationVerifier` verifies DSSE signatures without network access using local trust anchors
- `src/Scanner/StellaOps.Scanner.WebService/Services/NullOfflineKitAuditEmitter.cs` - Null audit emitter for environments without audit logging
- **API Endpoints**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/OfflineKitEndpoints.cs` - REST endpoints for importing and managing offline kits
- **Configuration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Configuration/OfflineKitOptions.cs` - `OfflineKitOptions` configuration model
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Configuration/OfflineKitOptionsValidator.cs` - Options validation
- **Trust Anchors**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/TrustAnchors/TrustAnchorRegistry.cs` - `TrustAnchorRegistry` manages local trust anchors for offline verification
## E2E Test Plan
- [ ] Import an offline vulnerability kit via the `OfflineKitEndpoints` and verify it is accepted and stored
- [ ] Verify DSSE-signed attestations within the kit are verified using local trust anchors without network access
- [ ] Verify import of a tampered kit fails attestation verification
- [ ] Verify kit manifest service correctly lists available kits and their status
- [ ] Verify offline kit state tracking records import timestamps and kit versions
- [ ] Verify the scanner operates correctly with offline kit data as its vulnerability source

View File

@@ -0,0 +1,27 @@
# Offline Slice Bundle Export/Import (OCI Layout)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Offline distribution of reachability slices via OCI layout tar.gz bundles including all referenced artifacts (graphs, SBOMs), with integrity verification on import. Targets <100MB for typical scans.
## Implementation Details
- **Offline Bundle Service**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/Offline/OfflineBundleService.cs` - `OfflineBundleService` exports and imports reachability slices as OCI layout tar.gz bundles with all referenced artifacts
- **Evidence Bundle Export**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/IEvidenceBundleExporter.cs` - `IEvidenceBundleExporter` interface for exporting evidence bundles
- `src/Scanner/StellaOps.Scanner.WebService/Services/EvidenceBundleExporter.cs` - `EvidenceBundleExporter` exports scan evidence as portable bundles
- **OCI Slice Services**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/SlicePushService.cs` - Push slices to OCI registries
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/SlicePullService.cs` - Pull slices from OCI registries
## E2E Test Plan
- [ ] Export a reachability slice bundle as an OCI layout tar.gz file and verify it contains all referenced artifacts (graphs, SBOMs)
- [ ] Import the exported bundle into a disconnected instance and verify integrity verification passes
- [ ] Verify the exported bundle size stays under 100MB for typical scans
- [ ] Verify tampered bundles fail integrity verification on import
- [ ] Verify the imported bundle's reachability data is usable for offline vulnerability analysis

View File

@@ -0,0 +1,23 @@
# OS Rootfs Fingerprint and Surface Cache
## Module
Scanner
## Status
IMPLEMENTED
## Description
Root filesystem fingerprinting to uniquely identify OS layers, paired with a surface cache that avoids re-analyzing unchanged OS layers across scans.
## Implementation Details
- **Rootfs Fingerprinting**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS/Internal/OsRootfsFingerprint.cs` - `OsRootfsFingerprint` generates unique fingerprints for OS root filesystem layers based on package database state
- **Surface Cache**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS/Internal/OsAnalyzerSurfaceCache.cs` - `OsAnalyzerSurfaceCache` caches OS analysis results keyed by rootfs fingerprint, avoiding re-analysis of unchanged OS layers
## E2E Test Plan
- [ ] Scan a container image and verify an OS rootfs fingerprint is generated based on the package database state
- [ ] Rescan the same image and verify the surface cache returns cached results without re-analyzing the OS layer
- [ ] Scan a different image sharing the same base OS layer and verify the cache hit reuses previously computed results
- [ ] Scan an image with a modified OS layer and verify the cache miss triggers fresh OS analysis
- [ ] Verify fingerprint stability (same layer produces identical fingerprints across scans)

View File

@@ -0,0 +1,26 @@
# Outbox Pattern for Event Dispatch
## Module
Scanner
## Status
IMPLEMENTED
## Description
Outbox pattern for reliable event dispatch with idempotent processing, dispatch tracking, and retry logic.
## Implementation Details
- **Event Dispatcher**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/IReportEventDispatcher.cs` - `IReportEventDispatcher` interface for reliable event dispatch with idempotent processing
- `src/Scanner/StellaOps.Scanner.WebService/Services/ReportEventDispatcher.cs` - `ReportEventDispatcher` implements the outbox pattern for reliable event dispatch with dispatch tracking and retry logic
- **OCI Attestation Publisher**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/IOciAttestationPublisher.cs` - `IOciAttestationPublisher` interface for publishing attestation events to OCI registries
- **Report Endpoints**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/ReportEndpoints.cs` - `ReportEndpoints` triggers event dispatch for completed scan reports
## E2E Test Plan
- [ ] Complete a scan and verify the report event dispatcher reliably publishes scan completion events
- [ ] Simulate a transient failure during event dispatch and verify the retry logic reprocesses the event
- [ ] Verify idempotent processing ensures duplicate events are not dispatched for the same scan
- [ ] Verify dispatch tracking records the status of each dispatched event (pending, dispatched, failed)
- [ ] Verify the outbox pattern guarantees at-least-once delivery for scan report events

View File

@@ -0,0 +1,24 @@
# Package Name Normalization Service
## Module
Scanner
## Status
IMPLEMENTED
## Description
Cross-ecosystem package name normalization service handling aliases between package managers (apt/dpkg, pip eggs/wheels/PyPI, npm scoped/unscoped, Go module/package paths). Uses a JSON alias map with 326 lines of known aliases and provides file-hash fingerprint fallback for unresolvable packages.
## Implementation Details
- **Normalization Service**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Normalization/IPackageNameNormalizer.cs` - `IPackageNameNormalizer` interface for cross-ecosystem package name normalization
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Normalization/PackageNameNormalizer.cs` - `PackageNameNormalizer` handles aliases between package managers (apt/dpkg, pip eggs/wheels/PyPI, npm scoped/unscoped, Go module/package paths), using a JSON alias map and file-hash fingerprint fallback
- **DI Registration**: `src/Scanner/__Libraries/StellaOps.Scanner.Core/Normalization/NormalizationServiceCollectionExtensions.cs`
## E2E Test Plan
- [ ] Normalize an apt package name and verify it maps to the correct dpkg equivalent
- [ ] Normalize a pip egg/wheel package name and verify it maps to the canonical PyPI name
- [ ] Normalize an npm scoped package and verify correct normalization (e.g., `@scope/package`)
- [ ] Normalize a Go module path and verify package path aliasing works correctly
- [ ] Verify the JSON alias map resolves known cross-ecosystem aliases (e.g., `libssl-dev` to `openssl`)
- [ ] Verify the file-hash fingerprint fallback produces a consistent identifier for unresolvable packages

View File

@@ -0,0 +1,25 @@
# Path Explanation Service with Multi-Format Rendering
## Module
Scanner
## Status
IMPLEMENTED
## Description
Service that converts raw reachability graph paths (entrypoint-to-sink) into human-readable explanations with gate annotations, supporting text, markdown, and JSON output formats for display in CLI, UI, and API responses.
## Implementation Details
- **Path Explanation Service**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Explanation/PathExplanationService.cs` - `PathExplanationService` converts raw reachability graph paths into human-readable explanations with gate annotations
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Explanation/PathExplanationModels.cs` - Models for path explanation data including node descriptions, gate annotations, and confidence levels
- **Multi-Format Rendering**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Explanation/PathRenderer.cs` - `PathRenderer` renders path explanations in multiple formats: plain text, markdown, and JSON for CLI, UI, and API consumption
## E2E Test Plan
- [ ] Generate a reachability path from an entrypoint to a vulnerable sink and verify the explanation service produces a human-readable description
- [ ] Verify gate annotations (auth, admin-only, feature flags) appear in the path explanation
- [ ] Verify text format rendering produces a clean CLI-readable output
- [ ] Verify markdown format rendering produces properly formatted markdown with code blocks and links
- [ ] Verify JSON format rendering produces structured data suitable for API responses and UI consumption
- [ ] Verify multi-hop paths (entrypoint -> intermediate -> sink) include all intermediate nodes with descriptions

View File

@@ -0,0 +1,30 @@
# Per-Layer SBOM Content-Addressable Storage
## Module
Scanner
## Status
IMPLEMENTED
## Description
Content-addressable storage for per-layer SBOMs keyed by diffID with PostgreSQL metadata and gzip-compressed content storage. Supports TTL-based eviction for cold layers and provides cache hit/miss metrics. While "Layer-SBOM Cache with Hash-Based Reuse" exists in known features, this specific CAS implementation with PostgreSQL persistence and TTL eviction is a distinct shipped capability.
## Implementation Details
- **Content-Addressable Storage**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/LayerSbomCas/ILayerSbomCas.cs` - `ILayerSbomCas` interface for content-addressable SBOM storage keyed by diffID
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/LayerSbomCas/PostgresLayerSbomCas.cs` - `PostgresLayerSbomCas` PostgreSQL-backed CAS with gzip-compressed content storage and TTL-based eviction
- **Cache Infrastructure**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/Abstractions/ILayerCacheStore.cs` - Layer cache store interface
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/Abstractions/LayerCacheEntry.cs` - Cache entry with metadata (diffID, TTL, creation time)
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/LayerCache/LayerCacheStore.cs` - Cache store implementation
- **Maintenance**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Cache/Maintenance/ScannerCacheMaintenanceService.cs` - TTL-based eviction for cold/stale layer SBOMs
- **DI Registration**: `src/Scanner/__Libraries/StellaOps.Scanner.Cache/ScannerCacheServiceCollectionExtensions.cs`
## E2E Test Plan
- [ ] Store a per-layer SBOM via CAS keyed by diffID and verify it is retrievable by the same key
- [ ] Verify stored content is gzip-compressed and decompresses correctly on retrieval
- [ ] Verify TTL-based eviction removes cold layer SBOMs after the configured TTL expires
- [ ] Verify cache hit/miss metrics are tracked and exposed for monitoring
- [ ] Verify duplicate puts for the same diffID are idempotent (content-addressable deduplication)
- [ ] Verify PostgreSQL metadata correctly tracks creation time, last access time, and TTL for each entry

View File

@@ -0,0 +1,31 @@
# Per-Layer SBOM Export API
## Module
Scanner
## Status
IMPLEMENTED
## Description
Per-layer SBOMs stored as individual CAS artifacts with API endpoints to retrieve layer-specific SBOMs (GET /scans/{id}/layers, GET /scans/{id}/layers/{digest}/sbom with format param), content negotiation, immutable caching (ETag, Cache-Control), and CLI commands (stella scan layer-sbom, stella scan recipe).
## Implementation Details
- **API Endpoints**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/LayerSbomEndpoints.cs` - `LayerSbomEndpoints` with `GET /scans/{id}/layers` (list layers) and `GET /scans/{id}/layers/{digest}/sbom` (retrieve per-layer SBOM with format negotiation)
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/ScanEndpoints.cs` - Scan endpoints integrating per-layer SBOM access
- **Layer SBOM Service**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/ILayerSbomService.cs` - `ILayerSbomService` interface for layer SBOM operations
- `src/Scanner/StellaOps.Scanner.WebService/Services/LayerSbomService.cs` - `LayerSbomService` manages per-layer SBOM retrieval with content negotiation (SPDX, CycloneDX) and immutable caching
- `src/Scanner/StellaOps.Scanner.WebService/Services/SurfacePointerService.cs` - `SurfacePointerService` tracks surface-level pointers for layer SBOMs
- **Layer SBOM Composition**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/LayerSbomComposer.cs` - Composes per-layer SBOMs
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/SpdxLayerWriter.cs` - SPDX format layer SBOM writer
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/CycloneDxLayerWriter.cs` - CycloneDX format layer SBOM writer
## E2E Test Plan
- [ ] Call `GET /scans/{id}/layers` and verify a list of container layers with digests and sizes is returned
- [ ] Call `GET /scans/{id}/layers/{digest}/sbom?format=spdx` and verify a valid SPDX SBOM is returned for the specific layer
- [ ] Call `GET /scans/{id}/layers/{digest}/sbom?format=cyclonedx` and verify a valid CycloneDX SBOM is returned
- [ ] Verify ETag and Cache-Control headers are set for immutable caching of per-layer SBOMs
- [ ] Verify content negotiation via Accept header works as an alternative to the format query parameter
- [ ] Verify requesting a non-existent layer digest returns 404

View File

@@ -0,0 +1,32 @@
# PLT/IAT Resolution and Dynamic Loading Detection for Binary Analysis
## Module
Scanner
## Status
IMPLEMENTED
## Description
Enhanced binary call graph extraction using x86 and ARM64 disassembly to resolve PLT stubs to GOT entries and IAT thunks to actual import targets, plus heuristic detection of dynamic loading patterns (dlopen/LoadLibrary) for more complete binary reachability analysis.
## Implementation Details
- **Disassembly Engines**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Disassembly/X86Disassembler.cs` - `X86Disassembler` disassembles x86/x64 code to resolve PLT stubs to GOT entries and extract call targets
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Disassembly/Arm64Disassembler.cs` - `Arm64Disassembler` disassembles ARM64 code for PLT/IAT resolution
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Disassembly/DirectCallExtractor.cs` - `DirectCallExtractor` extracts direct call targets from disassembled instruction streams
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Disassembly/BinaryTextSectionReader.cs` - Reads .text sections for disassembly
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Disassembly/BinaryDisassemblyModels.cs` - Models for disassembly results
- **Dynamic Loading Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Analysis/BinaryDynamicLoadDetector.cs` - `BinaryDynamicLoadDetector` detects dlopen/LoadLibrary/dlsym patterns for dynamic library loading
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/Analysis/BinaryStringLiteralScanner.cs` - `BinaryStringLiteralScanner` scans string literals to identify dynamically loaded library names
- **Binary Call Graph Integration**:
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/BinaryCallGraphExtractor.cs` - `BinaryCallGraphExtractor` integrates disassembly and dynamic load detection into call graph extraction
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/FunctionBoundaryDetector.cs` - Detects function boundaries for accurate call graph construction
## E2E Test Plan
- [ ] Scan a container with ELF binaries containing PLT stubs and verify PLT-to-GOT resolution identifies the actual imported functions
- [ ] Scan a container with PE binaries and verify IAT thunk resolution maps to actual import targets
- [ ] Verify x86/x64 disassembly correctly extracts direct call instructions and their targets
- [ ] Verify ARM64 disassembly correctly handles ADRP+ADD patterns for PLT resolution
- [ ] Verify dynamic loading detection identifies `dlopen`/`LoadLibrary` calls and extracts library name strings
- [ ] Verify the binary call graph includes both statically linked and dynamically loaded library references

View File

@@ -0,0 +1,24 @@
# Policy Version Binding to Reachability Slices (strict/forward/any)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Binds reachability slices to specific policy versions with three validation modes: strict (invalidate on any policy change), forward (valid with newer versions), and any (valid with any version). Production defaults to strict mode.
## Implementation Details
- **Policy Binding**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/PolicyBinding.cs` - `PolicyBinding` binds reachability slices to specific policy versions with three validation modes: strict (invalidate on any policy change), forward (valid with newer versions), and any (valid with any version)
- **Slice Schema**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceSchema.cs` - `SliceSchema` includes policy version binding metadata in slice definitions
## E2E Test Plan
- [ ] Create a reachability slice with strict policy binding and verify it is invalidated when the policy version changes
- [ ] Create a reachability slice with forward binding and verify it remains valid when the policy version is incremented
- [ ] Create a reachability slice with forward binding and verify it is invalidated when the policy version is rolled back
- [ ] Create a reachability slice with "any" binding and verify it remains valid regardless of policy version changes
- [ ] Verify production defaults to strict mode when no binding mode is explicitly specified
- [ ] Verify invalidated slices trigger re-computation of reachability analysis

View File

@@ -0,0 +1,24 @@
# Predictive Entrypoint Risk Scoring
## Module
Scanner
## Status
IMPLEMENTED
## Description
Multi-dimensional predictive risk scoring that combines semantic, temporal, mesh, and binary intelligence signals into a composite risk score for entrypoints. Provides business-context-aware risk assessment with trend tracking and fleet-level aggregation.
## Implementation Details
- **Risk Scoring Framework**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Risk/IRiskScorer.cs` - `IRiskScorer` interface for computing entrypoint risk scores
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Risk/CompositeRiskScorer.cs` - `CompositeRiskScorer` combines semantic, temporal, mesh, and binary intelligence signals into a multi-dimensional composite risk score
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Risk/RiskScore.cs` - `RiskScore` model representing the composite score with individual signal contributions
## E2E Test Plan
- [ ] Analyze an internet-facing entrypoint with known vulnerable dependencies and verify it receives a high composite risk score
- [ ] Verify semantic signals (route semantics, input types) contribute to the risk score
- [ ] Verify temporal signals (recent vulnerability disclosures, EPSS trends) influence the score
- [ ] Verify mesh signals (cross-service exposure, network topology) factor into the assessment
- [ ] Verify the composite risk scorer correctly weights and aggregates individual signal scores
- [ ] Verify trend tracking shows score changes over time for the same entrypoint

View File

@@ -0,0 +1,28 @@
# Proc Snapshot Collectors (Java/DotNet/PHP Runtime Inventory)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Runtime process snapshot collection for Java classpath, .NET assemblies, and PHP autoload paths, providing runtime-observed library inventories that feed into SBOM reconciliation.
## Implementation Details
- **Process Snapshot**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Runtime/ProcFileSystemSnapshot.cs` - `ProcFileSystemSnapshot` collects runtime process state from /proc filesystem entries (Java classpath, .NET assemblies, PHP autoload paths)
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Runtime/ProcProcess.cs` - `ProcProcess` model representing a discovered runtime process with its loaded libraries
- **Process Graph**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Runtime/ProcGraph.cs` - `ProcGraph` represents the runtime process dependency graph
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Runtime/ProcGraphBuilder.cs` - `ProcGraphBuilder` constructs the process graph from snapshot data
- **Reconciliation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Runtime/EntryTraceRuntimeReconciler.cs` - `EntryTraceRuntimeReconciler` reconciles runtime-observed libraries with static SBOM analysis
## E2E Test Plan
- [ ] Collect a process snapshot from a running Java container and verify classpath entries are captured
- [ ] Collect a process snapshot from a running .NET container and verify loaded assembly paths are captured
- [ ] Collect a process snapshot from a running PHP container and verify autoload paths are captured
- [ ] Verify the runtime reconciler correctly matches runtime-observed libraries to static SBOM components
- [ ] Verify runtime-observed libraries not in the static SBOM are flagged as "runtime-only" discoveries
- [ ] Verify the process graph correctly models parent-child process relationships

View File

@@ -0,0 +1,24 @@
# Progressive Fidelity Scan Mode (Quick/Standard/Deep)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Allows users to select scan depth (Quick/Standard/Deep) with a FidelityAwareAnalyzer that adjusts analysis precision and an upgrade endpoint to promote results to higher fidelity. Distinct from "Tiered Scanner Precision" which describes imported/executed/tainted-sink PR-AUC tiers -- this is about user-selectable scan depth modes.
## Implementation Details
- **Fidelity-Aware Analyzer**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Orchestration/Fidelity/FidelityAwareAnalyzer.cs` - `FidelityAwareAnalyzer` adjusts analysis precision based on the selected scan depth mode (Quick/Standard/Deep)
- **Fidelity Endpoints**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/FidelityEndpoints.cs` - `FidelityEndpoints` provides API for selecting scan depth and upgrading scan results to higher fidelity
## E2E Test Plan
- [ ] Trigger a Quick scan and verify it completes faster with reduced analysis depth (SBOM only, no reachability)
- [ ] Trigger a Standard scan and verify it includes SBOM generation plus basic vulnerability matching
- [ ] Trigger a Deep scan and verify it includes full reachability analysis, call graph extraction, and binary intelligence
- [ ] Use the upgrade endpoint to promote Quick scan results to Standard and verify additional analysis is performed
- [ ] Use the upgrade endpoint to promote Standard to Deep and verify full reachability analysis is appended
- [ ] Verify the selected scan depth is recorded in scan metadata for auditability

View File

@@ -0,0 +1,29 @@
# Proof Bundle API for Exploit Paths
## Module
Scanner
## Status
IMPLEMENTED
## Description
REST API (GET /triage/paths/{pathId}/proof) returning complete proof bundles aggregating reachability subgraph (nodes + edges), symbol map with source locations, VEX claims with trust scores, and computed bundle digest for integrity. Export endpoint for JSON file download.
## Implementation Details
- **Proof Bundle Storage**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/PostgresProofBundleRepository.cs` - `PostgresProofBundleRepository` stores and retrieves proof bundles for exploit paths
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Entities/ProofBundleRow.cs` - `ProofBundleRow` database entity for proof bundle persistence
- **Proof Bundle Writer**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/ProofBundleWriter.cs` - `ProofBundleWriter` assembles proof bundles aggregating reachability subgraph, symbol map, VEX claims, and computes bundle digest
- **Scan Manifest**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Repositories/IScanManifestRepository.cs` - Repository for scan manifest data linked to proof bundles
- **OCI Publishing**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/VerdictOciPublisher.cs` - Publishes proof bundles to OCI registries as attestation artifacts
## E2E Test Plan
- [ ] Generate a proof bundle for an exploit path and retrieve it via the API, verifying it contains the reachability subgraph with nodes and edges
- [ ] Verify the proof bundle includes the symbol map with source file locations
- [ ] Verify the proof bundle includes VEX claims with trust scores for each finding
- [ ] Verify the computed bundle digest provides integrity verification
- [ ] Export the proof bundle as a JSON file and verify the download contains the complete bundle
- [ ] Verify proof bundles are publishable to OCI registries as attestation artifacts

View File

@@ -0,0 +1,28 @@
# Python egg-info and Editable Install Support
## Module
Scanner
## Status
IMPLEMENTED
## Description
Extends Python analyzer to discover packages installed via legacy egg-info metadata format and pip editable installs (pip install -e), which lack standard dist-info directories.
## Implementation Details
- **Egg-Info Adapter**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python/Internal/Packaging/Adapters/EggInfoAdapter.cs` - `EggInfoAdapter` discovers packages installed via legacy egg-info metadata format, extracting package name, version, and dependencies
- **Editable Install Adapter**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python/Internal/Packaging/Adapters/PipEditableAdapter.cs` - `PipEditableAdapter` discovers packages installed via `pip install -e` editable installs, which use .egg-link files instead of standard dist-info
- **Package Discovery**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python/Internal/Packaging/PythonPackageDiscovery.cs` - `PythonPackageDiscovery` orchestrates discovery across dist-info, egg-info, and editable install paths
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python/Internal/Packaging/PythonPackageInfo.cs` - `PythonPackageInfo` unified package metadata model
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python/Internal/Packaging/PythonPackageKind.cs` - Enum distinguishing dist-info, egg-info, and editable package types
- **Language Analyzer**: `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python/PythonLanguageAnalyzer.cs`
## E2E Test Plan
- [ ] Scan a container with Python packages installed via legacy `python setup.py install` (egg-info) and verify they are discovered
- [ ] Scan a container with pip editable installs (`pip install -e .`) and verify the editable packages are discovered
- [ ] Verify egg-info packages include correct name, version, and dependency metadata in the SBOM
- [ ] Verify editable installs using .egg-link files are correctly resolved to their source paths
- [ ] Verify the package kind (dist-info vs egg-info vs editable) is correctly classified for each discovered package

View File

@@ -0,0 +1,28 @@
# Quiet Scans Validation (Reachability + VEX + Dedup)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Reachability gates and VEX candidate emission are tested and integrated into the SmartDiff pipeline for quieter scan results.
## Implementation Details
- **Reachability Gate Bridge**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/ReachabilityGateBridge.cs` - `ReachabilityGateBridge` integrates reachability gate verdicts into the SmartDiff pipeline to suppress unreachable findings
- **VEX Candidate Emission**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/VexCandidateEmitter.cs` - `VexCandidateEmitter` generates VEX candidates for findings that can be auto-resolved
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/VexCandidateModels.cs` - Models for VEX candidate data
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/VexEvidence.cs` - VEX evidence supporting auto-resolution decisions
- **SmartDiff Pipeline**:
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/SmartDiffPredicate.cs` - `SmartDiffPredicate` applies reachability and VEX filters for quieter results
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/Repositories.cs` - Repository interfaces for SmartDiff detection data
## E2E Test Plan
- [ ] Scan an image with vulnerabilities in unreachable code paths and verify findings are suppressed by reachability gates
- [ ] Verify VEX candidate emission generates auto-resolution candidates for backported patches
- [ ] Verify the SmartDiff pipeline deduplicates findings that appear in both old and new scan results
- [ ] Verify the combination of reachability gates + VEX candidates + deduplication produces significantly fewer actionable findings
- [ ] Verify suppressed findings are still accessible with their suppression reason when queried explicitly

View File

@@ -0,0 +1,34 @@
# Reachability Caching with Incremental Updates
## Module
Scanner
## Status
IMPLEMENTED
## Description
Postgres-backed reachability cache with incremental updates, graph delta computation, impact set calculation, and state flip detection for efficient cache invalidation.
## Implementation Details
- **Reachability Cache**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Cache/IReachabilityCache.cs` - `IReachabilityCache` interface for cached reachability results
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Cache/PostgresReachabilityCache.cs` - `PostgresReachabilityCache` PostgreSQL-backed cache for reachability analysis results
- **Incremental Updates**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Cache/IncrementalReachabilityService.cs` - `IncrementalReachabilityService` performs incremental reachability updates based on graph deltas
- **Graph Delta Computation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Cache/IGraphDeltaComputer.cs` - `IGraphDeltaComputer` interface for computing graph changes
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Cache/GraphDeltaComputer.cs` - `GraphDeltaComputer` computes added/removed/modified nodes and edges between graph versions
- **Impact Set Calculation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Cache/ImpactSetCalculator.cs` - `ImpactSetCalculator` determines which reachability paths are affected by graph changes
- **State Flip Detection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Cache/StateFlipDetector.cs` - `StateFlipDetector` detects reachability state changes (reachable->unreachable or vice versa) for cache invalidation
- **PR Reachability Gate**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Cache/PrReachabilityGate.cs` - `PrReachabilityGate` provides PR-level reachability gating using cached results
## E2E Test Plan
- [ ] Scan an image, verify reachability results are cached in PostgreSQL, then rescan and verify cache hits avoid recomputation
- [ ] Modify one dependency in the image and verify incremental update only recomputes affected paths
- [ ] Verify graph delta computation correctly identifies added, removed, and modified nodes and edges
- [ ] Verify impact set calculation determines exactly which reachability paths need re-evaluation
- [ ] Verify state flip detection correctly identifies findings that changed from reachable to unreachable (or vice versa)
- [ ] Verify the PR reachability gate uses cached results to quickly evaluate PR-level reachability changes

View File

@@ -0,0 +1,22 @@
# Reachability Mini-Map Visualization API
## Module
Scanner
## Status
IMPLEMENTED
## Description
Extracts a compact mini-map from full reachability graphs, providing a simplified topological view (MiniMapNode, MiniMapPath models) for quick visual orientation. Distinct from existing "Reachability Subgraph Extraction" which is about proof-of-exposure, not UI visualization.
## Implementation Details
- **Mini-Map Extractor**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/MiniMap/MiniMapExtractor.cs` - `MiniMapExtractor` extracts compact mini-map representations from full reachability graphs for quick visual orientation
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/MiniMap/ReachabilityMiniMap.cs` - `ReachabilityMiniMap` model containing `MiniMapNode` and `MiniMapPath` structures for simplified topological views
## E2E Test Plan
- [ ] Generate a mini-map from a reachability graph and verify it contains simplified nodes and paths
- [ ] Verify the mini-map correctly preserves the topological structure (entrypoints, intermediate hops, vulnerable sinks)
- [ ] Verify the mini-map node count is significantly smaller than the full reachability graph
- [ ] Verify mini-map paths include key metadata (gate types, confidence levels) for each path segment
- [ ] Verify the API returns the mini-map in a format suitable for UI rendering (JSON with coordinates/layout hints)

View File

@@ -0,0 +1,35 @@
# Reachability Slice DSSE Predicate (Attestable Minimal Subgraph)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Defines attestable reachability slices as DSSE predicates (`stellaops.dev/predicates/reachability-slice@v1`) containing minimal subgraphs for specific CVE queries. Includes slice extraction from full call graphs, DSSE signing with CAS storage, and verdict computation (reachable/unreachable/unknown with confidence scores).
## Implementation Details
- **Slice Extraction**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceExtractor.cs` - `SliceExtractor` extracts minimal subgraphs from full call graphs for specific CVE queries
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceModels.cs` - Models for reachability slices including verdict (reachable/unreachable/unknown) with confidence scores
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceSchema.cs` - Schema definition for `stellaops.dev/predicates/reachability-slice@v1` predicate
- **DSSE Signing**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceDsseSigner.cs` - `SliceDsseSigner` signs reachability slices as DSSE predicates
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceHasher.cs` - `SliceHasher` computes content-addressed hashes for slice integrity
- **CAS Storage**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceCasStorage.cs` - `SliceCasStorage` content-addressable storage for DSSE-signed reachability slices
- **Policy Binding**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/PolicyBinding.cs` - Policy version binding for slices
- **Observed Path Slices**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/ObservedPathSliceGenerator.cs` - Generates slices from runtime-observed paths
- **Diff Computation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/SliceDiffComputer.cs` - Computes diffs between slice versions
## E2E Test Plan
- [ ] Extract a reachability slice for a specific CVE and verify it contains the minimal subgraph (entrypoint to vulnerable function)
- [ ] Verify the slice is signed as a DSSE predicate with `stellaops.dev/predicates/reachability-slice@v1` type
- [ ] Verify the slice includes a verdict (reachable/unreachable/unknown) with a confidence score
- [ ] Verify DSSE signature verification passes for a correctly signed slice
- [ ] Verify CAS storage correctly stores and retrieves slices by content address
- [ ] Verify slice diff computation identifies changes between two slice versions for the same CVE

View File

@@ -0,0 +1,33 @@
# Reachability Status Classification (R0-R3/UNREACHABLE through REACHABLE_PROVEN)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Reachability classification with multiple tiers (unreachable, possibly reachable, reachable static, reachable proven) and confidence scoring with deterministic modifiers.
## Implementation Details
- **Reachability Models**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/DependencyReachabilityModels.cs` - Defines reachability status tiers (R0=UNREACHABLE, R1=POSSIBLY_REACHABLE, R2=REACHABLE_STATIC, R3=REACHABLE_PROVEN) with confidence scoring
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/ReachabilityPolicy.cs` - `ReachabilityPolicy` configures classification thresholds and tier boundaries
- **Static Analysis**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/StaticReachabilityAnalyzer.cs` - `StaticReachabilityAnalyzer` performs static call graph analysis for R2 classification
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/ConditionalReachabilityAnalyzer.cs` - `ConditionalReachabilityAnalyzer` handles conditional reachability (feature flags, config-dependent paths)
- **Combiner**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/ReachGraphReachabilityCombiner.cs` - `ReachGraphReachabilityCombiner` combines static and runtime signals for final classification
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/VulnerabilityReachabilityFilter.cs` - `VulnerabilityReachabilityFilter` filters vulnerabilities based on reachability status
- **Reporting**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/Reporting/DependencyReachabilityReporter.cs` - Reporter for reachability classification results
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/Reporting/DependencyReachabilityReport.cs` - Report model
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Dependencies/ReachabilityReportBuilder.cs` - Builder for constructing reports
## E2E Test Plan
- [ ] Scan a container with a vulnerability in unreachable code and verify it is classified as R0 (UNREACHABLE)
- [ ] Scan a container with a vulnerability in statically reachable code (call graph path exists) and verify R2 (REACHABLE_STATIC)
- [ ] Verify runtime-confirmed reachability (observed call) promotes classification to R3 (REACHABLE_PROVEN)
- [ ] Verify conditional reachability (behind feature flag or config) is classified as R1 (POSSIBLY_REACHABLE) with appropriate confidence
- [ ] Verify confidence scores are computed deterministically for the same input
- [ ] Verify the vulnerability filter correctly suppresses R0 findings from default result sets

View File

@@ -0,0 +1,32 @@
# Reachability Subgraph Extraction and Proof of Exposure
## Module
Scanner
## Status
IMPLEMENTED
## Description
Full subgraph extraction for reachability proofs with witness tracking, explanation generation, and proof spine building.
## Implementation Details
- **Subgraph Extraction**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Subgraph/ReachabilitySubgraphExtractor.cs` - `ReachabilitySubgraphExtractor` extracts full subgraphs for reachability proofs including all nodes and edges on paths from entrypoints to vulnerable sinks
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/SubgraphExtractor.cs` - Base subgraph extraction logic
- **Witness Tracking**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitness.cs` - `PathWitness` records witnessed reachability paths
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/RuntimeObservation.cs` - `RuntimeObservation` records runtime-observed call events with stack samples
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/IRuntimeWitnessGenerator.cs` - Interface for generating runtime witnesses
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/RuntimeWitnessRequest.cs` - Request model for witness generation
- **Attestation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Attestation/ReachabilitySubgraphPublisher.cs` - Publishes proof-of-exposure subgraphs as attestations
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Attestation/ReachabilityWitnessPublisher.cs` - Publishes witness records as attestations
- **Resolver**: `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/IReachabilityResolver.cs` - Interface for resolving reachability queries
## E2E Test Plan
- [ ] Extract a subgraph for a specific vulnerability and verify it contains all nodes and edges from entrypoint to vulnerable sink
- [ ] Verify witness tracking records runtime-observed call events that confirm reachability
- [ ] Verify proof-of-exposure subgraphs are publishable as DSSE-signed attestations
- [ ] Verify the subgraph includes gate annotations (auth, admin-only) on intermediate nodes
- [ ] Verify explanation generation produces human-readable descriptions of the exposure path
- [ ] Verify the reachability resolver correctly queries subgraphs for specific CVE/component pairs

View File

@@ -0,0 +1,30 @@
# Reachability Trace Export Endpoint with Runtime Evidence Overlays
## Module
Scanner
## Status
IMPLEMENTED
## Description
New trace export endpoint (GET /scans/{scanId}/reachability/traces/export) that exports reachability graphs in JSON-Lines or GraphSON format. Includes runtime-confirmed edge flags, reachability scores (0-1), evidence URIs, and SARIF relatedLocations references. Uses StellaOps.Canonical.Json for deterministic content digests. Runtime annotations are overlays only, preserving lattice semantics.
## Implementation Details
- **Reachability Endpoints**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/ReachabilityEndpoints.cs` - `ReachabilityEndpoints` including trace export (`GET /scans/{scanId}/reachability/traces/export`) with format selection (JSON-Lines, GraphSON)
- **Runtime Evidence**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Runtime/RuntimeStaticMerger.cs` - `RuntimeStaticMerger` merges runtime observations as overlays onto static reachability graphs
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Runtime/EbpfRuntimeReachabilityCollector.cs` - `EbpfRuntimeReachabilityCollector` collects runtime evidence from eBPF probes
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Runtime/EbpfSignalMerger.cs` - `EbpfSignalMerger` merges eBPF signals into reachability graphs
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Runtime/IRuntimeReachabilityCollector.cs` - Interface for runtime collectors
- **Observation Store**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/FunctionMap/ObservationStore/IRuntimeObservationStore.cs` - Interface for runtime observation storage
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/FunctionMap/ObservationStore/PostgresRuntimeObservationStore.cs` - PostgreSQL-backed observation store
## E2E Test Plan
- [ ] Export reachability traces via `GET /scans/{scanId}/reachability/traces/export` in JSON-Lines format and verify output is valid
- [ ] Export in GraphSON format and verify the output is a valid graph structure
- [ ] Verify runtime-confirmed edges are flagged with runtime evidence metadata
- [ ] Verify reachability scores (0-1) are included for each path
- [ ] Verify evidence URIs link to the supporting evidence artifacts
- [ ] Verify deterministic content digests are computed using canonical JSON serialization

View File

@@ -0,0 +1,25 @@
# Remediation PR Generator (Deterministic PR/MR Creation)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Deterministic PR/MR generation with template sections (summary, steps, SBOM changes, test requirements, rollback steps, VEX claim, evidence), actual SCM branch creation and file updates, and remediation apply endpoint returning PR metadata.
## Implementation Details
- **Evidence Contracts**:
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/UnifiedEvidenceContracts.cs` - Contracts including remediation evidence models with SBOM changes, VEX claims, and PR metadata
- **Reachability Endpoints**:
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/ReachabilityEndpoints.cs` - Endpoints supporting remediation actions with reachability context
- **PR Annotation Service**:
- `src/Scanner/StellaOps.Scanner.WebService/Services/PrAnnotationService.cs` - `PrAnnotationService` generates PR/MR annotations with evidence links
## E2E Test Plan
- [ ] Trigger remediation PR generation for a vulnerable dependency and verify a PR template is generated with summary, steps, and SBOM changes sections
- [ ] Verify the generated PR includes test requirements and rollback steps
- [ ] Verify VEX claims are included in the PR body linking to reachability evidence
- [ ] Verify the remediation apply endpoint returns PR metadata (URL, branch name, commit SHA)
- [ ] Verify deterministic generation produces identical PR content for the same input

View File

@@ -0,0 +1,23 @@
# Reproducible Rebuild Service (reproduce.debian.net Integration)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Integration with reproduce.debian.net for reproducible rebuild verification, with local rebuild backend and determinism validator. Enables binary identity verification by comparing rebuilt binaries against published ones. Distinct from the known "Reproducible build verification" which is a high-level concept - this is the concrete service implementation.
## Implementation Details
- **Reproducibility Verification**:
- `src/Scanner/__Libraries/StellaOps.Scanner.BuildProvenance/Analyzers/ReproducibilityVerifier.cs` - `ReproducibilityVerifier` verifies binary identity by comparing rebuilt binaries against published ones
- **Rebuild Proof**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Lineage/RebuildProof.cs` - `RebuildProof` model capturing rebuild verification results (match/mismatch, hash comparison)
## E2E Test Plan
- [ ] Verify the reproducibility verifier can compare a rebuilt binary against its published counterpart
- [ ] Verify matching binaries produce a successful rebuild proof
- [ ] Verify mismatching binaries produce a failure with detailed diff information
- [ ] Verify rebuild proof includes hash comparison (SHA256) of the rebuilt vs published binary
- [ ] Verify the service handles unavailable rebuild sources gracefully

View File

@@ -0,0 +1,23 @@
# RPM Legacy BDB Packages Database Fallback
## Module
Scanner
## Status
IMPLEMENTED
## Description
Adds fallback support for legacy Berkeley DB (BDB) format RPM package databases alongside the modern SQLite format, enabling package discovery on older RHEL/CentOS images.
## Implementation Details
- **Berkeley DB Reader**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Rpm/Internal/BerkeleyDbReader.cs` - `BerkeleyDbReader` parses legacy BDB format RPM package databases for older RHEL/CentOS images
- **RPM Database Reader**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Rpm/RpmDatabaseReader.cs` - `RpmDatabaseReader` with fallback logic: tries modern SQLite format first, falls back to BDB format for legacy images
## E2E Test Plan
- [ ] Scan an older RHEL/CentOS image (pre-RHEL 8) using BDB format RPM database and verify packages are discovered
- [ ] Scan a modern RHEL/CentOS image using SQLite format RPM database and verify it uses the primary path
- [ ] Verify the fallback logic correctly detects the database format and chooses the appropriate reader
- [ ] Verify BDB-parsed packages include correct name, version, release, and architecture metadata
- [ ] Verify both BDB and SQLite paths produce consistent package lists for the same set of installed packages

View File

@@ -0,0 +1,34 @@
# Runtime Observation Record
## Module
Scanner
## Status
IMPLEMENTED
## Description
RuntimeObservation record wrapping RuntimeCallEvent with observation count, stack sample hash, container/process context, and source type (tetragon/otel/profiler/tracer), with PostgreSQL persistence.
## Implementation Details
- **Runtime Observation Model**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/RuntimeObservation.cs` - `RuntimeObservation` record wrapping `RuntimeCallEvent` with observation count, stack sample hash, container/process context, and source type
- **Observation Store**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/FunctionMap/ObservationStore/IRuntimeObservationStore.cs` - `IRuntimeObservationStore` interface for persisting runtime observations
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/FunctionMap/ObservationStore/PostgresRuntimeObservationStore.cs` - `PostgresRuntimeObservationStore` PostgreSQL-backed persistence for runtime observations
- **Runtime Collection**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Runtime/EbpfRuntimeReachabilityCollector.cs` - Collects observations from eBPF/Tetragon probes
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Runtime/IRuntimeReachabilityCollector.cs` - Interface for runtime observation collectors
- **Witness Generation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/IRuntimeWitnessGenerator.cs` - Generates witnesses from runtime observations
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/RuntimeWitnessRequest.cs` - Request model for witness generation
- **Claim Verification**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/FunctionMap/Verification/IClaimVerifier.cs` - Interface for verifying runtime claims
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/FunctionMap/Verification/ClaimVerifier.cs` - Verifies runtime observations against static analysis claims
## E2E Test Plan
- [ ] Submit a runtime observation from Tetragon eBPF probes and verify it is persisted in PostgreSQL with correct source type
- [ ] Verify observation count is incremented for repeated observations of the same call event
- [ ] Verify stack sample hash is computed and stored for each unique stack trace
- [ ] Verify container/process context (container ID, PID, namespace) is captured in the observation record
- [ ] Verify observations from different source types (tetragon, otel, profiler, tracer) are correctly classified
- [ ] Verify the claim verifier correlates runtime observations with static reachability claims

View File

@@ -0,0 +1,28 @@
# Runtime-Static SBOM Reconciliation
## Module
Scanner
## Status
IMPLEMENTED
## Description
Reconciles runtime process snapshots (from /proc filesystem) against static SBOM analysis to identify discrepancies between declared and actually-loaded libraries. Detects ghost libraries (loaded at runtime but missing from SBOM) and phantom libraries (in SBOM but not loaded).
## Implementation Details
- **Runtime Reconciliation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Runtime/EntryTraceRuntimeReconciler.cs` - `EntryTraceRuntimeReconciler` reconciles runtime process snapshots against static SBOM analysis, detecting ghost libraries (runtime-only) and phantom libraries (SBOM-only)
- **Process Snapshots**:
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Runtime/ProcFileSystemSnapshot.cs` - Collects runtime process state from /proc filesystem
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Runtime/ProcProcess.cs` - Model for runtime processes
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Runtime/ProcGraph.cs` - Process dependency graph
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Runtime/ProcGraphBuilder.cs` - Builds process graphs from snapshots
- **Runtime-Static Merge**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Runtime/RuntimeStaticMerger.cs` - `RuntimeStaticMerger` merges runtime observations with static analysis for comprehensive views
## E2E Test Plan
- [ ] Reconcile runtime process snapshots against static SBOM and verify ghost libraries (loaded at runtime but missing from SBOM) are detected
- [ ] Verify phantom libraries (declared in SBOM but not loaded at runtime) are identified
- [ ] Verify matching libraries (present in both runtime and SBOM) are confirmed as consistent
- [ ] Verify the reconciliation report includes library name, version, and source (runtime vs static) for each discrepancy
- [ ] Verify runtime-static merge correctly augments static reachability analysis with runtime-confirmed paths

View File

@@ -0,0 +1,25 @@
# Runtime Timeline API
## Module
Scanner
## Status
IMPLEMENTED
## Description
Provides a chronological timeline of runtime observations (RuntimeTimeline model, TimelineBuilder, RuntimePosture enum) with an API endpoint. Distinct from "Runtime Reachability Collection" which is about gathering data, not the timeline visualization API.
## Implementation Details
- **Timeline Model**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/Timeline/RuntimeTimeline.cs` - `RuntimeTimeline` model representing a chronological sequence of runtime observations with `RuntimePosture` classification
- **Timeline Builder**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Native/RuntimeCapture/Timeline/TimelineBuilder.cs` - `TimelineBuilder` constructs timeline instances from raw runtime observations, ordering events chronologically and computing posture
- **Tests**:
- `src/Scanner/__Tests/StellaOps.Scanner.Analyzers.Native.Library.Tests/RuntimeCapture/Timeline/TimelineBuilderTests.cs` - Unit tests for timeline construction and posture computation
## E2E Test Plan
- [ ] Build a runtime timeline from a set of native runtime observations and verify events are ordered chronologically
- [ ] Verify the `RuntimePosture` enum correctly classifies the overall runtime posture based on observation patterns
- [ ] Verify timeline entries include observation timestamps, source types, and observation counts
- [ ] Submit runtime observations over time and verify the timeline reflects the temporal progression accurately
- [ ] Verify the timeline API endpoint returns the timeline in a serializable format with correct pagination support

View File

@@ -0,0 +1,27 @@
# Runtime-to-Static Graph Merge Algorithm
## Module
Scanner
## Status
IMPLEMENTED
## Description
Merges runtime observations with static call graphs, marking existing edges as "observed" with confidence boost to 1.0, and adding new edges for dynamic dispatch paths discovered at runtime.
## Implementation Details
- **Runtime-Static Merger**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Runtime/RuntimeStaticMerger.cs` - `RuntimeStaticMerger` merges runtime observations with static analysis graphs, boosting confidence of edges confirmed at runtime to 1.0 and adding new edges for dynamic dispatch paths
- **eBPF Signal Merger**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Runtime/EbpfSignalMerger.cs` - `EbpfSignalMerger` merges eBPF-sourced runtime signals into the static graph
- **Observed Path Slice Generator**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Slices/ObservedPathSliceGenerator.cs` - Generates reachability slices from runtime-observed paths merged into static analysis
- **Trace Retention**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Runtime/Retention/TraceRetentionManager.cs` - `TraceRetentionManager` manages retention of runtime traces used in the merge process
## E2E Test Plan
- [ ] Merge a runtime observation set with a static call graph and verify existing edges that were observed at runtime have confidence boosted to 1.0
- [ ] Verify new edges are added for dynamic dispatch paths discovered at runtime (e.g., reflection, virtual method dispatch) that are not present in the static graph
- [ ] Verify the merged graph retains all static-only edges with their original confidence scores
- [ ] Verify the merge algorithm handles conflicting information between static and runtime analysis (e.g., static says unreachable, runtime says observed)
- [ ] Verify eBPF-sourced signals are correctly merged into the graph via `EbpfSignalMerger`

View File

@@ -0,0 +1,45 @@
# Runtime Witness Predicate Types
## Module
Scanner
## Status
IMPLEMENTED
## Description
Runtime witness predicate types with DSSE signing, path witnesses, runtime observations, and suppression witnesses for reachability analysis.
## Implementation Details
- **Predicate Types**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/RuntimeWitnessPredicateTypes.cs` - `RuntimeWitnessPredicateTypes` defining predicate type URIs for path witnesses, runtime observations, and suppression witnesses
- **Path Witnesses**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitness.cs` - `PathWitness` model representing a witnessed execution path through the call graph
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitnessBuilder.cs` - `PathWitnessBuilder` constructs path witnesses from observation data
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/IPathWitnessBuilder.cs` - Interface for path witness construction
- **Suppression Witnesses**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/SuppressionWitness.cs` - `SuppressionWitness` model for marking paths as suppressed (not reachable)
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/SuppressionWitnessBuilder.cs` - Builds suppression witnesses with evidence
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/SuppressionWitnessSchema.cs` - Schema definition for suppression witnesses
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/ISuppressionWitnessBuilder.cs` - Interface for suppression witness construction
- **DSSE Signing**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/WitnessDsseSigner.cs` - `WitnessDsseSigner` signs witnesses using DSSE envelopes
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/IWitnessDsseSigner.cs` - Interface for witness DSSE signing
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/SuppressionDsseSigner.cs` - DSSE signer specialized for suppression witnesses
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/ISuppressionDsseSigner.cs` - Interface for suppression DSSE signing
- **Witness Verification**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/WitnessSchema.cs` - Schema definition for witness validation
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/WitnessMatcher.cs` - `WitnessMatcher` matches witnesses to reachability claims
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/IWitnessVerifier.cs` - Interface for witness verification
- **Supporting Types**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/SignedWitnessGenerator.cs` - Generates signed witnesses combining building and signing
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/RuntimeWitnessRequest.cs` - Request model for runtime witness generation
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/ObservationType.cs` - `ObservationType` enum classifying observation sources
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/ClaimIdGenerator.cs` - Generates deterministic claim IDs for witnesses
## E2E Test Plan
- [ ] Create a path witness from runtime observations and verify it includes the observed call path with entry point and sink
- [ ] Sign a path witness with DSSE and verify the envelope contains the correct predicate type URI from `RuntimeWitnessPredicateTypes`
- [ ] Create a suppression witness and verify it marks the specified path as suppressed with justification evidence
- [ ] Verify `WitnessMatcher` correctly correlates witnesses with reachability claims by matching call path signatures
- [ ] Verify witness verification validates both the DSSE signature and the schema conformance of the witness payload
- [ ] Verify the `ClaimIdGenerator` produces deterministic, content-addressed IDs for identical witness data

View File

@@ -0,0 +1,33 @@
# SARIF 2.1.0 Export System (Findings, SmartDiff, GitHub Code Scanning)
## Module
Scanner
## Status
IMPLEMENTED
## Description
Full SARIF 2.1.0 export service with rule registry (STELLA-VULN, STELLA-SEC, STELLA-SC, STELLA-BIN taxonomy), fingerprint generation, schema validation, export options, and dedicated library. Exports both main findings and SmartDiff results (rules SDIFF001-004). GitHub code scanning integration endpoints and IDE-compatible output.
## Implementation Details
- **SARIF Export Service**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Sarif/SarifExportService.cs` - `SarifExportService` converts scanner findings into SARIF 2.1.0 format documents
- `src/Scanner/__Libraries/StellaOps.Scanner.Sarif/ISarifExportService.cs` - Interface for SARIF export
- `src/Scanner/__Libraries/StellaOps.Scanner.Sarif/SarifExportOptions.cs` - `SarifExportOptions` controlling export behavior (include SmartDiff, fingerprints, etc.)
- **Rule Registry**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Sarif/Rules/SarifRuleRegistry.cs` - `SarifRuleRegistry` maintaining the taxonomy of SARIF rules (STELLA-VULN, STELLA-SEC, STELLA-SC, STELLA-BIN) and SmartDiff rules (SDIFF001-004)
- `src/Scanner/__Libraries/StellaOps.Scanner.Sarif/Rules/ISarifRuleRegistry.cs` - Interface for rule registry
- **Fingerprint Generation**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Sarif/Fingerprints/FingerprintGenerator.cs` - `FingerprintGenerator` produces deterministic fingerprints for SARIF results to enable deduplication
- `src/Scanner/__Libraries/StellaOps.Scanner.Sarif/Fingerprints/IFingerprintGenerator.cs` - Interface for fingerprint generation
- **Models**:
- `src/Scanner/__Libraries/StellaOps.Scanner.Sarif/Models/SarifModels.cs` - SARIF 2.1.0 data models (SarifLog, Run, Result, Rule, Location, etc.)
- `src/Scanner/__Libraries/StellaOps.Scanner.Sarif/FindingInput.cs` - `FindingInput` model converting scanner findings into SARIF-compatible input
## E2E Test Plan
- [ ] Export scanner findings in SARIF 2.1.0 format and verify the output validates against the SARIF 2.1.0 JSON schema
- [ ] Verify the rule registry includes all expected rule IDs (STELLA-VULN-*, STELLA-SEC-*, STELLA-SC-*, STELLA-BIN-*) with correct taxonomy metadata
- [ ] Verify SmartDiff results are exported with rules SDIFF001-004 and include change context (added/removed/modified findings)
- [ ] Verify fingerprint generation produces deterministic fingerprints for the same finding across exports
- [ ] Verify the SARIF output is compatible with GitHub code scanning upload format (correct schema version, tool information, and result structure)
- [ ] Verify `SarifExportOptions` correctly controls which findings are included (e.g., filtering by severity, including/excluding SmartDiff)

Some files were not shown because too many files have changed in this diff Show More