# 23 · FAQ Matrix — Stella Ops 

# FAQ & Support Matrix

A living list of the questions we get every day, plus a compact matrix of what is **Supported Now**, **In Preview**, and **On the Roadmap (TODO)**.

---

## 0 Quick Legend

| Mark | Meaning |
|------|---------|
| ✅ | Fully supported in the current release |
| 🅿️ | Preview / opt‑in behind a feature flag |
| 🛠  | Planned in the **≤ 6 month** roadmap (Feature Matrix “TODO”) |
| 🚧 | Longer‑term; 9‑12 month horizon or beyond |

---

## 1 General

| # | Question | Short Answer | Status |
|---|----------|-------------|--------|
| G‑1 | *Why launch **another** DevSecOps product?* | Existing scanners are either SaaS‑only, slow, or lack offline & Russian language feeds. Stella Ops focuses on *speed (<5 s), modularity, air‑gap friendliness*, and an AGPL code‑base that enterprises can extend in‑house. | ✅ |
| G‑2 | *What tech stack?* | Backend **.NET 9** + Redis; runners are OCI images (Trivy, Syft, Grype). UI Angular 17. | ✅ |
| G‑3 | *License?* | **AGPL v3** for all core repos; plugins inherit if linked. | ✅ |
| G‑4 | *Where do I report bugs?* | Open an issue in `git.stella-ops.ru/stella/core` or ping `#stella-ops` on Matrix. | ✅ |

---

## 2 Installation & Upgrades

| # | Question | Answer | Status |
|---|----------|--------|--------|
| I‑1 | *How do I pull agent images now?* | All official images are in the **anonymous read‑only registry** `registry.git.stella-ops.ru`. No auth token required for pull. | ✅ *(new)* |
| I‑2 | *Can I still use GHCR?* | Images remain mirrored for convenience but are not signed; internal registry is the source of truth. | ✅ |
| I‑3 | *How to upgrade from ≤ v0.8?* | Re‑generate `docker‑compose.yml` with the bootstrap script; volumes remain intact. Import legacy mute‑rules via `/policy/import`. | ✅ |
| I‑4 | *Helm charts?* | K8s Helm chart is under `deploy/helm`; undefaulted (requires `values.yaml`). | 🅿️ |

---

## 3 SBOM & Scanning


| # | Question | Short Answer | Status |
|---|----------|-------------|--------|
|---|----------|-------------|--------|
| **S‑1** | *Why exactly **333 scans**?* | Covers p95 workload of SMBs (~290 builds/day) while keeping infra costs <$5/mo per user and nudging larger orgs toward Plus/Pro. | ✅ |
| **S‑2** | *How is the limit technically enforced?* | Each `/scan` request carries a **Client‑JWT**. The Quota plug‑in atomically increments `quota:<token>:<date>` in Redis. Soft (5 s) and hard (60 s) wait‑walls ensure fair use. | ✅ |
| **S‑3** | *What if my site is fully offline?* | Every **OUK tarball** contains a fresh Client‑JWT valid **30 days**. Uploading the OUK refreshes the token automatically; no Internet required. | ✅ |
| S‑4 | *Can I pool multiple tokens?* | Yes, but each token has its own 333/day budget. Use distinct tokens per CI line if you need more throughput. | ✅ |
| S‑5 | *Does quota enforcement affect performance?* | No. Legitimate scans still complete in < 5 s; blocked scans incur only their specified wait‑wall. | ✅ |
| S‑6 | *Which SBOM formats does Stella emit?* | Built‑in: **`trivy-json-v2`**, **`spdx-json`**, **`cyclonedx-json`**. | ✅ |
| S‑7 | *What is Δ‑SBOM and how fast is it?* | Uploads only new layers; P95 ≤ 1 s on cached bases. | ✅ |
| S‑8 | *Windows container scanning?* | Runner binaries compile on Windows, but layer‑unpack path is unoptimised; full support 🚧. | 🚧 |

---

## 4 Policy‑as‑Code

