partly or unimplemented features - now implemented
This commit is contained in:
master
@@ -1592,5 +1592,152 @@ Offline verification bundles include tile proofs for air-gapped environments.
|
||||
|
||||
---
|
||||
|
||||
*Document Version: 1.3.0*
|
||||
*Last Updated: 2026-01-28*
|
||||
## 13. Cross-Distro Coverage Matrix for Backport Validation
|
||||
|
||||
Manages a curated set of high-impact CVEs with per-distribution backport
|
||||
status tracking, enabling systematic validation of backport detection
|
||||
accuracy across Alpine, Debian, and RHEL.
|
||||
|
||||
### 13.1 Architecture
|
||||
|
||||
1. **CuratedCveEntry** — One row per CVE (e.g., Heartbleed, Baron Samedit)
|
||||
with cross-distro `DistroCoverageEntry` array tracking backport status
|
||||
per distro-version
|
||||
2. **CrossDistroCoverageService** — In-memory coverage matrix with upsert,
|
||||
query, summary, and validation marking operations
|
||||
3. **SeedBuiltInEntries** — Idempotent seeding of 5 curated high-impact CVEs
|
||||
(CVE-2014-0160, CVE-2021-3156, CVE-2015-0235, CVE-2023-38545, CVE-2024-6387)
|
||||
with pre-populated backport status across Alpine, Debian, and RHEL versions
|
||||
|
||||
### 13.2 Distro Families & Backport Status
|
||||
|
||||
| Enum | Values |
|
||||
|---|---|
|
||||
| `DistroFamily` | Alpine, Debian, Rhel |
|
||||
| `BackportStatus` | NotPatched, Backported, NotApplicable, Unknown |
|
||||
|
||||
### 13.3 Models
|
||||
|
||||
| Type | Description |
|
||||
|---|---|
|
||||
| `DistroCoverageEntry` | Per distro-version: package name/version, backport status, validated flag |
|
||||
| `CuratedCveEntry` | CVE with CommonName, CvssScore, CweIds, Coverage array, computed CoverageRatio |
|
||||
| `CrossDistroCoverageSummary` | Aggregated counts: TotalCves, TotalEntries, ValidatedEntries, ByDistro breakdown |
|
||||
| `DistroBreakdown` | Per-distro EntryCount, ValidatedCount, BackportedCount |
|
||||
| `CuratedCveQuery` | Component/Distro/Status/OnlyUnvalidated filters with Limit/Offset paging |
|
||||
|
||||
### 13.4 Built-in Curated CVEs
|
||||
|
||||
| CVE | Component | Common Name | CVSS |
|
||||
|---|---|---|---|
|
||||
| CVE-2014-0160 | openssl | Heartbleed | 7.5 |
|
||||
| CVE-2021-3156 | sudo | Baron Samedit | 7.8 |
|
||||
| CVE-2015-0235 | glibc | GHOST | 10.0 |
|
||||
| CVE-2023-38545 | curl | SOCKS5 heap overflow | 9.8 |
|
||||
| CVE-2024-6387 | openssh | regreSSHion | 8.1 |
|
||||
|
||||
### 13.5 DI Registration
|
||||
|
||||
`ICrossDistroCoverageService` → `CrossDistroCoverageService` registered via
|
||||
TryAddSingleton in `GoldenSetServiceCollectionExtensions.AddGoldenSetServices()`.
|
||||
|
||||
### 13.6 OTel Metrics
|
||||
|
||||
Meter: `StellaOps.BinaryIndex.GoldenSet.CrossDistro`
|
||||
|
||||
| Counter | Description |
|
||||
|---|---|
|
||||
| `crossdistro.upsert.total` | CVE entries upserted |
|
||||
| `crossdistro.query.total` | Coverage queries executed |
|
||||
| `crossdistro.seed.total` | Built-in entries seeded |
|
||||
| `crossdistro.validated.total` | Entries marked as validated |
|
||||
|
||||
### 13.7 Source Files
|
||||
|
||||
- Models: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GoldenSet/Models/CrossDistroCoverageModels.cs`
|
||||
- Interface: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GoldenSet/Services/ICrossDistroCoverageService.cs`
|
||||
- Implementation: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GoldenSet/Services/CrossDistroCoverageService.cs`
|
||||
|
||||
### 13.8 Test Coverage (37 tests)
|
||||
|
||||
- Models: DistroFamily/BackportStatus enum counts, DistroCoverageEntry roundtrips/defaults,
|
||||
CuratedCveEntry coverage ratio/empty, CuratedCveQuery defaults, Summary coverage/empty
|
||||
- Service: SeedBuiltInEntries population/idempotency/heartbleed/baron-samedit/distro coverage,
|
||||
UpsertAsync store-retrieve/overwrite/null/empty, GetByCveIdAsync unknown/case-insensitive/null,
|
||||
QueryAsync all/component/distro/status/unvalidated/limit-offset/ordering,
|
||||
GetSummaryAsync counts/empty, SetValidatedAsync mark/unknown-cve/unknown-version/summary/null,
|
||||
CreateBuiltInEntries deterministic/distro-coverage
|
||||
|
||||
---
|
||||
|
||||
## 14. ELF Segment Normalization for Delta Hashing
|
||||
|
||||
### 14.1 Purpose
|
||||
|
||||
The existing instruction-level normalization (X64/Arm64 pipelines) operates on
|
||||
disassembled instruction streams. ELF Segment Normalization fills the gap for
|
||||
**raw binary bytes** — zeroing position-dependent data (relocation entries,
|
||||
GOT/PLT displacements, alignment padding) and canonicalizing NOP sleds
|
||||
*before* disassembly, enabling deterministic delta hashing across builds
|
||||
compiled at different base addresses or link orders.
|
||||
|
||||
### 14.2 Key Types
|
||||
|
||||
| Type | Location | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `ElfNormalizationStep` | `Normalization/ElfSegmentNormalizer.cs` | Enum of normalization passes (RelocationZeroing, GotPltCanonicalization, NopCanonicalization, JumpTableRewriting, PaddingZeroing) |
|
||||
| `ElfSegmentNormalizationOptions` | same | Options record with `Default` and `Minimal` presets |
|
||||
| `ElfSegmentNormalizationResult` | same | Result with NormalizedBytes, DeltaHash (SHA-256), ModifiedBytes, AppliedSteps, StepCounts, computed ModificationRatio |
|
||||
| `IElfSegmentNormalizer` | same | Interface: `Normalize`, `ComputeDeltaHash` |
|
||||
| `ElfSegmentNormalizer` | same | Implementation with 5 internal passes and 2 OTel counters |
|
||||
|
||||
### 14.3 Normalization Passes
|
||||
|
||||
1. **RelocationZeroing** — Scans for ELF64 RELA-shaped entries (heuristic:
|
||||
info field encodes valid x86-64 relocation types 1–42 with symbol index
|
||||
≤100 000); zeros the offset and addend fields (16 bytes per entry).
|
||||
2. **GotPltCanonicalization** — Detects `FF 25` (JMP [rip+disp32]) and
|
||||
`FF 35` (PUSH [rip+disp32]) PLT stub patterns; zeros the 4-byte
|
||||
displacement to remove position-dependent indirect jump targets.
|
||||
3. **NopCanonicalization** — Matches 7 multi-byte x86-64 NOP variants
|
||||
(2–7 bytes each, per Intel SDM) and replaces with canonical single-byte
|
||||
NOPs (0x90).
|
||||
4. **JumpTableRewriting** — Identifies sequences of 4+ consecutive 8-byte
|
||||
entries sharing the same upper 32 bits (switch-statement jump tables);
|
||||
zeros the entries.
|
||||
5. **PaddingZeroing** — Detects runs of 4+ alignment padding bytes (0xCC or
|
||||
0x00) between code regions and zeros them.
|
||||
|
||||
### 14.4 Delta Hashing
|
||||
|
||||
`ComputeDeltaHash` produces a lowercase SHA-256 hex string of the normalized
|
||||
byte buffer. Two builds of the same source compiled at different addresses
|
||||
will produce the same delta hash after normalization.
|
||||
|
||||
### 14.5 OTel Instrumentation
|
||||
|
||||
Meter: `StellaOps.BinaryIndex.Normalization.ElfSegment`
|
||||
|
||||
| Counter | Description |
|
||||
| --- | --- |
|
||||
| `elfsegment.normalize.total` | Segments normalized |
|
||||
| `elfsegment.bytes.modified` | Total bytes modified across all passes |
|
||||
|
||||
### 14.6 DI Registration
|
||||
|
||||
`IElfSegmentNormalizer` is registered as `TryAddSingleton<ElfSegmentNormalizer>`
|
||||
inside `AddNormalizationPipelines()` in `ServiceCollectionExtensions.cs`.
|
||||
|
||||
### 14.7 Test Coverage (35 tests)
|
||||
|
||||
- Models: DefaultOptions (all enabled), MinimalOptions (relocations only), ModificationRatio zero/computed, enum values
|
||||
- Service: Constructor null guard, empty input result + SHA-256, ComputeDeltaHash determinism/distinct,
|
||||
NOP canonicalization (3-byte, 2-byte, 4-byte, no-NOP, 7-byte, single-byte),
|
||||
GOT/PLT (JMP disp32, PUSH disp32), alignment padding (INT3 run, zero run, short run),
|
||||
relocation zeroing (valid RELA, invalid entry), jump table (consecutive addresses, random data),
|
||||
full pipeline (deterministic hash, default vs minimal, all-disabled, step-count consistency)
|
||||
|
||||
---
|
||||
|
||||
*Document Version: 1.5.0*
|
||||
*Last Updated: 2026-02-08*
|
||||
|
||||
Reference in New Issue
Block a user