248 lines
20 KiB
Markdown
248 lines
20 KiB
Markdown
# 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.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
|
||
|
||
---
|
||
|
||
# 3) Practices
|
||
|
||
## 3.1) Naming
|
||
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`); 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/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 `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
|
||
|
||
# 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`<br>`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`<br>`src/Attestor/StellaOps.Attestor.Verify` | `docs/modules/attestor/architecture.md` |
|
||
| Concelier | `src/Concelier/StellaOps.Concelier.WebService`<br>`src/Concelier/__Libraries/StellaOps.Concelier.*` | `docs/modules/concelier/architecture.md` |
|
||
| Excititor | `src/Excititor/StellaOps.Excititor.WebService`<br>`src/Excititor/__Libraries/StellaOps.Excititor.*` | `docs/modules/excititor/architecture.md` |
|
||
| Policy Engine | `src/Policy/StellaOps.Policy.Engine`<br>`src/Policy/__Libraries/StellaOps.Policy.*` | `docs/modules/policy/architecture.md` |
|
||
| Scanner | `src/Scanner/StellaOps.Scanner.WebService`<br>`src/Scanner/StellaOps.Scanner.Worker`<br>`src/Scanner/__Libraries/StellaOps.Scanner.*` | `docs/modules/scanner/architecture.md` |
|
||
| Scheduler | `src/Scheduler/StellaOps.Scheduler.WebService`<br>`src/Scheduler/StellaOps.Scheduler.Worker` | `docs/modules/scheduler/architecture.md` |
|
||
| CLI | `src/Cli/StellaOps.Cli`<br>`src/Cli/StellaOps.Cli.Core`<br>`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`<br>`src/Notify/StellaOps.Notify.Worker` | `docs/modules/notify/architecture.md` |
|
||
| Export Center | `src/ExportCenter/StellaOps.ExportCenter.WebService`<br>`src/ExportCenter/StellaOps.ExportCenter.Worker` | `docs/modules/export-center/architecture.md` |
|
||
| Registry Token Service | `src/Registry/StellaOps.Registry.TokenService`<br>`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`<br>`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`<br>`src/Zastava/StellaOps.Zastava.Webhook`<br>`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.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` that is contained in the modules directory. The directory is referenced sprint;
|
||
- **Determinism**: Sort keys, normalize timestamps to UTC ISO‑8601, avoid non‑deterministic data in exports and tests. Use immutable JSON (NDJSON)
|
||
- **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/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.
|
||
- **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 sprnts documentations lives under `docs/implplan/SPRINT_*.md`. Each sprint must follow this template:
|
||
```md
|
||
# Sprint <ID> · <Stream/Topic>
|
||
|
||
## Topic & Scope
|
||
- Summarise the sprint in 2–4 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).
|
||
|
||
## Dependencies & Concurrency
|
||
- Upstream sprints or artefacts that must land first.
|
||
- Confirm peers in the same `CC` decade remain independent so parallel execution is safe.
|
||
|
||
## 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. |