9e5e958d42
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Added detailed task completion records for KMS interface implementation and CLI support for file-based keys. - Documented security enhancements including Argon2id password hashing, audit event contracts, and rate limiting configurations. - Included scoped service support and integration updates for the Plugin platform, ensuring proper DI handling and testing coverage.
140 lines
4.8 KiB
Markdown
Executable File
140 lines
4.8 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](05_ROADMAP.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
|