stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
75c2bcafced8b7a9e4e442cd10af3972f5788d35
git.stella-ops.org/docs/modules/vex-lens
History
master 75c2bcafce
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Add LDAP Distinguished Name Helper and Credential Audit Context 
- Implemented LdapDistinguishedNameHelper for escaping RDN and filter values.
- Created AuthorityCredentialAuditContext and IAuthorityCredentialAuditContextAccessor for managing credential audit context.
- Developed StandardCredentialAuditLogger with tests for success, failure, and lockout events.
- Introduced AuthorityAuditSink for persisting audit records with structured logging.
- Added CryptoPro related classes for certificate resolution and signing operations.
2025-11-09 12:21:38 +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
Align AOC tasks for Excititor and Concelier
2025-10-31 18:50:15 +02:00
implementation_plan.md
feat: Implement vulnerability token signing and verification utilities
2025-11-03 10:04:10 +02:00
README.md
Add tenant isolation smoke test for telemetry stack
2025-11-05 15:09:54 +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.

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.