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

feat: Enhance traceability and logging in Risk and Vulnerability clients

Browse Source 
- Implemented shared trace ID generation utility for Risk and Vulnerability clients, ensuring consistent trace headers across API calls.
- Updated RiskHttpClient and VulnerabilityHttpClient to utilize the new trace ID generation method.
- Added validation for artifact metadata in PackRun endpoints, ensuring all artifacts include a digest and positive size.
- Enhanced logging payloads in PackRun to include artifact digests and sizes.
- Created a utility for generating trace IDs, preferring crypto.randomUUID when available, with a fallback to a ULID-style string.
- Added unit tests to verify the presence of trace IDs in HTTP requests for VulnerabilityHttpClient.
- Documented query-hash metrics for Vuln Explorer, detailing hashing rules and logging filters to ensure compliance with privacy standards.
- Consolidated findings from late-November reviews into a comprehensive advisory for Scanner and SBOM/VEX areas, outlining remediation tracks and gaps.
This commit is contained in:
StellaOps Bot
2025-12-02 19:24:26 +02:00
parent 76ecea482e
commit acbb0ff637
20 changed files with 186 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
docs/product-advisories/31-Nov-2025 FINDINGS.md Normal file
View File

@@ -0,0 +1,54 @@
# 31-Nov-2025 – FINDINGS (Gap Consolidation)
## Purpose
This advisory consolidates late-November gap findings across Scanner, SBOM/VEX spine, competitor ingest, and other cross-cutting areas. It enumerates remediation tracks referenced by multiple sprints (for example SPRINT_0186_0001_0001_record_deterministic_execution.md) so implementation teams can scope work without waiting on scattered notes.
## Scope & Status
- **Created:** 2025-12-02 (retroactive to 2025-11-30 findings review)
- **Applies to:** Scanner, Sbomer, Policy/Authority, CLI/UI, Observability, Offline/Release
- **Priority sets included:** SC1–SC10 (Scanner), SP1–SP10 (SBOM/VEX spine), CM1–CM10 (Competitor ingest). Other gap families remain to be catalogued; see "Pending families" below.
## SC (Scanner Blueprint) Gaps — SC1–SC10
1. **SC1 — Standards convergence roadmap**: Land coordinated adoption of CVSS v4.0, CycloneDX 1.7 (incl. CBOM), and SLSA 1.2 in scanner outputs and docs.
2. **SC2 — CDX 1.7 + CBOM exports**: Produce deterministic CycloneDX 1.7 with CBOM sections and embedded evidence citations.
3. **SC3 — SLSA Source Track capture**: Capture source-trace fields (build provenance, source repo refs, build-id) in replay bundles.
4. **SC4 — Compatibility adapters**: Provide downgrade adapters (CVSS v4→v3.1, CDX 1.7→1.6, SLSA 1.2→1.0) with deterministic mapping tables.
5. **SC5 — Determinism CI for new formats**: Add CI checks/harnesses ensuring stable ordering/hashes for new schemas.
6. **SC6 — Binary/source evidence alignment**: Align binary evidence (build-id, symbols, patch oracle) with source SBOM/VEX outputs.
7. **SC7 — API/UI surfacing**: Expose the new metadata in surface API and console (filters, columns, download endpoints).
8. **SC8 — Baseline fixtures**: Curate fixture set covering v4 scoring, CBOM, SLSA 1.2, and evidence chips for regression.
9. **SC9 — Governance/approvals**: Define review gates/approvers for schema bumps and downgrade mappings.
10. **SC10 — Offline-kit parity**: Ensure offline kits ship frozen schemas, mappings, and fixtures for the above.
## SP (SBOM/VEX Spine) Gaps — SP1–SP10
1. **SP1 — Versioned API/DTO schemas**: Introduce versioned SBOM/VEX spine schemas with explicit migration rules.
2. **SP2 — Predicate/edge evidence requirements**: Mandate evidence fields per predicate/edge (e.g., reachability proof, package identity, build metadata).
3. **SP3 — Unknowns workflow contract**: Define lifecycle/SLA for Unknowns registry entries and their surfacing in spine APIs.
4. **SP4 — DSSE-signed bundle manifest**: Require DSSE-signed manifest including hash listings for every spine artifact.
5. **SP5 — Deterministic diff rules/fixtures**: Specify canonical diff rules and fixtures for SBOM/VEX deltas.
6. **SP6 — Feed snapshot freeze/staleness**: Codify snapshot/policy freshness guarantees and staleness thresholds.
7. **SP7 — Mandated DSSE per stage**: Enforce DSSE signatures per processing stage with Rekor/mirror policies (online/offline).
8. **SP8 — Policy lattice versioning**: Version the policy lattice and embed version refs into spine objects.
9. **SP9 — Performance/pagination limits**: Set deterministic pagination/ordering and perf budgets for API queries.
10. **SP10 — Crosswalk mappings**: Provide crosswalk between SBOM/VEX/graph/policy outputs for auditors and tooling.
## CM (Competitor Ingest) Gaps — CM1–CM10
1. **CM1 — Normalization adapters**: Harden ingest adapters for Syft/Trivy/Clair (SBOM + vuln scan) into StellaOps schemas.
2. **CM2 — Signature/provenance verification**: Verify external SBOM/scan signatures and provenance before acceptance; reject/flag unverifiable payloads.
3. **CM3 — Snapshot governance**: Enforce DB snapshot versioning, freshness SLAs, and rollback plans for imported feeds.
4. **CM4 — Anomaly regression tests**: Add regression tests for known ingest anomalies (schema drift, nullables, encoding, ordering).
5. **CM5 — Offline ingest kits**: Provide offline kits with DSSE-signed adapters, mappings, and fixtures for external SBOM/scan imports.
6. **CM6 — Fallback rules**: Define fallback hierarchy when external data is incomplete (prefer signed SBOM → unsigned SBOM → scan results → policy defaults).
7. **CM7 — Source transparency**: Persist source tool/version/hash metadata and expose it in APIs/exports.
8. **CM8 — Benchmark parity**: Maintain benchmark parity with upstream tool baselines (version-pinned, hash-logged runs).
9. **CM9 — Ecosystem coverage**: Track coverage per ecosystem (container, Java, Python, .NET, Go, OS packages) and gaps for ingest support.
10. **CM10 — Error resilience & retries**: Standardize retry/backoff/error classification for ingest pipeline; surface diagnostics deterministically.
## Pending Families (to be expanded)
The following gap families were referenced in November indices and still need detailed findings written out:
- CV1–CV10 (CVSS v4 receipts), CVM1–CVM10 (momentum), FC1–FC10 (SCA fixture gaps), OB1–OB10 (onboarding), IG1–IG10 (implementor guidance), RR1–RR10 (Rekor receipts), SK1–SK10 (standups), MI1–MI10 (UI micro-interactions), PVX1–PVX10 (Proof-linked VEX UI), TTE1–TTE10 (Time-to-Evidence), AR-EP1…AR-VB1 (archived advisories revival), BP1–BP10 (SBOM→VEX proof pipeline), UT1–UT10 (unknown heuristics), CE1–CE10 (evidence patterns), ET1–ET10 (ecosystem fixtures), RB1–RB10 (reachability fixtures), G1–G12 / RD1–RD10 (reachability benchmark/dataset), UN1–UN10 (unknowns registry), U1–U10 (decay), EX1–EX10 (explainability), VEX1–VEX10 (VEX claims), BR1–BR10 (binary reachability), VT1–VT10 (triage), PL1–PL10 (plugin arch), EB1–EB10 (evidence baseline), EC1–EC10 (export center), AT1–AT10 (automation), OK1–OK10 / RK1–RK10 / MS1–MS10 (offline/mirror/Rekor kits), TP1–TP10 (task packs), AU1–AU10 (auth), CL1–CL10 (CLI), OR1–OR10 (orchestrator), ZR1–ZR10 (Zastava), NR1–NR10 (Notify), GA1–GA10 (graph analytics), TO1–TO10 (telemetry), PS1–PS10 (policy), FL1–FL10 (ledger), CI1–CI10 (Concelier ingest).
Each pending family should be expanded in this document (or split into dedicated, linked supplements) with numbered findings, recommended evidence, and deterministic test/fixture expectations.
## Decision Trace
- This document was created to satisfy sprint and index references to “31-Nov-2025 FINDINGS.md” and unblock gap-remediation tasks across Scanner/SBOM/VEX and ingest tracks.