Implement code changes to enhance functionality and improve performance
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled

This commit is contained in:
2025-11-15 18:09:17 +02:00
parent 13e4b53dda
commit a3db0c959d
2 changed files with 4479 additions and 63 deletions

102
AGENTS.md
View File

@@ -2,7 +2,7 @@
**StellaOps** an next-gen and sovereign container-security toolkit built for high-speed, offline operation, released under AGPL-3.0-or-later.
Stella Ops is a self-hostable, sovereign container-security platform that makes proof—not promises—default. It binds every container digest to content-addressed SBOMs (SBOM 3.0.0 and CycloneDX 1.6), in-toto/DSSE attestations, and optional Sigstore Rekor transparency, then layers deterministic, replayable scanning with entry-trace and VEX-first decisioning. “Next-gen” means findings are reproducible and explainable, exploitability is modeled in OpenVEX and merged with lattice logic for stable outcomes, and the same workflow runs online or fully air-gapped. “Sovereign” means cryptographic and operational independence: bring-your-own trust roots, regional crypto readiness (eIDAS/FIPS/GOST/SM), offline bundles, and post-quantum-ready modes—so regulated orgs can comply without phoning home.
Stella Ops is a self-hostable, sovereign container-security platform that makes proof—not promises—default. It binds every container digest to content-addressed SBOMs (SBOM 3.0.1 and CycloneDX 1.6), in-toto/DSSE attestations, and optional Sigstore Rekor transparency, then layers deterministic, replayable scanning with entry-trace and VEX-first decisioning. “Next-gen” means findings are reproducible and explainable, exploitability is modeled in OpenVEX and merged with lattice logic for stable outcomes, and the same workflow runs online or fully air-gapped. “Sovereign” means cryptographic and operational independence: bring-your-own trust roots, regional crypto readiness (eIDAS/FIPS/GOST/SM), offline bundles, and post-quantum-ready modes—so regulated orgs can comply without phoning home.
Our principles and goals are simple: authenticity & integrity by default, provenance attached to digests, transparency for tamper-evidence, determinism & replay for audits, explainability engineers can act on, and exploitability over enumeration to cut noise. We minimize trust and blast radius with short-lived keys, least-privilege, and content-addressed caches; we stay air-gap friendly with mirrored feeds; and we keep governance honest with reviewable OPA/Rego policy gates and VEX-based waivers. The result is a platform that shortens time-to-truth, makes risk measurable, and lets you ship with confidence—anywhere, under any sovereignty requirement.
More documention is available ./docs/*.md files. Read `docs/README.md` to gather information about the available documentation. You could inquiry specific documents as your work requires it
@@ -12,21 +12,21 @@ More documention is available ./docs/*.md files. Read `docs/README.md` to gather
# 3) Practices
## 3.1) Naming
All modules are .NET projects based on .NET 10 (preview). Exclussion is the UI. It is based on Angular
All modules are .NET projects based on .NET 10. Exclussion is the UI. It is based on Angular.
All modules are contained by one or more projects. Each project goes in its dedicated folder. Each project starts with StellaOps.<ModuleName>. In case it is common for for all StellaOps modules it is library or plugin and it is named StellaOps.<LibraryOrPlugin>.
## 3.2) Key technologies & integrations
- **Runtime**: .NET 10 (`net10.0`) preview SDK; C# latest preview features. Any dependencies like Microsoft.* should strive to be closests version.
- **Runtime**: .NET 10 (`net10.0`); C# latest preview features. Any dependencies like Microsoft.* should strive to be closests version.
- **Nuget**: Try to re-use / cache nugets to /local-nugets
- **Data**: MongoDB (canonical store and job/export state). MongoDB driver version should be > 3.0
- **Observability**: structured logs, counters, and (optional) OpenTelemetry traces.
- **Ops posture**: offlinefirst, allowlist for remote hosts, strict schema validation, gated LLM fallback (only where explicitly configured).
## 3.3) Task workflow & guild coordination
- **Always sync state before coding.** When you pick up a task, immediately flip its status from `TODO` (or current state) to `DOING` in the relevant `docs/implplan/SPRINT_*.md` entry. Tasks must return to `TODO` if you step away, or `DONE` when you ship.
- **Always sync state before coding.** When you pick up a task, immediately flip its status from `TODO` (or current state) to `DOING` in the relevant `docs/implplan/NNN_*.md` entry. Tasks must return to `TODO` if you step away, or `DONE` when you ship.
- **Read the local agent charter first.** Every task directory must contain an `AGENTS.md` describing roles, expectations, and required prep docs. Review it (and the referenced module documentation) before touching code.
- **Mirror state across artefacts.** Sprint files are the single source of truth; every status update must be recorded in the matching `SPRINT_*.md`, plus context noted in commit/PR descriptions.
- **Mirror state across artefacts.** Sprint files are the single source of truth; every status update must be recorded in the matching `NNN_*.md`, plus context noted in commit/PR descriptions.
- **Document prerequisites.** If an `AGENTS.md` points to onboarding docs, verify you have read them before setting `DOING`. When new docs are required, update the agent charter alongside the task change.
- **Coordination**. Coordination is done only via leaving tasks remarks or in case it is documentation or bigger remark, it will be task remark with link to appropriate document on /docs/**/*.md
@@ -181,30 +181,15 @@ You main characteristics:
- You are autonomus - meaning that you will work for long time alone and achieve maximum without stopping for stupid questions
- You operate on the same directory where other agents will work. In case you need to work on a dependency directory referenced from an `AGENTS.md` or sprint entry you have to ask for confirmation first.
## 5.1) Type of contributions
- **BEBase (Platform & Pipeline)**
Owns DI, plugin host, job scheduler/coordinator, configuration binding, minimal API endpoints, and Mongo bootstrapping.
- **BEConnX (Connectors)**
One agent per source family (NVD, Red Hat, Ubuntu, Debian, SUSE, GHSA, OSV, PSIRTs, CERTs, KEV, ICS). Implements fetch/parse/map with incremental watermarks.
- **BEMerge (Canonical Merge & Dedupe)**
Identity graph, precedence policies, canonical JSON serializer, and deterministic hashing (`merge_event`).
- **BEExport (JSON & Trivy DB)**
Deterministic export trees, Trivy DB packaging, optional ORAS push, and offline bundle.
- **QA (Validation & Observability)**
Schema tests, fixture goldens, determinism checks, metrics/logs/traces, e2e reproducibility runs.
- **DevEx/Docs**
Maintains this agent framework, templates, and perdirectory guides; assists parallelization and reviews.
## 5.2) Work rules (important)
- **Directory ownership**: Each agent works **only inside its module directory**. Crossmodule edits require a brief handshake in issues/PR description.
- **Scoping**: Use each modules `AGENTS.md` and referenced sprint entries to plan; autonomous agents must read `src/AGENTS.md` and the module docs before acting.
- **Determinism**: Sort keys, normalize timestamps to UTC ISO8601, avoid nondeterministic data in exports and tests.
- **Scoping**: Use each modules `AGENTS.md` that is contained in the modules directory. The directory is referenced sprint;
- **Determinism**: Sort keys, normalize timestamps to UTC ISO8601, avoid nondeterministic data in exports and tests. Use immutable JSON (NDJSON)
- **Status tracking**: Update your modules sprint entry as you progress (TODO → DOING → DONE/BLOCKED). Before starting work ensure the sprint row is set to DOING; when pausing or shipping, update the same entry accordingly.
- **Coordination**: If a task is blocked on another team, update the relevant sprint entry (and add new ones if needed) describing the dependency. When scope or requirements or rules change, update the sprint doc plus any referenced documentation accordingly.
- **Sprint synchronization**: When given a task, locate the corresponding sprint file `docs/implplan/SPRINT_*.md`, confirm its state there, and keep that entry updated. Always check the nearby `AGENTS.md` for context.
- **Sprint synchronization**: When given a task, locate the corresponding sprint file `docs/implplan/NNN_*.md`, confirm its state there, and keep that entry updated. Always check the nearby `AGENTS.md` for context.
- **Tests**: Add/extend fixtures and unit tests per change; never regress determinism or precedence.
- **Test layout**: Use module-specific projects in `StellaOps.Concelier.<Component>.Tests`; shared fixtures/harnesses live in `StellaOps.Concelier.Testing`.
- **Execution autonomous**: In case you need to continue with more than one options just continue sequentially, unless the continue requires design decision.
@@ -227,46 +212,37 @@ You main characteristics:
## 6) Implementation Planning Overview
The implementation plan lives under `docs/implplan`. Follow these conventions whenever you touch sprint artefacts.
The sprnts documentations lives under `docs/implplan/SPRINT_*.md`. Each sprint must follow this template:
```md
# Sprint <ID> · <Stream/Topic>
- **Numbering & concurrency**
- Sprint files use the pattern `SPRINT_<decade><unit>_<topic>.md`.
- The **decade** (110s, 120s, …) identifies a delivery stream. Streams can execute in parallel.
- Numbers inside the same decade (e.g. `110``119`) **must not depend on each other**; they are intentionally concurrency-safe once upstream decades have landed.
- Multi-phase work keeps the decade and adds suffixes (`_i`, `_ii`, …) while preserving the no-intra-decade-dependency rule.
- **Required sections per sprint file**
1. `## Topic & Scope`
2. `## Dependencies & Concurrency`
3. `## Documentation Prerequisites`
4. `## Task Board` (single table with `Task ID`, `Status`, `Owner(s)`, `Dependencies`, `Notes`)
5. `## Execution Log`
6. `## Decisions & Risks`
7. `## Next Checkpoints`
- Optional deep dives go into `docs/implplan/archived/` or linked supplements to keep sprint files concise.
- **Updating sprint status**
- Flip the relevant row to `DOING` as soon as you start and keep the parent stream tracker in sync (e.g. Sprint 300 for Docs).
- Revert to `TODO` with a log entry if you pause mid-work.
- Mark `DONE (YYYY-MM-DD)` and capture validation evidence in the execution log when closing work.
- **Creating new sprints**
1. Copy `docs/implplan/templates/sprint-template.md` to `docs/implplan/SPRINT_<id>_<topic>.md`.
2. Update headings, scope, dependencies, and seed the initial task board.
3. Register the sprint in the stream index below and any parent tracker.
- **Stream index (update when scopes change)**
## Topic & Scope
- Summarise the sprint in 24 bullets that read like a short story (what outcomes are expected, why now).
- Call out the single owning directory (e.g., `src/Concelier/StellaOps.Concelier.Core`) and the evidence you expect to produce.
- **Working directory:** `<path/to/module>` (explicitly list the root path contributors must work in).
| Decade | Stream | Notes |
| --- | --- | --- |
| 110s | Ingestion & Evidence | Advisory AI, Concelier, Excititor, Mirror. |
| 120s | Policy & Reasoning | Findings ledger, policy evaluation, provenance. |
| 130s | Scanner Surface | Scanner surface hardening and deterministic compose. |
| 140s | Signals & Graph | Runtime signals, graph enrichment, Zastava. |
| 150s | Orchestration & Scheduling | Scheduler, orchestrator, automation packs. |
| 160s | Evidence & Export | Export Center, Evidence Locker, timeline indexer. |
| 170s | Notifications & Telemetry | Notify stack and telemetry improvements. |
| 180s | Replay Foundations | Deterministic replay primitives and evidence locker integration. |
| 200s | Experience SDKs & CLI | CLI, SDKs, dev portal, experience alignment. |
| 210s | UI & Web | Console SPA and web surfaces. |
| 300s | Documentation Process | Docs process ladder and per-module dossiers. |
| 400s | Reachability & Runtime Evidence | Runtime callgraph union and reachability evidence chain. |
| 500s | Ops & Air-gap | Offline modes, deployment, samples, sovereign crypto. |
## Dependencies & Concurrency
- Upstream sprints or artefacts that must land first.
- Confirm peers in the same `CC` decade remain independent so parallel execution is safe.
Keep this index synchronized any time new sprints are added or re-scoped.
## Documentation Prerequisites
- List onboarding docs, architecture dossiers, runbooks, ADRs, or experiment notes that contributors must read before flipping any task to `DOING`.
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | EXAMPLE-00-001 | TODO | Upstream contract or sprint | Guild · Team | Replace with the real backlog. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-11-15 | Sprint created; awaiting staffing. | Planning |
## Decisions & Risks
- Pending approvals, blocked schema reviews, or risks with a mitigation plan.
## Next Checkpoints
- Dated meetings, demos, or cross-team alignment calls with the accountable owners.
```
When sprint's task are all marked to DONE. Move the file to docs/impplan/archived.