Initial commit

2025-08-30 21:05:34 +00:00
commit b04557a923
40 changed files with 5469 additions and 0 deletions
--- a/docs/24_OFFLINE_KIT.md
+++ b/docs/24_OFFLINE_KIT.md
@@ -0,0 +1,94 @@
+# Offline Update Kit (OUK) — Air‑Gap Bundle
+
+<!--
+  Build‑time variable injection:
+    {{ quota_anon }}   = 33
+    {{ quota_token }}  = 333
+    {{ dotnet }}       = "10 LTS"
+-->
+
+The **Offline Update Kit** packages everything Stella Ops needs to run on a
+completely isolated network:
+
+| Component | Contents |
+|-----------|----------|
+| **Merged vulnerability feeds** | OSV, GHSA plus optional NVD 2.0, CNNVD, CNVD, ENISA, JVN and BDU |
+| **Container images** | `stella-ops`, *Zastava* sidecar (x86‑64 & arm64) |
+| **Provenance** | Cosign signature, SPDX 2.3 SBOM, in‑toto SLSA attestation |
+| **Delta patches** | Daily diff bundles keep size \< 350 MB |
+
+*Scanner core:* C# 12 on **.NET {{ dotnet }}**.  
+*Imports are idempotent and atomic — no service downtime.*
+
+---
+
+## 1 · Download & verify
+
+```bash
+curl -LO https://get.stella-ops.org/ouk/stella-ops-offline-kit-<DATE>.tgz
+curl -LO https://get.stella-ops.org/ouk/stella-ops-offline-kit-<DATE>.tgz.sig
+
+cosign verify-blob \
+  --key https://stella-ops.org/keys/cosign.pub \
+  --signature stella-ops-offline-kit-<DATE>.tgz.sig \
+  stella-ops-offline-kit-<DATE>.tgz
+````
+
+Verification prints **OK** and the SHA‑256 digest; cross‑check against the
+[changelog](https://git.stella-ops.org/stella-ops/offline-kit/-/releases).
+
+---
+
+## 2 · Import on the air‑gapped host
+
+```bash
+docker compose --env-file .env \
+  -f docker-compose.stella-ops.yml \
+  exec stella-ops \
+  stella admin import-offline-usage-kit stella-ops-offline-kit-<DATE>.tgz
+```
+
+* The CLI validates the Cosign signature **before** activation.
+* Old feeds are kept until the new bundle is fully verified.
+* Import time on a SATA SSD: ≈ 25 s for a 300 MB kit.
+
+---
+
+## 3 · Delta patch workflow
+
+1. **Connected site** fetches `stella-ouk-YYYY‑MM‑DD.delta.tgz`.
+2. Transfer via any medium (USB, portable disk).
+3. `stella admin import-offline-usage-kit <delta>` applies only changed CVE rows & images.
+
+Daily deltas are **< 30 MB**; weekly roll‑up produces a fresh full kit.
+
+---
+
+## 4 · Quota behaviour offline
+
+The scanner enforces the same fair‑use limits offline:
+
+* **Anonymous:** {{ quota\_anon }} scans per UTC day
+* **Free JWT:** {{ quota\_token }} scans per UTC day
+
+Soft reminder at 200 scans; throttle above the ceiling but **never block**.
+See the detailed rules in
+[`33_333_QUOTA_OVERVIEW.md`](33_333_QUOTA_OVERVIEW.md).
+
+---
+
+## 5 · Troubleshooting
+
+| Symptom                                | Explanation                              | Fix                                   |
+| -------------------------------------- | ---------------------------------------- | ------------------------------------- |
+| `could not verify SBOM hash`           | Bundle corrupted in transit              | Re‑download / re‑copy                 |
+| Import hangs at `Applying feeds…`      | Low disk space in `/var/lib/stella`      | Free ≥ 2 GiB before retry             |
+| `quota exceeded` same day after import | Import resets counters at UTC 00:00 only | Wait until next UTC day or load a JWT |
+
+---
+
+## 6 · Related documentation
+
+* **Install guide:** `/install/#air-gapped`
+* **Sovereign mode rationale:** `/sovereign/`
+* **Security policy:** `/security/#reporting-a-vulnerability`