Initial commit
This commit is contained in:
139
docs/10_OFFLINE_KIT.md
Executable file
139
docs/10_OFFLINE_KIT.md
Executable file
@@ -0,0 +1,139 @@
|
||||
# Offline Update Kit (OUK) — 100 % Air‑Gap Operation
|
||||
|
||||
> **Status:** ships together with the public α `v0.1.0` (ETA **late 2025**).
|
||||
> All commands below assume the bundle name
|
||||
> `stella-ouk‑2025‑α.tar.gz` – adjust once the real date tag is known.
|
||||
|
||||
---
|
||||
|
||||
## 1 · What’s in the bundle 📦
|
||||
|
||||
| Item | Purpose |
|
||||
|------|---------|
|
||||
| **Vulnerability database** | Pre‑merged snapshot of NVD 2.0, OSV, GHSA <br/> + optional **regional catalogue** feeds |
|
||||
| **Container images** | Scanner + Zastava for **x86‑64** & **arm64** |
|
||||
| **Cosign signatures** | Release attestation & SBOM integrity |
|
||||
| **SPDX SBOM** | Cryptographically signed bill of materials |
|
||||
| **Import manifest** | Check‑sums & version metadata |
|
||||
|
||||
Nightly **delta patches** keep the bundle < 350 MB while staying *T‑1 day*
|
||||
current.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Download & verify 🔒
|
||||
|
||||
```bash
|
||||
curl -LO https://get.stella-ops.org/releases/latest/stella-ops-offline-usage-kit-v0.1a.tar.gz
|
||||
curl -LO https://get.stella-ops.org/releases/latest/stella-ops-offline-usage-kit-v0.1a.tar.gz.sig
|
||||
|
||||
cosign verify-blob \
|
||||
--key https://stella-ops.org/keys/cosign.pub \
|
||||
--signature stella-ops-offline-usage-kit-v0.1a.tar.gz.sig \
|
||||
stella-ops-offline-usage-kit-v0.1a.tar.gz
|
||||
```
|
||||
|
||||
The output shows `Verified OK` and the SHA‑256 digest ‑ compare with the
|
||||
release notes.
|
||||
|
||||
---
|
||||
|
||||
## 3 · Import on the isolated host 🚀
|
||||
|
||||
```bash
|
||||
docker compose --env-file .env -f compose-stella.yml \
|
||||
exec stella-ops stella ouk import stella-ops-offline-usage-kit-v0.1a.tar.gz
|
||||
```
|
||||
|
||||
* The scanner verifies the Cosign signature **before** activation.
|
||||
* DB switch is atomic – **no downtime** for running jobs.
|
||||
* Import time on an SSD VM ≈ 5‑7 s.
|
||||
|
||||
---
|
||||
|
||||
## 4 · How the quota works offline 🔢
|
||||
|
||||
| Mode | Daily scans | Behaviour at 200 scans | Behaviour over limit |
|
||||
| --------------- | ----------- | ---------------------- | ------------------------------------ |
|
||||
| **Anonymous** | {{ quota_anon }} | Reminder banner | CLI slows \~10 % |
|
||||
| **Token (JWT)** | {{ quota_token }} | Reminder banner | Throttle continues, **never blocks** |
|
||||
|
||||
*Request a free JWT:* send a blank e‑mail to
|
||||
`token@stella-ops.org` – the bot replies with a signed token that you
|
||||
store as `STELLA_JWT` in **`.env`**.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Updating the bundle ⤴️
|
||||
|
||||
1. Download the newer tarball & signature.
|
||||
2. Repeat the **verify‑blob** step.
|
||||
3. Run `stella ouk import <file>` – only the delta applies; average
|
||||
upgrade time is **< 3 s**.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Road‑map highlights for Sovereign 🌐
|
||||
|
||||
| Release | Planned feature |
|
||||
| ---------------------- | ---------------------------------------- |
|
||||
| **v0.1 α (late 2025)** | Manual OUK import • Zastava beta |
|
||||
| **v0.3 β (Q2 2026)** | Auto‑apply delta patch • nightly re‑scan |
|
||||
| **v0.4 RC (Q3 2026)** | LDAP/AD SSO • registry scanner GA |
|
||||
| **v1.0 GA (Q4 2026)** | Custom TLS/crypto adaptors (**incl. SM2**)—enabled where law or security requires it |
|
||||
|
||||
Full details live in the public [Road‑map](../roadmap/README.md).
|
||||
|
||||
---
|
||||
|
||||
## 7 · Troubleshooting 🩹
|
||||
|
||||
| Symptom | Fix |
|
||||
| -------------------------------------------- | ------------------------------------------------------- |
|
||||
| `cosign: signature mismatch` | File corrupted ‑ re‑download both tarball & `.sig` |
|
||||
| `ouk import: no space left` | Ensure **8 GiB** free in `/var/lib/docker` |
|
||||
| Import succeeds but scans still hit Internet | Confirm `STELLA_AIRGAP=true` in `.env` (v0.1‑α setting) |
|
||||
|
||||
---
|
||||
|
||||
## 8 · FAQ — abbreviated ❓
|
||||
|
||||
<details>
|
||||
<summary><strong>Does the JWT token work offline?</strong></summary>
|
||||
|
||||
Yes. Signature validation happens locally; no outbound call is made.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Can I mirror the bundle internally?</strong></summary>
|
||||
|
||||
Absolutely. Host the tarball on an intranet HTTP/S server or an object
|
||||
store; signatures remain valid.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Is there a torrent alternative?</strong></summary>
|
||||
|
||||
Planned for the β releases – follow the
|
||||
[community chat](https://matrix.to/#/#stellaops:libera.chat) for ETA.
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
### Licence & provenance 📜
|
||||
|
||||
The Offline Update Kit is part of Stella Ops and therefore
|
||||
**AGPL‑3.0‑or‑later**. All components inherit the same licence.
|
||||
|
||||
```bash
|
||||
cosign verify-blob \
|
||||
--key https://stella-ops.org/keys/cosign.pub \
|
||||
--signature stella-ops-offline-usage-kit-v0.1a.tar.gz.sig \
|
||||
stella-ops-offline-usage-kit-v0.1a.tar.gz
|
||||
```
|
||||
|
||||
— **Happy air‑gap scanning!**
|
||||
© 2025‑2026 Stella Ops
|
||||
Reference in New Issue
Block a user