140 lines
4.9 KiB
Markdown
Executable File
140 lines
4.9 KiB
Markdown
Executable File
# 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
|