| # | Question | Answer | Status |
|---|----------|--------|--------|
| P‑1 | *How are mutes & blocks stored now?* | Default: **YAML** (`scan-policy.yaml`) in Mongo (versioned). Import / export via `/policy/{import,export}` or Settings → Policies. | ✅ |
| P‑2 | *Why YAML over OPA?* | YAML lowers entry barrier; advanced users may embed **Rego** snippets. First‑class Rego evaluation is 🛠. | 🛠 |
| P‑3 | *CLI enforcement?* | Pass `--policy-file path` plus `--enforce` to fail builds on violations. Exit‑code reflects policy gate. | ✅ |
| P‑4 | *Audit history?* | Every policy change writes an immutable record (`audit_policies` collection) and appears in UI *History* tab. | ✅ |

---

## 5 Registry & Offline Use

| # | Question | Answer | Status |
|---|----------|--------|--------|
| R‑1 | *Is the internal registry mandatory?* | No, but recommended for sovereignty & signature verification (`cosign verify`). | ✅ |
| R‑2 | *How to mirror for OUK?* | `oras pull registry.git.stella-ops.ru/library/* --output ./ouk-bundle` → import on the target via `ctr images import`. | ✅ |
| R‑3 | *Does the backend fetch external feeds?* | Only when `--feeds.auto=1`; OUK installs run fully offline with NVD packed in the tarball. | ✅ |

---

## 6 Performance

| # | Scenario | Target | Achieved (July 2025) |
|---|----------|--------|----------------------|
| Local SBOM scan (`alpine`) | **≤ 5 s** | 4.2 s P95 |
| Δ‑SBOM warm base | **≤ 1 s** | 0.8 s P95 |
| Image unpack (200 MB) | **≤ 10 s** | 8.6 s P95 |

*Numbers measured on 4 vCPU / 8 GB Ubuntu 22.04 runner.*

---

## 7 Security & Compliance

| # | Question | Answer | Status |
|---|----------|--------|--------|
| C‑1 | *How are images signed?* | Cosign signatures pushed alongside each tag (`*.sig`). Santech verifies on pull. | ✅ |
| C‑2 | *Supply‑chain attestation (SLSA)?* | SLSA‑gen at build time and verification in runner is 🛠 (≤ 6 months). | 🛠 |
| C‑3 | *Rekor transparency log?* | Local Rekor mirror for offline installs is 🚧 (9‑12 months). | 🚧 |
| C‑4 | *TLS ciphers?* | Default OpenSSL suites; plug‑in allows GOST/SM (via `ITlsProvider`). | ✅ |

---

## 8 Road‑map / Future Features

| Area | Feature | ETA | Notes |
|------|---------|-----|-------|
| UI  | Modular route plug‑ins | Q1‑2026 | Dynamic Angular module loader |
| SBOM | Multi‑arch Δ‑SBOM | Q1‑2026 | Layer digest per arch |
| Policy | Rego native engine | Q1‑2026 | `opa eval` in‑proc |
| Supply chain | SLSA provenance | Q1‑2026 | Level 3 target |
| Integrity | Rekor mirror | Q2‑2026 | Air‑gap friendly |
| Ecosystem | Community plugin market | Q2‑2026 | Curated index in UI |
| Scale | Redis Cluster auto‑shard | Q3‑2026 | Transparent fail‑over |

---

## 9 Troubleshooting

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| **`ER_BAD_SV` error on scan** | SBOM format flag mismatch | Set correct `--sbom-type` or let auto‑detect. |
| Δ‑SBOM still uploads full SBOM | Cache cold or digest mismatch | Check `docker history` shows reused layers; bump builder version. |
| “Policy file invalid” | YAML schema error | Run `/policy/validate` endpoint; lint with VS Code schema. |
| Pull fails with 401 | Corporate proxy intercepts registry | Mirror to on‑premise Harbor; set `--registry` flag. |

---

## 10 Licensing & Community

| # | Question | Answer |
|---|----------|--------|
| L‑1 | *Can I build a commercial fork?* | AGPL allows commercial services but derivatives must remain AGPL if distributed. |
| L‑2 | *Commercial support?* | Community only today; paid support partners in discussion. |
| L‑3 | *How to contribute a plugin?* | Fork → implement DI contract (`IScannerRunner`, etc.) → PR + ADR. |

---

## 11 Change Log

| Date       | Highlights |
|------------|------------|
| 2025‑07‑14 | Added internal registry, multi‑format SBOM, Δ‑SBOM, Policy‑as‑Code, updated roadmap (SLSA/Rekor) |
| 2025‑06‑30 | Initial public FAQ matrix |

---

*(End of FAQ Matrix v2.0)*