save checkpoint
This commit is contained in:
master
44
docs/features/checked/scanner/binary-intelligence-engine.md
Normal file
44
docs/features/checked/scanner/binary-intelligence-engine.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Binary Intelligence Engine (Function-Level Code Fingerprinting)
|
||||
|
||||
## Module
|
||||
Scanner
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Function-level binary code fingerprinting for entry-trace native terminals, including deterministic symbol-window extraction, vulnerable marker matching, and binary intelligence payload propagation through storage and API contracts.
|
||||
|
||||
## Implementation Details
|
||||
- **Entry-trace graph contract**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/EntryTraceTypes.cs`
|
||||
- Added `EntryTraceGraph.BinaryIntelligence`
|
||||
- Added `EntryTraceBinaryIntelligence`, `EntryTraceBinaryTarget`, `EntryTraceBinaryVulnerability`
|
||||
- **Serializer/storage round-trip**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Serialization/EntryTraceGraphSerializer.cs`
|
||||
- Added binary intelligence contract mappings and round-trip conversion.
|
||||
- **Worker enrichment**:
|
||||
- `src/Scanner/StellaOps.Scanner.Worker/Processing/EntryTraceExecutionService.cs`
|
||||
- Integrates binary intelligence generation for native terminals during entry-trace execution.
|
||||
- Produces deterministic function windows, binary-format inference, CVE marker extraction, and graph enrichment.
|
||||
- **API surface**:
|
||||
- `src/Scanner/StellaOps.Scanner.WebService/Contracts/EntryTraceResponse.cs`
|
||||
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/ScanEndpoints.cs`
|
||||
- Entry-trace response returns `graph.binaryIntelligence` when available.
|
||||
- **Behavioral coverage**:
|
||||
- `src/Scanner/__Tests/StellaOps.Scanner.Worker.Tests/EntryTraceExecutionServiceTests.cs`
|
||||
- `src/Scanner/__Tests/StellaOps.Scanner.WebService.Tests/ScansEndpointsTests.cs`
|
||||
- `src/Scanner/__Tests/StellaOps.Scanner.Storage.Tests/EntryTraceResultStoreTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [x] Verify function-level binary fingerprinting behavior in EntryTrace binary test namespace.
|
||||
- [x] Verify worker entry-trace execution attaches binary intelligence for native terminal binaries.
|
||||
- [x] Verify `GET /api/v1/scans/{scanId}/entrytrace` returns graph payload including `binaryIntelligence`.
|
||||
- [x] Verify persisted `EntryTraceResult` round-trips binary intelligence through serializer/repository.
|
||||
|
||||
## Verification
|
||||
- Run ID: `run-002`
|
||||
- Date (UTC): 2026-02-12
|
||||
- Tier 0: Source verification passed (`tier0-source-check.json`).
|
||||
- Tier 1: Build and focused test executions passed (`tier1-build-check.json`, `tier1-build-results.json`, `tier1-test-results.json`).
|
||||
- Tier 2: Integration checks passed for worker, endpoint, and storage round-trip (`tier2-e2e-check.json`).
|
||||
@@ -0,0 +1,51 @@
|
||||
# Binary SBOM and Build-ID to PURL Mapping
|
||||
|
||||
## Module
|
||||
Scanner
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Binary call graph extraction, offline Build-ID to PURL correlation, patch verification orchestration, and unified binary finding mapping are wired into Scanner worker execution with deterministic Tier 1/Tier 2 evidence.
|
||||
|
||||
## Implementation Details
|
||||
- **Binary call graph extraction**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Extraction/Binary/BinaryCallGraphExtractor.cs`
|
||||
- **Patch verification engine + contracts**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/IPatchVerificationOrchestrator.cs`
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/PatchVerificationOrchestrator.cs`
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.PatchVerification/DependencyInjection/ServiceCollectionExtensions.cs`
|
||||
- **Build-ID index**:
|
||||
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/Index/IBuildIdIndex.cs`
|
||||
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/Index/OfflineBuildIdIndex.cs`
|
||||
- `src/Scanner/StellaOps.Scanner.Analyzers.Native/Index/BuildIdLookupResult.cs`
|
||||
- **Worker runtime wiring**:
|
||||
- `src/Scanner/StellaOps.Scanner.Worker/Extensions/BinaryIndexServiceExtensions.cs`
|
||||
- registers patch verification services in worker binary integration path.
|
||||
- `src/Scanner/StellaOps.Scanner.Worker/Processing/BinaryLookupStageExecutor.cs`
|
||||
- publishes mapped binary findings for downstream gating.
|
||||
- executes Build-ID index batch lookup and stores mapping output.
|
||||
- executes patch verification orchestration and stores verification result.
|
||||
- `src/Scanner/StellaOps.Scanner.Worker/Processing/BinaryFindingMapper.cs`
|
||||
- runtime call path now exercised from binary lookup stage.
|
||||
- **Shared analysis contracts**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.Core/Contracts/ScanAnalysisKeys.cs`
|
||||
- added binary build-id mapping and patch-verification analysis keys.
|
||||
- **Worker validation test**:
|
||||
- `src/Scanner/__Tests/StellaOps.Scanner.Worker.Tests/BinaryLookupStageExecutorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [x] Scan a container image with native binaries containing ELF build-IDs and verify Build-ID to PURL mapping runtime path executes.
|
||||
- [x] Verify binary call graph extraction behavior via `BinaryCallGraphExtractor` tests.
|
||||
- [x] Verify patch verification orchestration behavior executes with patch-data and no-patch-data paths.
|
||||
- [x] Verify binary vulnerability findings are mapped into unified finding objects for downstream stages.
|
||||
- [x] Verify offline Build-ID index resolves exact mappings without network access.
|
||||
- [x] Verify worker runtime wiring includes patch verification, build-id lookup, and finding mapping call sites.
|
||||
|
||||
## Verification
|
||||
- Run ID: `run-002`
|
||||
- Date (UTC): 2026-02-12
|
||||
- Tier 0: Source verification passed (`tier0-source-check.json`).
|
||||
- Tier 1: Build, focused behavior tests, and code-review semantic wiring checks passed (`tier1-build-check.json`, `tier1-code-review.json`).
|
||||
- Tier 2: Integration/e2e summary passed, including runtime wiring parity checks (`tier2-integration-check.json`, `tier2-e2e-check.json`).
|
||||
@@ -0,0 +1,37 @@
|
||||
# Bug ID to CVE Mapping in Changelog Parsing
|
||||
|
||||
## Module
|
||||
Scanner
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Regex-based extraction of changelog bug references (Debian `Closes: #123456`, `RHBZ#123456`, Launchpad `LP: #123456`) with deterministic bug-to-CVE correlation for backport evidence metadata.
|
||||
|
||||
## Implementation Details
|
||||
- **Shared extraction helper**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS/Helpers/ChangelogBugReferenceExtractor.cs` - Extracts bug references and bug-to-CVE mappings from changelog text.
|
||||
- **RPM wiring**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Rpm/RpmPackageAnalyzer.cs` - Applies extractor to RPM changelog entries and emits `vendor.changelogBugRefs` / `vendor.changelogBugToCves`.
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Rpm/Internal/RpmHeaderParser.cs` - Supplies `ChangeLogText` entries from RPM metadata.
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Rpm/Internal/RpmHeader.cs`
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Rpm/Internal/RpmTags.cs`
|
||||
- **DPKG wiring**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.OS.Dpkg/DpkgPackageAnalyzer.cs` - Reads package changelog files (including `.gz`), extracts bug mappings, and merges CVE hints.
|
||||
- **Behavioral coverage**:
|
||||
- `src/Scanner/__Tests/StellaOps.Scanner.Analyzers.OS.Tests/Helpers/ChangelogBugReferenceExtractorTests.cs`
|
||||
- `src/Scanner/__Tests/StellaOps.Scanner.Analyzers.OS.Tests/Dpkg/DpkgChangelogBugCorrelationTests.cs`
|
||||
- `src/Scanner/__Tests/StellaOps.Scanner.Analyzers.OS.Tests/OsAnalyzerDeterminismTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [x] Verify Debian `Closes: #NNNNNN` references are extracted and preserved in metadata.
|
||||
- [x] Verify RPM changelog `RHBZ#NNNNNN` references are extracted.
|
||||
- [x] Verify Launchpad `LP: #NNNNNN` references are extracted.
|
||||
- [x] Verify bug references are cross-referenced with CVE IDs from the same changelog entry.
|
||||
- [x] Verify deterministic metadata and golden snapshot behavior through OS analyzer test runs.
|
||||
|
||||
## Verification
|
||||
- Run: `run-001`
|
||||
- Date (UTC): 2026-02-12
|
||||
- Artifacts: `docs/qa/feature-checks/runs/scanner/bug-id-to-cve-mapping-in-changelog-parsing/run-001/`
|
||||
38
docs/features/checked/scanner/byos-ingestion-workflow.md
Normal file
38
docs/features/checked/scanner/byos-ingestion-workflow.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# BYOS (Bring Your Own SBOM) Ingestion Workflow
|
||||
|
||||
## Module
|
||||
Scanner
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## 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
|
||||
|
||||
## Verification
|
||||
- Verified in `run-001` on 2026-02-12 with Tier 0/1/2 evidence in `docs/qa/feature-checks/runs/scanner/byos-ingestion-workflow/run-001/`.
|
||||
- Tier 2 API checks validated CycloneDX inline upload, SPDX base64 upload, upload record retrieval, and unknown-format rejection paths.
|
||||
Reference in New Issue
Block a user