# 1) What is StellaOps?

**StellaOps** an open, sovereign, modular container-security toolkit built for high-speed, offline operation, released under AGPL-3.0-or-later.

It follows an SBOM-first model—analyzing each container layer or ingesting existing CycloneDX/SPDX SBOMs, then enriching them with vulnerability, licence, secret-leak, and misconfiguration data to produce cryptographically signed reports.

Vulnerability detection maps OS and language dependencies to sources such as NVD, GHSA, OSV, ENISA.
Secrets sweep flags exposed credentials or keys in files or environment variables.
Licence audit identifies potential conflicts, especially copyleft obligations.
Misconfiguration checks detect unsafe Dockerfile patterns (root user, latest tags, permissive modes).
Provenance features include in-toto/SLSA attestations signed with cosign for supply-chain trust.

| Guiding principle | What it means for Concelier |
|-------------------|---------------------------|
| **SBOM-first ingest** | Prefer signed SBOMs or reproducible layer diffs before falling back to raw scraping; connectors treat source docs as provenance, never as mutable truth. |
| **Deterministic outputs** | Same inputs yield identical canonical advisories and exported JSON/Trivy DB artefacts; merge hashes and export manifests are reproducible across machines. |
| **Restart-time plug-ins only** | Connector/exporter plug-ins load at service start, keeping runtime sandboxing simple and avoiding hot-patch attack surface. |
| **Sovereign/offline-first** | No mandatory outbound calls beyond allow-listed advisories; Offline Kit bundles Mongo snapshots and exporter artefacts for air-gapped installs. |
| **Operational transparency** | Every stage logs structured events (fetch, parse, merge, export) with correlation IDs so parallel agents can debug without shared state. |

Performance: warm scans < 5 s, cold scans < 30 s on a 4 vCPU runner.
Deployment: entirely SaaS-free, suitable for air-gapped or on-prem use through its Offline Kit.
Policy: anonymous users → 33 scans/day; verified → 333 /day; nearing 90 % quota triggers throttling but never full blocks.

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.<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.
- **Data**: MongoDB (canonical store and job/export state).
- **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 is contained by different modules installable via docker containers
- Concelier. Responsible for aggregation and delivery of vulnerability database
- Cli. Command line tool to unlock full potential - request database operations, install scanner, request scan, configure backend
- Backend. Configures and Manages scans
- UI. UI to access the backend (and scanners)
- Agent. Installable daemon that does the scanning
- Zastava. Realtime monitor for allowed (verified) installations.

## 4.1) Concelier
It is webservice based module that is responsible for aggregating vulnerabilities information from various sources, parsing and normalizing them into a canonical shape, merging and deduplicating the results in one place, with export capabilities to Json and TrivyDb. It supports init and resume for all of the sources, parse/normalize and merge/deduplication operations, plus export. Export supports delta exports—similarly to full and incremential database backups.

### 4.1.1) Usage
It supports operations to be started by cmd line:
# stella db [fetch|merge|export] [init|resume <point>]
or 
api available on https://db.stella-ops.org

### 4.1.2) Data flow (end‑to‑end)

1. **Fetch**: connectors request source windows with retries/backoff, persist raw documents with SHA256/ETag metadata.
2. **Parse & Normalize**: validate to DTOs (schema-checked), quarantine failures, normalize to canonical advisories (aliases, affected ranges with NEVRA/EVR/SemVer, references, provenance).
3. **Merge & Deduplicate**: enforce precedence, build/maintain alias graphs, compute deterministic hashes, and eliminate duplicates before persisting to MongoDB.
4. **Export**: JSON tree and/or Trivy DB; package and (optionally) push; write export state.

### 4.1.3) Architecture
For more information of the architecture see `./docs/ARCHITECTURE_CONCELIER.md`.

---

### 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-in-parallel 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 or 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 TODOS.md file. Always check the AGENTS.md in the relevant TODOS.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.

---