git.stella-ops.org/AGENTS.md

1) What is StellaOps?

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.

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

---

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 contained by one or more projects. Each project goes in its dedicated folder. Each project starts with StellaOps.. In case it is common for for all StellaOps modules it is library or plugin and it is named StellaOps..

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.
• 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: offline‑first, 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.
• 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.
• 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

4) Modules

StellaOps ships as containerised building blocks; each module owns a clear boundary and has its own code folder, deployable image, and deep-dive architecture dossier.

Module	Primary path(s)	Key doc
Authority	src/Authority/StellaOps.Authority src/Authority/StellaOps.Authority.Plugin.*	docs/modules/authority/architecture.md
Signer	src/Signer/StellaOps.Signer	docs/modules/signer/architecture.md
Attestor	src/Attestor/StellaOps.Attestor src/Attestor/StellaOps.Attestor.Verify	docs/modules/attestor/architecture.md
Concelier	src/Concelier/StellaOps.Concelier.WebService src/Concelier/__Libraries/StellaOps.Concelier.*	docs/modules/concelier/architecture.md
Excititor	src/Excititor/StellaOps.Excititor.WebService src/Excititor/__Libraries/StellaOps.Excititor.*	docs/modules/excititor/architecture.md
Policy Engine	src/Policy/StellaOps.Policy.Engine src/Policy/__Libraries/StellaOps.Policy.*	docs/modules/policy/architecture.md
Scanner	src/Scanner/StellaOps.Scanner.WebService src/Scanner/StellaOps.Scanner.Worker src/Scanner/__Libraries/StellaOps.Scanner.*	docs/modules/scanner/architecture.md
Scheduler	src/Scheduler/StellaOps.Scheduler.WebService src/Scheduler/StellaOps.Scheduler.Worker	docs/modules/scheduler/architecture.md
CLI	src/Cli/StellaOps.Cli src/Cli/StellaOps.Cli.Core src/Cli/StellaOps.Cli.Plugins.*	docs/modules/cli/architecture.md
UI / Console	src/UI/StellaOps.UI	docs/modules/ui/architecture.md
Notify	src/Notify/StellaOps.Notify.WebService src/Notify/StellaOps.Notify.Worker	docs/modules/notify/architecture.md
Export Center	src/ExportCenter/StellaOps.ExportCenter.WebService src/ExportCenter/StellaOps.ExportCenter.Worker	docs/modules/export-center/architecture.md
Registry Token Service	src/Registry/StellaOps.Registry.TokenService src/Registry/__Tests/StellaOps.Registry.TokenService.Tests	docs/modules/registry/architecture.md
Advisory AI	src/AdvisoryAI/StellaOps.AdvisoryAI	docs/modules/advisory-ai/architecture.md
Orchestrator	src/Orchestrator/StellaOps.Orchestrator	docs/modules/orchestrator/architecture.md
Vulnerability Explorer	src/VulnExplorer/StellaOps.VulnExplorer.Api	docs/modules/vuln-explorer/architecture.md
VEX Lens	src/VexLens/StellaOps.VexLens	docs/modules/vex-lens/architecture.md
Graph Explorer	src/Graph/StellaOps.Graph.Api src/Graph/StellaOps.Graph.Indexer	docs/modules/graph/architecture.md
Telemetry Stack	ops/devops/telemetry	docs/modules/telemetry/architecture.md
DevOps / Release	ops/devops	docs/modules/devops/architecture.md
Platform	(cross-cutting docs)	docs/modules/platform/architecture-overview.md
CI Recipes	(pipeline templates)	docs/modules/ci/architecture.md
Zastava	src/Zastava/StellaOps.Zastava.Observer src/Zastava/StellaOps.Zastava.Webhook src/Zastava/StellaOps.Zastava.Core	docs/modules/zastava/architecture.md

4.1 Module cheat sheet

Authority

• Path: src/Authority/StellaOps.Authority, plugins in src/Authority/StellaOps.Authority.Plugin.*.
• Docs: docs/modules/authority/architecture.md.
• Responsibilities: Issues short-lived, sender-constrained OpToks (DPoP/mTLS) for services, CLI, and UI; exposes OIDC discovery, device-code, and auth-code flows.
• Key traits: Ed25519/ES256 signing with JWKS rotation, tenant-aware scopes, stateless JWT validation, optional introspection, and structured audit trails.

Signer

• Path: src/Signer/StellaOps.Signer.
• Docs: docs/modules/signer/architecture.md.
• Responsibilities: Authenticates callers, enforces Proof-of-Entitlement, verifies scanner release signatures, and returns DSSE bundles for SBOMs and reports.
• Key traits: Supports keyless (Fulcio) and keyful (KMS/HSM) signing, applies plan quotas, stores audit trails, and delegates Rekor logging to the Attestor.

