Add initial documentation
This commit is contained in:
121
docs/02_WHY.md
Normal file
121
docs/02_WHY.md
Normal file
@ -0,0 +1,121 @@
|
||||
# 2 · WHY — Why Stella Ops Exists
|
||||
|
||||
> Explaining the concrete pain we solve, why the world needs **one more** DevSecOps
|
||||
> platform, and the success signals that prove we are on the right track.
|
||||
|
||||
Software‑supply‑chain attacks, licence‑risk, and incomplete SBOM coverage slow
|
||||
teams and compliance audits to a crawl. Most existing scanners:
|
||||
|
||||
* **Assume Internet** access for CVE feeds or SaaS back‑ends.
|
||||
* **Parse an entire image** every build (no layer‑delta optimisation).
|
||||
* **Accept a single SBOM format** (usually Trivy JSON) and choke on anything else.
|
||||
* Offer **no built‑in policy history / audit trail**.
|
||||
* Require 30‑60 s wall‑time per scan, an order of magnitude slower than modern CI
|
||||
expectations.
|
||||
* **Hide quota limits** or throttle without warning once you move past free trials.
|
||||
|
||||
---
|
||||
# 1 Free‑Tier Quota — Why **333**?
|
||||
|
||||
The limit of **333 SBOM scans per UTC day** was not chosen at random.
|
||||
|
||||
| Constraint | Analysis | Outcome |
|
||||
|------------|----------|---------|
|
||||
| **SMB workload** | Internal survey across 37 SMBs shows median **210** container builds/day (p95 ≈ 290). | 333 gives ≈ 1.6 × head‑room without forcing a paid tier. |
|
||||
| **Cost of feeds** | Hosting, Trivy DB mirrors & CVE merge traffic average **≈ $14 / 1 000 scans**. | 333/day yields <$5 infra cost per user — sustainable for an OSS project. |
|
||||
| **Incentive to upgrade** | Larger orgs (> 300 builds/day) gain ROI from Plus/Pro tiers anyway. | Clear upsell path without hurting hobbyists. |
|
||||
|
||||
> **In one sentence:** *333 scans cover the daily needs of a typical small /
|
||||
> medium business, keep free usage genuinely useful and still leave a financial
|
||||
> runway for future development*.
|
||||
|
||||
## 1.1 How the Quota Is Enforced (1‑minute view)
|
||||
|
||||
* Backend loads the **Quota plug‑in** at startup.
|
||||
* Every `/scan` call passes the caller’s **Client‑JWT** to the plug‑in.
|
||||
* The plug‑in **increments a counter in Redis** under
|
||||
`quota:<token>:<yyyy‑mm‑dd>` (expires at UTC midnight).
|
||||
* Soft wait‑wall (5 s) after limit; hard wait‑wall (60 s) after 30 blocked calls.
|
||||
* For **offline installs**, a *1‑month validity Client‑JWT* ships inside every
|
||||
**Offline Update Kit (OUK)** tarball. Uploading the OUK refreshes the token
|
||||
automatically.
|
||||
|
||||
Detailed sequence living in **30_QUOTA_ENFORCEMENT_FLOW.md**.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 2 · Why *Another* DevSecOps Product? — Macro Drivers
|
||||
|
||||
| Driver | Evidence | Implication for Tooling |
|
||||
|--------|----------|-------------------------|
|
||||
| **Exploding supply‑chain attacks** | Sonatype 2024 report shows **742 %** growth since 2020. | SBOMs & provenance checks must be default, not “best‑practice”. |
|
||||
| **Regulation tsunami** | • US EO 14028 & NIST SP 800‑218<br>• EU Cyber‑Resilience Act (CRA) in force 2026<br>• Russian ФЗ‑187 for КИИ | Vendors must *attest* build provenance (SLSA) and store tamper‑proof SBOMs. |
|
||||
| **Runtime‑cost intolerance** | Pipelines build hundreds of images/day; waiting > 10 s per scan breaks SLA. | Need **delta‑aware** engines that reuse layer analyses (< 1 s warm scans). |
|
||||
| **Air‑gap & sovereignty demands** | Finance/defence prohibit outbound traffic; data must stay on‑prem. | Ship **self‑contained registry + CVE DB** and run offline. |
|
||||
| **Predictable free‑tier limits** | Teams want clarity, not surprise throttling. | Provide **transparent 333 scans/day quota**, early banner & graceful wait‑wall. |
|
||||
|
||||
> **Therefore:** The market demands a **modular, SBOM‑first, sub‑5 s, 100 % self‑hosted**
|
||||
> platform **with a transparent free‑tier quota**—precisely the niche Stella Ops targets.
|
||||
|
||||
---
|
||||
|
||||
## 3 · Gap in Current Tooling
|
||||
|
||||
* Trivy / Syft create SBOMs but re‑analyse **every** layer → wasted minutes/day.
|
||||
* Policy engines (OPA/Rego) are separate binaries, with no UI or change history.
|
||||
* No mainstream OSS bundle ships an **anonymous internal registry** for air‑gapped pulls.
|
||||
* Provenance attestation (SLSA) and Rekor transparency logs remain “bring‑your‑own”.
|
||||
* Free tiers either stop at 100 scans **or** silently throttle; none announce a **clear 333/day allowance**.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Why Stella Ops Can Win
|
||||
|
||||
1. **Speed First** — Delta‑SBOM flow uses cached layers to hit `< 1 s` warm scans.
|
||||
2. **Multi‑Format Ready** — Auto‑detects Trivy‑JSON, SPDX‑JSON, CycloneDX‑JSON; UI
|
||||
lets teams choose per‑project defaults.
|
||||
3. **Offline by Default** — Ships an **anonymous internal Docker registry**
|
||||
(`StellaOps.Registry`) plus Redis, Mongo, CVE DB, and UI in a single compose up.
|
||||
4. **Open & Modular** — .NET hot‑load plug‑ins (`StellaOpsAttestor`, future scanners)
|
||||
under AGPL; anyone can extend.
|
||||
5. **Policy as Code** — YAML rules today, upgrade path to OPA/Rego with history stored
|
||||
in Mongo via `StellaOps.MutePolicies`.
|
||||
6. **Sovereign‑Ready** — Russian‑language UI, local vulnerability mirrors, zero
|
||||
telemetry by default.
|
||||
7. **Honest Free‑tier Boundaries** — Clear **333 scans/day** limit, early banner at 200 and predictable wait‑wall—no hidden throttling.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Success Criteria — Signals We Solve the Problem
|
||||
|
||||
* **Performance:** P95 scan < 5 s on first pass; `< 1 s` for warm delta scans.
|
||||
* **Compatibility:** SBOMs in at least three formats consumed by ≥ 3 downstream tools.
|
||||
* **Adoption:** ≥ 1 000 reported installs & ≥ 2 000 binary downloads by Q2‑2026.
|
||||
* **Compliance:** Positive audits referencing CRA / NIST / SLSA readiness.
|
||||
* **Community:** ≥ 15 first‑time contributors merged per quarter by 2026.
|
||||
* **Transparency:** 0 support tickets complaining about “mystery throttling”.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Non‑Goals (2025‑2027)
|
||||
|
||||
* Multi‑tenant SaaS offering.
|
||||
* Automatic “fix‑PR” generation (left to ecosystem).
|
||||
* Windows container **scanning** (Windows *agents* are on the 12‑month roadmap).
|
||||
|
||||
---
|
||||
|
||||
## 7 · Stakeholder Pain‑Point Recap
|
||||
|
||||
| Persona | Pain Today | Stella Ops Solution |
|
||||
|---------|------------|---------------------|
|
||||
| **Dev** | “My CI fails for 45 s on every push.” | < 5 s initial, < 1 s warm scans. |
|
||||
| **Sec‑Ops** | Separate tools for SBOM, policy, and audit. | Unified UI + YAML / Rego policies with history. |
|
||||
| **Infra** | Internet‑blocked site; no public pulls allowed. | Offline compose bundle + internal registry. |
|
||||
| **Compliance** | Need CRA‑ready provenance by 2026. | Future `StellaOpsAttestor` SLSA + Rekor integration. |
|
||||
| **Budget owner** | Fears hidden overage charges in “free” tiers. | Transparent 333 scans/day limit, visible in UI/API. |
|
||||
|
||||
---
|
||||
*Last updated: 14 Jul 2025 (sync with free‑tier quota rev 2.0).*
|
||||
Reference in New Issue
Block a user