stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
10212d67c0dfa0dd849fd798c24502b773664749
git.stella-ops.org/docs/modules/vex-lens
History
master cef4cb2c5a Add support for ГОСТ Р 34.10 digital signatures 
- Implemented the GostKeyValue class for handling public key parameters in ГОСТ Р 34.10 digital signatures.
- Created the GostSignedXml class to manage XML signatures using ГОСТ 34.10, including methods for computing and checking signatures.
- Developed the GostSignedXmlImpl class to encapsulate the signature computation logic and public key retrieval.
- Added specific key value classes for ГОСТ Р 34.10-2001, ГОСТ Р 34.10-2012/256, and ГОСТ Р 34.10-2012/512 to support different signature algorithms.
- Ensured compatibility with existing XML signature standards while integrating ГОСТ cryptography.
2025-11-09 21:59:57 +02:00
..
AGENTS.md
Update AGENTS.md files across multiple modules to standardize task status update instructions and introduce a new document for Secret Leak Detection operations.
2025-11-05 11:58:32 +02:00
architecture.md
Add support for ГОСТ Р 34.10 digital signatures
2025-11-09 21:59:57 +02:00
implementation_plan.md
Add support for ГОСТ Р 34.10 digital signatures
2025-11-09 21:59:57 +02:00
README.md
Add support for ГОСТ Р 34.10 digital signatures
2025-11-09 21:59:57 +02:00

README.md

StellaOps VEX Consensus Lens

VEX Lens produces a deterministic, provenance-rich consensus view of VEX statements so downstream policy and exploration surfaces can trust what “affected” or “not affected” means per artifact. It separates raw ingestion (Excititor) from adjudication, weighs issuers cryptographically, and keeps conflicts transparent for auditors and tooling.

Scope & responsibilities

  • Normalise OpenVEX, CSAF VEX, and CycloneDX VEX documents from Excititor into lens-ready tuples without violating the Aggregation-Only Contract.
  • Apply issuer weights, signature verification results, freshness decay, and policy overrides to compute consensus and confidence for each (artifact, advisory) pair.
  • Emit consensus snapshots, conflict summaries, and DSSE attestations consumed by Policy Engine, Vulnerability Explorer, Advisory AI, and Task Runner workflows.
  • Provide simulation/export APIs and Offline Kit bundles so tenants can rehearse policy changes and mirror consensus data in air-gapped environments.

Architecture snapshot (Sprint 30 groundwork)

  • StellaOps.VexLens service & workers — orchestrate normalisation, trust weighting, lattice join, and persistence into vex_consensus, vex_consensus_history, and vex_conflict_queue collections.
  • Issuer Directory integration — maintains publisher metadata, keys, and trust tiers that feed weighting engines and revocation workflows.
  • Consensus APIs — /v1/vex/consensus, /v1/vex/conflicts, /v1/vex/trust/weights, and export streams with DSSE manifests for Offline Kit + Export Center.
  • Explainability traces — capture derived-from chains, conflicting issuers, and trust deltas to power UI drilldowns and CLI audits.
  • Recompute orchestration — Orchestrator jobs trigger recompute on Excititor deltas, issuer updates, or policy knob changes with deterministic ordering and SRM manifests.

Provenance-aware trust weighting (new)

  • Connector metadata contract. Excititor connectors now emit vex.provenance.* fields (provider id/name/kind, trust.weight, trust.tier, human-readable trust.note, cosign.*, and ordered pgp.fingerprints). VEX Lens must ingest these keys verbatim so the trust engine can reason about issuer pedigree without hitting external registries for every statement.
  • Weight calculation. Lens uses the supplied trust.weight as the baseline score, then multiplies by freshness decay and justification scope multipliers. Missing weights default to the Issuer Directory profile, but connector-provided values take precedence so Ubuntu/SUSE mirror feeds can tune their relative influence.
  • Integrity hints. Presence of vex.provenance.cosign.* or pgp.fingerprints toggles signature-policy shortcuts: if Lens sees a statement whose provenance indicates cosign keyless mode plus Rekor URI, it can skip redundant issuer lookups and apply the “cryptographically verified” confidence tier immediately.
  • Policy exposure. Consensus APIs surface the original provenance payload inside each sources[] entry so Policy Engine, Advisory AI, and Console can explain why a lower-tier issuer lost a conflict (e.g., different trust.tier or missing fingerprints). See the updated payload reference in docs/vex/consensus-json.md.

Current workstreams (Q4 2025)

  • VEXLENS-30-001..004 — build normalisation pipeline, product mapping library, and trust weighting engine (in progress; dependencies captured in src/VexLens/StellaOps.VexLens/TASKS.md).
  • VEXLENS-30-005..007 — expose consensus APIs and export flows, aligning docs with future /docs/vex/consensus-*.md deliverables.
  • DOCS-VEX-30-001..004 — broader documentation set (overview, algorithm, API) tracked in docs/TASKS.md; update this README again once those artefacts merge.

Integrations & dependencies

  • Excititor supplies signature-verified VEX observations and issuer hints.
  • Policy Engine consumes consensus verdicts for suppression/waiver logic and exposes trust controls to operators.
  • Vulnerability Explorer & Advisory AI render consensus badges, conflicts, and rationale in investigative workflows.
  • Orchestrator & Scheduler run backfills, recomputes, and incident routing driven by Lens change streams.
  • Notify / Task Runner receive conflict and override events for operator actions once notification bridges ship.

Data & observability

  • Collections: vex_consensus, vex_consensus_history, vex_conflict_queue, plus issuer registry tables managed with tenant isolation and deterministic indexes.
  • Metrics: vex_consensus_conflicts_total, vex_consensus_latency_seconds, vex_consensus_recompute_seconds{reason}, signature failure counters.
  • Traces/logs: consensus.group, consensus.join, consensus.persist spans with correlation IDs and issuer details; structured logs capture trust adjustments and reconciliation outcomes.
  • Offline bundles include consensus.jsonl, conflicts.jsonl, manifest + DSSE signatures, enabling mirror deployments and replay validation.

Key docs & references

  • architecture.md — implementation-ready blueprint covering inputs, algorithm, APIs, storage, observability, and exports.
  • implementation_plan.md — phased delivery roadmap and acceptance criteria.
  • ../../vex/aggregation.md — Aggregation-Only Contract boundaries for VEX ingestion and downstream consumers.
  • Sprint tracking in docs/implplan/SPRINT_200_documentation_process.md and module engineering tasks in src/VexLens/StellaOps.VexLens/TASKS.md.

Epic alignment

  • Epic 7 — VEX Consensus Lens: deterministic VEX adjudication, issuer directory, consensus exports.
  • Related epics: Issuer Directory (keys & trust), Vulnerability Explorer overlays, Policy trust tuning.