Attestor

• Path: src/Attestor/StellaOps.Attestor, proof helpers in src/Attestor/StellaOps.Attestor.Verify.
• Docs: docs/modules/attestor/architecture.md.
• Responsibilities: Submits DSSE bundles to Rekor v2, caches {uuid, index, proof}, and serves verification bundles to Scanner, UI, CLI, and Export Center.
• Key traits: mTLS + OpTok enforcement for Signer-only submissions, Mongo/Redis idempotency, optional DSSE archive mirroring, and resilient retry/backoff.

Concelier

• Path: src/Concelier/StellaOps.Concelier.WebService with connectors/exporters under src/Concelier/__Libraries/StellaOps.Concelier.*.
• Docs: docs/modules/concelier/architecture.md.
• Responsibilities: Applies the Aggregation-Only Contract to ingest advisories, produce immutable observations, correlate linksets, and publish deterministic exports.
• Key traits: Restart-time connectors/exporters, Mongo-backed scheduling, canonical JSON/Trivy outputs, Offline Kit parity, and hash-stable manifests.

Excititor

• Path: src/Excititor/StellaOps.Excititor.WebService, connectors/adapters in src/Excititor/__Libraries/StellaOps.Excititor.*.
• Docs: docs/modules/excititor/architecture.md.
• Responsibilities: Normalises VEX statements into observations, builds provenance-rich linksets, and surfaces consensus/conflicts for policy suppression.
• Key traits: Aggregation-only guardrails, restart-time plug-ins, Mongo persistence, deterministic exports, and Offline Kit-ready bundles.

Policy Engine

• Path: src/Policy/StellaOps.Policy.Engine, shared libraries under src/Policy/__Libraries/StellaOps.Policy.*.
• Docs: docs/modules/policy/architecture.md.
• Responsibilities: Evaluates stella-dsl@1 policies, joins SBOM/advisory/VEX evidence, materialises effective findings, and emits explain traces.
• Key traits: Deterministic evaluation (no wall clock), change-stream driven increments, simulation endpoints, and Authority-scoped tenancy/RBAC enforcement.

Scanner.WebService

• Path: src/Scanner/StellaOps.Scanner.WebService.
• Docs: docs/modules/scanner/architecture.md.
• Responsibilities: Hosts scan/diff/export APIs, enqueues work, serves SBOM and diff artifacts, and publishes DSSE-ready report metadata.
• Key traits: Minimal APIs with Redis/NATS queue clients, RustFS artifact integration, BOM-index lookups, and DSSE hand-off to Signer/Attestor.

Scanner.Worker

