Initial commit (history squashed)

docs/01_WHAT_IS_IT.md

@@ -0,0 +1,77 @@
+# 1 · What Is - **Stella Ops**?
+
+Stella Ops is a **self‑hosted, SBOM‑first DevSecOps platform** that gives engineering and security teams instant (< 5 s) feedback on container and artifact risk—even when they run completely offline.  
+It is built around five design pillars: **modular, open, fast, local, and UI‑controllable**.
+
+---
+
+## 1. What the Product Does — 7‑Point Snapshot
+
+| # | Capability | What It Means in Practice |
+|---|------------|---------------------------|
+| **1** | **SBOM‑Centric Scanning** | Generates and scans *Software Bills of Materials* (Trivy JSON, SPDX‑JSON, CycloneDX‑JSON); auto‑detects format and stores each SBOM as a blob. |
+| **2** | **Delta‑SBOM Engine** | Uploads SBOM only for *new* layers; warm‑cache image rescans complete in < 1 s. |
+| **3** | **Anonymous Internal Registry** | Ships a built‑in `StellaOps.Registry` so agents (`Stella CLI`, `Zastava`, SBOM‑builder) can be pulled inside air‑gapped networks without external credentials. |
+| **4** | **Policy‑as‑Code** | Supports YAML rules today and OPA/Rego (`StellaOps.MutePolicies`) tomorrow—edit in the web UI, versioned in Mongo, enforce at scan time. |
+| **5** | **Pluggable Modules** | Every scanner, exporter, or attestor is a hot‑load .NET plug‑in (e.g., `StellaOpsAttestor` for SLSA/Rekor in the roadmap). |
+| **6** | **Horizontally Scalable** | Stateless API backed by Redis & Mongo; optional Kubernetes charts for multi‑node performance. |
+| **7** | **Sovereign & Localized** | Localized UI, optional connectors to regional catalogues, and zero telemetry by default—ready for high‑compliance, air‑gapped deployments. |
+
+> **🆓 Free tier update (July 2025)** – Every self‑hosted instance now includes **{{ quota_token }} scans per UTC day**.  
+> A yellow banner appears once you cross **200 scans** (≈ 60 % of quota).  
+> Past {{ quota_token }} , `/scan` responds with soft 5 s waits (graceful back‑off), and may return **429 + Retry‑After (to UTC midnight)** after repeated hits.
+
+---
+
+## 2. How It Works — End‑to‑End Flow (30 sec tour)
+
+1. **Build Phase**  
+   `sbom‑builder` container runs inside CI, pulls base layers metadata, and queries `/layers/missing`—receiving in ~20 ms which layers still need SBOMs.  
+   • New layers ➟ SBOM generated ➟ `*.sbom.<type>` + `*.sbom.type` dropped next to image tarball.
+
+2. **Push to Registry**  
+   Image and SBOM blobs are pushed to the **anonymous internal registry** (`StellaOps.Registry`). Cosign tags are attached if enabled.
+
+3. **Scan Phase**  
+   `Stella CLI` agent pulls the SBOM blob, sends `/scan?sbomType=spdx-json` to backend. If flag is absent, backend auto‑detects.  
+   • Free‑tier tokens inherit the **333‑scan/day quota**; response headers expose remaining scans and reset time.
+
+4. **Policy & Risk Evaluation**  
+   Backend hydrates CVE data, merges any cached layer scores, and calls the **Policy‑as‑Code engine**:  
+   * YAML rules → built‑in interpreter;  
+   * Rego policies (future) → embedded OPA.
+
+5. **Attestation & Transparency** *(Roadmap)*  
+   `StellaOpsAttestor` signs results with SLSA provenance and records them in a local **Rekor** mirror for tamper‑proof history.
+
+6. **Feedback Loop**  
+   • CLI exits with non‑zero on policy block.  
+   • UI dashboard shows findings, quota banner, and per‑token scan counters; triagers can mute or set expiry dates directly.
+
+---
+
+## 3. Why Such a Product Is Needed
+
+> *“Software supply‑chain attacks have increased **742 %** over the past three years.”* – Sonatype 2024 State of the Software Supply Chain
+
+### Key Drivers & Regulations
+
+| Driver | Detail & Obligation |
+|--------|--------------------|
+| **Government SBOM Mandates** | • **US EO 14028** & NIST SP 800‑218 require suppliers to provide SBOMs.<br>• EU **Cyber Resilience Act (CRA)** will demand attestations of secure development by 2026. |
+| **SLSA & SSDF Frameworks** | Industry pushes toward **SLSA v1.0** levels 2‑3 and NIST **SSDF 1.1** controls, emphasising provenance and policy enforcement. |
+| **Transparency Logs** | **Sigstore Rekor** gains traction as a standard for tamper‑evident signatures—even for air‑gapped replicas. |
+| **Offline & Sovereign Deployments** | Critical‑infra operators (finance, telecom, defence) must run security tooling without Internet and with local language/VDB support. |
+| **Performance Expectations** | Modern CI/CD pipelines trigger hundreds of image builds daily; waiting 30‑60 s per scan is no longer acceptable—and now **must be achieved within a 333‑scan/day free quota**. |
+
+### Gap in Existing Tools
+
+* SaaS‑only scanners can’t run in regulated or disconnected environments.  
+* Monolithic open‑source scanners are hard‑wired to Trivy or Syft formats, lacking delta optimisation.  
+* Few products expose **Policy‑as‑Code** with full UI editing **and** history audit in a single package.  
+* None address quota‑aware throttling without hidden paywalls.
+
+**Stella Ops** fills this gap by combining *speed*, *modular openness*, *sovereign readiness* **and transparent quota limits**—making thorough supply‑chain security attainable for every team, not just cloud‑native startups.
+
+---
+*Last updated: 14 Jul 2025*