Add initial documentation
This commit is contained in:
147
docs/23_FAQ_MATRIX.md
Normal file
147
docs/23_FAQ_MATRIX.md
Normal file
@ -0,0 +1,147 @@
|
||||
# 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)*
|
||||
Reference in New Issue
Block a user