stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Refactor code structure and optimize performance across multiple modules

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-26 20:03:22 +02:00
parent c786faae84
commit f10d83c444
1385 changed files with 69732 additions and 10280 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
docs/modules/scanner/architecture.md
View File

@@ -316,10 +316,45 @@ Semantic data flows into:
See `docs/modules/scanner/operations/entrypoint-semantic.md` for full schema reference.
**E) Attestation & SBOM bind (optional)**
**E) Binary Vulnerability Lookup (Sprint 20251226_014_BINIDX)**
The **BinaryLookupStageExecutor** enriches scan results with binary-level vulnerability evidence:
* **Identity Extraction**: For each ELF/PE/Mach-O binary, extract Build-ID, file SHA256, and architecture. Generate a `binary_key` for catalog lookups.
* **Build-ID Catalog Lookup**: Query the BinaryIndex known-build catalog using Build-ID as primary key. Returns CVE matches with high confidence (>=0.95) when the exact binary version is indexed.
* **Fingerprint Matching**: For binaries not in the catalog, compute position-independent fingerprints (basic-block, CFG, string-refs) and match against the vulnerability corpus. Returns similarity scores and confidence.
* **Fix Status Detection**: For each CVE match, query distro-specific backport information to determine if the vulnerability was fixed via distro patch. Methods: `changelog`, `patch_analysis`, `advisory`.
* **Valkey Cache**: All lookups are cached with configurable TTL (default 1 hour for identities, 30 minutes for fingerprints). Target cache hit rate: >80% for repeat scans.
**BinaryFindingMapper** converts matches to standard findings format with `BinaryFindingEvidence`:
```csharp
public sealed record BinaryFindingEvidence
{
public required string BinaryKey { get; init; }
public string? BuildId { get; init; }
public required string MatchMethod { get; init; } // buildid_catalog, fingerprint_match, range_match
public required decimal Confidence { get; init; }
public string? FixedVersion { get; init; }
public string? FixStatus { get; init; } // fixed, vulnerable, not_affected, wontfix
}
```
**Proof Segments**: The **Attestor** generates `binary_fingerprint_evidence` proof segments with DSSE signatures for each binary with vulnerability matches. Schema: `https://stellaops.dev/predicates/binary-fingerprint-evidence@v1`.
**UI Badges**: Scan results display status badges:
* **Backported & Safe** (green): Distro backported the fix
* **Affected & Reachable** (red): Vulnerable and in code path
* **Unknown** (gray): Could not determine status
**CLI Commands** (Sprint 20251226_014):
* `stella binary inspect <file>`: Extract identity (Build-ID, hashes, architecture)
* `stella binary lookup <build-id>`: Query vulnerabilities by Build-ID
* `stella binary fingerprint <file>`: Generate position-independent fingerprint
**F) Attestation & SBOM bind (optional)**
* For each **file hash** or **binary hash**, query local cache of **Rekor v2** indices; if an SBOM attestation is found for **exact hash**, bind it to the component (origin=`attested`).
* For the **image** digest, likewise bind SBOM attestations (build‑time referrers).
* For the **image** digest, likewise bind SBOM attestations (build-time referrers).
### 5.4 Component normalization (exact only)