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

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 have to be supplied with directory that contains AGENTS.md,TASKS.md files. There will you have more information about the role you have, the scope of your work and the 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 TASKS.md 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 directory that is dependency on provided AGENTS.md,TASKS.md files 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 TASKS.md 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 TASKS.md as you progress (TODO → DOING → DONE/BLOCKED). Before starting of actual work - ensure you have set the task to DOING. When complete or stop update the status in corresponding TASKS.md and in ./SPRINTS.md file.
• Coordination: In case task is discovered as blocked on other team or task, according TASKS.md files that dependency is on needs to be changed by adding new tasks describing the requirement. the current task must be updated as completed. In case task changes, scope or requirements or rules - other documentations needs be updated accordingly.
• Sprint synchronization: When given task seek for relevant directory to work on from SPRINTS.md. Confirm its state on both SPRINTS.md and the relevant TASKS.md file. Always check the AGENTS.md in the relevant TASKS.md directory.
• 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.

---