# 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