Add initial documentation
This commit is contained in:
77
docs/01_WHAT_IS_IT.md
Normal file
77
docs/01_WHAT_IS_IT.md
Normal file
@ -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 (`SanTech`, `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 & Localised** | Russian‑language UI, local vulnerability DB mirrors, and no telemetry by default—ready for ГОСТ/FSTEC‑sensitive deployments. |
|
||||
|
||||
> **🆓 Free tier update (July 2025)** – Every self‑hosted instance now includes **333 scans per UTC day**.
|
||||
> A yellow banner appears once you cross **200 scans** (≈ 60 % of quota).
|
||||
> Past 333, `/scan` responds with soft 5 s waits for 30 calls, then a hard **60 s wait‑wall** until the daily reset.
|
||||
|
||||
---
|
||||
|
||||
## 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**
|
||||
`SanTech` 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*
|
||||
Reference in New Issue
Block a user