• Path: src/Scanner/StellaOps.Scanner.Worker with analyzers/caches in src/Scanner/__Libraries/StellaOps.Scanner.*.
• Docs: docs/modules/scanner/architecture.md.
• Responsibilities: Runs deterministic OS/language/native analyzers per layer, composes inventory and usage SBOM fragments, and streams them back to the catalog.
• Key traits: Layer/file CAS caching, restart-time analyzer plug-ins under plugins/scanner/**, bounded retries with lease renewals, and DSSE-ready outputs.

Scheduler

• Path: src/Scheduler/StellaOps.Scheduler.WebService, src/Scheduler/StellaOps.Scheduler.Worker.
• Docs: docs/modules/scheduler/architecture.md.
• Responsibilities: Detects advisory/VEX deltas, selects impacted assets via BOM index, and schedules analysis-only runs toward Scanner and Policy Engine.
• Key traits: Mongo impact cursors, Redis/NATS orchestration, webhook fan-out (Policy/Notify/Runtime), and deterministic evaluation windows.

CLI

• Path: src/Cli/StellaOps.Cli, helpers in src/Cli/StellaOps.Cli.Core, plug-ins in src/Cli/StellaOps.Cli.Plugins.*.
• Docs: docs/modules/cli/architecture.md.
• Responsibilities: Provides deterministic verbs for scan/diff/export/report, Buildx SBOM orchestration, policy/VEX administration, and offline kit workflows.
• Key traits: Native AOT binaries, device-code/client-credential login with DPoP storage, golden-output tests, and restart-time plug-in manifests in plugins/cli/**.

UI

• Path: src/UI/StellaOps.UI.
• Docs: docs/modules/ui/architecture.md.
• Responsibilities: Angular SPA for scans, policy authoring, VEX evidence exploration, runtime posture, and admin tooling via backend APIs.
• Key traits: Angular Signals with @ngrx/signals, typed API clients handling DPoP + SSE, Tailwind theming, and immutable content-hashed bundles.

Notify

• Path: src/Notify/StellaOps.Notify.WebService, src/Notify/StellaOps.Notify.Worker, connectors in src/Notify/__Libraries.
• Docs: docs/modules/notify/architecture.md.
• Responsibilities: Evaluates notification rules on platform events, renders channel-specific payloads, and delivers messages with throttling/digests.
• Key traits: Tenant-scoped rule engine, idempotent delivery queues, secrets referenced rather than stored, and comprehensive audit/metrics coverage.

Export Center

• Path: src/ExportCenter/StellaOps.ExportCenter.WebService, src/ExportCenter/StellaOps.ExportCenter.Worker, adapters in src/ExportCenter/StellaOps.ExportCenter.*.
• Docs: docs/modules/export-center/architecture.md.
• Responsibilities: Packages reproducible evidence bundles (JSON, Trivy, mirror) with provenance, signing, and distribution manifests for offline or mirror deployments.
• Key traits: Profile-driven exports, Orchestrator-backed job leases, Mongo/object storage staging, and cosign-compatible provenance/signature emission.

Registry Token Service

• Path: src/Registry/StellaOps.Registry.TokenService, with integration tests in src/Registry/__Tests/StellaOps.Registry.TokenService.Tests.
• Docs: docs/modules/registry/operations/token-service.md.
• Responsibilities: Issues scoped pull tokens for container/image registries, enforces licence/plan constraints, and publishes audit telemetry for token usage.
• Key traits: Authority-issued OpTok validation, Mongo-backed issuance ledger, deterministic checksum manifests for Offline Kit bundles, and emergency revoke/rotation tooling.

Zastava

• Path: src/Zastava/StellaOps.Zastava.Observer, src/Zastava/StellaOps.Zastava.Webhook, shared contracts in src/Zastava/StellaOps.Zastava.Core.
• Docs: docs/modules/zastava/architecture.md.
• Responsibilities: Observes running workloads, emits runtime posture events, and enforces admission-time policy (signed images, SBOM availability, policy verdict).
• Key traits: Authority-issued OpToks with DPoP/mTLS, ND-JSON batching with local buffering, delta-scan triggers on drift, and Kubernetes webhook enforcement.

---

4.1.4) Glossary (quick)

• OVAL — Vendor/distro security definition format; authoritative for OS packages.
• NEVRA / EVR — RPM and Debian version semantics for OS packages.
• PURL / SemVer — Coordinates and version semantics for OSS ecosystems.
• KEV — Known Exploited Vulnerabilities (flag only).

---

5) Your role as StellaOps contributor

You acting as information technology engineer that will take different type of roles in goal achieving StellaOps production implementation In order you to work you must be supplied with a directory that contains an AGENTS.md file and references to the owning docs/implplan/SPRINT_*.md entries. Those documents capture the role, scope, and tasks you will have.

Boundaries:

• You operate only in the working directories I gave you, unless there is dependencies that makes you to work on dependency in shared directory. Then you ask for confirmation.

You main characteristics:

• Keep endpoints small, deterministic, and cancellation-aware.
• Improve logs/metrics as per tasks.
• Update the owning sprint entry when moving tasks forward.
• When you are done with all task you state explicitly you are done.
• Impersonate the role described on working directory AGENTS.md you will read, if role is not available - take role of the CTO of the StellaOps in early stages.
• You always strive for best practices
• You always strive for re-usability
• When in doubt of design decision - you ask then act
• 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

• BE‑Base (Platform & Pipeline)
  Owns DI, plugin host, job scheduler/coordinator, configuration binding, minimal API endpoints, and Mongo bootstrapping.
• BE‑Conn‑X (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.
• BE‑Merge (Canonical Merge & Dedupe)
  Identity graph, precedence policies, canonical JSON serializer, and deterministic hashing (merge_event).
• BE‑Export (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 per‑directory guides; assists parallelization and reviews.

5.2) Work rules (important)

• Directory ownership: Each agent works only inside its module directory. Cross‑module edits require a brief handshake in issues/PR description.
• Scoping: Use each module’s 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 ISO‑8601, avoid non‑deterministic data in exports and tests.
• Status tracking: Update your module’s 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.
• 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.
• Additional references: When a task mentions historical epics, consult the corresponding module guides or domain playbooks under docs/modules/**, docs/api/, docs/risk/, or docs/airgap/ for the latest specification.

---

Required Reading

• docs/README.md
• docs/07_HIGH_LEVEL_ARCHITECTURE.md
• docs/modules/platform/architecture-overview.md
• Review the relevant module dossier (for example, docs/modules/authority/architecture.md) before editing component-specific content.

Working Agreement

• 1. Update task status to DOING/DONE inside the corresponding docs/implplan/SPRINT_*.md entry when you start or finish work.
• 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
• 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
• 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
• 5. Revert to TODO if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

6) Implementation Planning Overview

The implementation plan lives under docs/implplan. Follow these conventions whenever you touch sprint artefacts.

• 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)

  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.

Keep this index synchronized any time new sprints are added or re-scoped.