stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
e923880694b66a819714782b43fed2b0d577a95b
git.stella-ops.org/docs/modules/scanner/design/competitor-ingest-normalization.md
StellaOps Bot e923880694
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Export Center CI / export-ci (push) Has been cancelled
Details
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
Details
feat: Add DigestUpsertRequest and LockEntity models 
- Introduced DigestUpsertRequest for handling digest upsert requests with properties like ChannelId, Recipient, DigestKey, Events, and CollectUntil.
- Created LockEntity to represent a lightweight distributed lock entry with properties such as Id, TenantId, Resource, Owner, ExpiresAt, and CreatedAt.

feat: Implement ILockRepository interface and LockRepository class

- Defined ILockRepository interface with methods for acquiring and releasing locks.
- Implemented LockRepository class with methods to try acquiring a lock and releasing it, using SQL for upsert operations.

feat: Add SurfaceManifestPointer record for manifest pointers

- Introduced SurfaceManifestPointer to represent a minimal pointer to a Surface.FS manifest associated with an image digest.

feat: Create PolicySimulationInputLock and related validation logic

- Added PolicySimulationInputLock record to describe policy simulation inputs and expected digests.
- Implemented validation logic for policy simulation inputs, including checks for digest drift and shadow mode requirements.

test: Add unit tests for ReplayVerificationService and ReplayVerifier

- Created ReplayVerificationServiceTests to validate the behavior of the ReplayVerificationService under various scenarios.
- Developed ReplayVerifierTests to ensure the correctness of the ReplayVerifier logic.

test: Implement PolicySimulationInputLockValidatorTests

- Added tests for PolicySimulationInputLockValidator to verify the validation logic against expected inputs and conditions.

chore: Add cosign key example and signing scripts

- Included a placeholder cosign key example for development purposes.
- Added a script for signing Signals artifacts using cosign with support for both v2 and v3.

chore: Create script for uploading evidence to the evidence locker

- Developed a script to upload evidence to the evidence locker, ensuring required environment variables are set.
2025-12-03 07:51:50 +02:00

4.5 KiB
Raw Blame History

Competitor Ingest Normalization (CM1)

Purpose

Define how external SBOM/scan outputs (Syft, Trivy, Clair) are normalized into StellaOps schemas with deterministic ordering, provenance checks, and offline-ready adapters. Covers CM1–CM10 in the 31-Nov-2025 findings advisory.

Scope

  • Import pipeline for external SBOM + vulnerability scan payloads.
  • Adapter mappings, validation, provenance/signature verification, and fallback rules.
  • Offline ingest kits (adapters + fixtures) and regression tests.

Deliverables (CM tasks)

  • CM1: Mapping tables per tool → StellaOps SBOM/scan schema; required/optional fields; deterministic sort rules.
  • CM2: Signature/provenance verification policy (acceptable algorithms, trust roots, failure modes).
  • CM3: Snapshot governance: versioning, freshness SLA, rollback plan for imported feeds.
  • CM4: Anomaly regression suite (schema drift, nullables, encoding, ordering). Golden fixtures + hashes.
  • CM5: Offline ingest kit: DSSE-signed adapters/mappings/fixtures with tool versions and hashes.
  • CM6: Fallback hierarchy when data incomplete (signed SBOM → unsigned SBOM → scan → defaults) with explicit decision trace.
  • CM7: Source transparency fields (tool name/version/hash, build metadata) persisted and surfaced.
  • CM8: Benchmark parity plan with upstream tools (pinned versions, hash-logged runs).
  • CM9: Coverage matrix by ecosystem; gap tracker.
  • CM10: Retry/backoff/error taxonomy and deterministic diagnostics.

Determinism & Validation

  • Adapters must sort components and vulnerabilities deterministically (locale-invariant, stable keys).
  • All mapping rules and fixtures carry BLAKE3/SHA256 hashes; adapters are pure functions (no network).
  • Signature verification rejects unverifiable payloads; logs reason codes; can run offline using bundled trust roots.

Adapter mapping skeleton (CM1)

  • Tool coverage v0.1: Syft 1.0.x, Trivy 0.50.x, Clair 6.x (pin exact versions in fixtures).
  • Mapping tables (CSV, checked in under docs/modules/scanner/fixtures/competitor-adapters/):
    • component: external fields → name, version, purl, type, hashes, licenses, evidenceRef.
    • vulnerability: id, source, severity (normalised), cvss (score/vector), fixVersions, evidenceRef.
    • metadata: tool name/version/hash, scan timestamp (UTC), data source.
  • Sorting: components by purl → name → version; vulns by id → source → severityScore desc → cvss.vector.

Verification policy (CM2)

  • Acceptable signatures: DSSE/COSE/JWS with SHA256/Ed25519/ECDSA; trust roots bundled in offline kit.
  • Provenance check: require signer identity + hash match; if missing, mark provenance = unknown and apply fallback (CM6).

Snapshot governance (CM3)

  • Freshness budget: max age 7 days from scanTimestamp; reject older unless override flag set (logged).
  • Versioning: stored as snapshot_version (semver) and source_tool_hash; rollback plan requires prior snapshot hash.

Regression + fixtures (CM4/CM5)

  • Fixtures under docs/modules/scanner/fixtures/competitor-adapters/fixtures/ with golden hashes (BLAKE3/SHA256) and expected normalized output.
  • CI step runs adapter → normalized → hash compare; offline, no network.

Fallback hierarchy (CM6)

  1. Signed SBOM w/ valid provenance → accepted.
  2. Unsigned SBOM → accepted with provenance=unknown, warnings emitted.
  3. Scan-only results → accepted with degraded confidence; policy lattice may penalize.
  4. If all absent: reject with reason code no_evidence.

Transparency & coverage (CM7–CM9)

  • Persist: source.tool, source.version, source.hash, adapter.version, normalized_hash.
  • Coverage matrix maintained in docs/modules/scanner/fixtures/competitor-adapters/coverage.csv (ecosystem yes/no, notes).
  • Bench parity (CM8): pin upstream versions; store run hashes/logs in fixtures folder.

Error taxonomy (CM10)

  • Retryable: network/unavailable (should not occur in offline mode), rate-limit, transient IO.
  • Non-retryable: signature_invalid, schema_invalid, unsupported_version, no_evidence.
  • All errors must carry deterministic reason codes and be logged in normalized output metadata.

Open Items

  • Decide minimal evidence set for accepting unsigned SBOMs (intermediate level before scan-only fallback).
  • Confirm which hash (BLAKE3/SHA256) is canonical for adapter outputs.

Links

  • Sprint: docs/implplan/SPRINT_0186_0001_0001_record_deterministic_execution.md (CM1–CM10)
  • Advisory: docs/product-advisories/31-Nov-2025 FINDINGS.md