197 lines
7.6 KiB
Markdown
197 lines
7.6 KiB
Markdown
# 24 · Offline Update Kit (OUK) Administration Guide — Stella Ops
|
||
|
||
|
||
# Offline Update Kit (OUK) — Administrator Guide
|
||
|
||
Stella Ops is designed for *offline‑first* deployments—e.g. regulated datacentres that can’t call out to GitHub or NVD.
|
||
The **Offline Update Kit (OUK)** bundles *all* mutable security data (Trivy DB, NVD JSON, OSV feeds, UI locales, policy bundles) into a signed, single‑file archive so you can refresh an isolated cluster in minutes.
|
||
|
||
---
|
||
|
||
## 0 Quick Start (TL;DR)
|
||
|
||
1. **Download** the latest release asset
|
||
|
||
```bash
|
||
curl -L -O https://git.stella-ops.ru/stella/ops/-/releases/latest/download/ouk-20250715.tar.gz
|
||
curl -L -O https://git.stella-ops.ru/stella/ops/-/releases/latest/download/ouk-20250715.tar.gz.sig
|
||
```
|
||
|
||
2. **Verify** the Cosign signature
|
||
|
||
```bash
|
||
cosign verify-blob \
|
||
--key cosign.pub \
|
||
--signature ouk-20250715.tar.gz.sig \
|
||
ouk-20250715.tar.gz
|
||
```
|
||
|
||
3. **JWT Refresh** – the tarball already contains a **`client.jwt`** file valid
|
||
for **30 days**. Importing the OUK automatically refreshes the token used for
|
||
quota accounting in offline mode.
|
||
|
||
4. **UI → Settings → Offline Updates → Upload** the tarball
|
||
5. Wait for the toast: **“Feeds updated · Trivy DB 2025‑07‑14 · NVD 2025‑07‑15”**
|
||
6. Sub‑5 s scans now use the fresh data—done!
|
||
|
||
---
|
||
|
||
## 1 What the OUK Contains
|
||
|
||
| Component | Typical size |
|
||
|----------------------------------------|--------------|
|
||
| Trivy vulnerability DB (`vuln.db.tgz`) | 50 MB |
|
||
| NVD JSON feed (all years) | 1.4 GB |
|
||
| OSV JSON snapshots | 500 MB |
|
||
| BDU XML feed (🇷🇺 optional) | 25 MB |
|
||
| UI locale bundles | 100 kB |
|
||
| Policy pack snapshots | 5 kB |
|
||
| SBOM of the kit (`manifest.spdx.json`) | <1 MB |
|
||
| Cosign signature (`*.sig`) | 1 kB |
|
||
| Client‑JWT (`client.jwt`) 30 d | 2 kB |
|
||
|
||
All files are **content‑addressed**; the SBOM references each SHA‑256 so auditors can trace provenance.
|
||
|
||
---
|
||
|
||
## 2 Security Model
|
||
|
||
* Every tarball is signed with the **Stella Ops project key** (`cosign.pub`, fingerprint `AB12 34CD 56EF…`).
|
||
* The backend refuses any archive that fails signature or digest checks.
|
||
* The embedded SBOM gives auditors full transparency into exact feed versions.
|
||
|
||
---
|
||
|
||
## 3 Obtaining an OUK Tarball
|
||
|
||
### 3.1 Official Builds
|
||
|
||
* Produced automatically on the **first Friday of every month** by the Release pipeline (see *13_RELEASE_ENGINEERING_PLAYBOOK.md*).
|
||
* Stored under **GitLab → Releases → Assets** with the filename pattern `ouk-YYYYMMDD.tar.gz`.
|
||
* Example download via curl:
|
||
|
||
```bash
|
||
curl -L -O https://git.stella-ops.ru/stella/ops/-/releases/v2.3/downloads/ouk-20250715.tar.gz
|
||
curl -L -O https://git.stella-ops.ru/stella/ops/-/releases/v2.3/downloads/ouk-20250715.tar.gz.sig
|
||
```
|
||
|
||
---
|
||
|
||
## 4 Uploading Via UI
|
||
|
||
1. Log in as **system : admin** (role = Owner).
|
||
2. Navigate **Settings → Offline Updates**.
|
||
3. Press **Upload** and pick `ouk-YYYYMMDD.tar.gz`.
|
||
4. Backend workflow
|
||
1. Streams the file to `/tmp`.
|
||
2. Runs `cosign verify-blob`.
|
||
3. Extracts content into `var/lib/stella/db/` (read‑only).
|
||
4. Flushes Redis cache.
|
||
> After Cosign verification the backend copies **`client.jwt`** into
|
||
> `/var/lib/stella/tokens/`, replacing the previous offline token and resetting
|
||
> its expiry countdown.
|
||
|
||
5. Audit log emits `ouk_update` event (actor, datetime, SHA‑256).
|
||
|
||
The UI toast now shows
|
||
> “Feeds updated + Offline Token refreshed (valid till *17 Aug 2025*)”.
|
||
|
||
---
|
||
|
||
## 5 Uploading Via CLI (REST API)
|
||
|
||
No custom tool is required—`curl` does the job.
|
||
|
||
```bash
|
||
ACCESS_TOKEN=$(cat token.txt) # bearer from OpenIddict
|
||
SIGNATURE_B64=$(base64 -w0 ouk-20250715.tar.gz.sig)
|
||
|
||
curl -X POST https://stella.local/api/admin/ouk \
|
||
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
|
||
-H "X-Signature: ${SIGNATURE_B64}" \
|
||
--data-binary @ouk-20250715.tar.gz
|
||
```
|
||
|
||
*HTTP 201* is success; any non‑2xx code means verification or extraction failed.
|
||
|
||
---
|
||
|
||
## 6 Automated Sync (Advanced)
|
||
|
||
When outbound Internet is *allowed* but inbound isn’t:
|
||
|
||
1. Deploy **StellaOps.Registry** (internal Docker registry) on a host that can reach the Internet.
|
||
2. Cron job pulls the latest OUK with curl, verifies it, stores in an internal S3 bucket.
|
||
3. Offline cluster fetches nightly via **MinIO Gateway** URL:
|
||
|
||
```bash
|
||
curl -L -O https://minio.infra/offline/ouk-latest.tar.gz
|
||
curl -L -O https://minio.infra/offline/ouk-latest.tar.gz.sig
|
||
# repeat verification and upload steps
|
||
```
|
||
|
||
Remember to propagate **`client.jwt`** together with the feeds if you split the
|
||
tarball into multiple artefacts; otherwise the offline cluster may hit
|
||
*“Token expired”* errors.
|
||
|
||
---
|
||
|
||
## 7 Rollback Strategy
|
||
|
||
* The backend keeps the **last three OUK snapshots** in `/var/lib/stella/ouk-backup/`.
|
||
* UI → Offline Updates → **Restore** next to the desired date.
|
||
* Operation swaps a symlink—≈ 3 s, no service restart.
|
||
|
||
---
|
||
|
||
## 8 Troubleshooting
|
||
|
||
| Symptom | Likely cause | Fix |
|
||
|--------------------------------------|----------------------|----------------------------------------------|
|
||
| “Signature verification failed” | Wrong key/tampered | Re‑download; compare key fingerprints |
|
||
| “Feed age tile stays red” | Redis cache stale | `stella admin redis flushall` |
|
||
| `io/fs: read‑only file system` | Volume mounted RO | Remount RW or move OUK path |
|
||
| NVD import > 10 min | Slow disk | Move DB path to SSD/LVM cache |
|
||
| *“Token expired”* banner after OUK upload | `client.jwt` missing or out‑of‑date | Re‑run `ouk fetch`; ensure tarball contains fresh token. |
|
||
|
||
---
|
||
|
||
## 9 Non‑Commercial Usage Rules (English)
|
||
|
||
1. **Free for internal assessments** by individuals or organisations.
|
||
2. **SaaS resale/re‑hosting is forbidden** without explicit written consent (AGPL §13).
|
||
3. If you redistribute a modified build you **must** publish complete source under the same licence and keep Stella Ops attribution.
|
||
4. Third‑party dependencies remain under their respective licences (MIT, Apache‑2.0, ISC, BSD).
|
||
5. Deployments in state‑regulated or classified environments must follow **ФЗ‑187** and export‑control law.
|
||
|
||
---
|
||
|
||
## 10 Best Practices Snapshot
|
||
|
||
* Rotate OUK uploads at least **monthly**; weekly during high CVE activity.
|
||
* Store OUK assets in an **immutable bucket** (S3 WORM, Artifactory release) to thwart tampering.
|
||
* Keep `cosign.pub` on an offline root‑of‑trust USB; rotate keys yearly.
|
||
* During audits, export `manifest.spdx.json` as evidence of feed provenance.
|
||
|
||
---
|
||
|
||
## 11 FAQ
|
||
|
||
**Q:** *Does OUK update Docker base images?*
|
||
**A:** No—OUK is for **data** only. Refresh base images via internal registry or CI pipelines.
|
||
|
||
**Q:** *Why not bundle Grype DB too?*
|
||
**A:** Grype consumes Trivy DB format directly; duplication saved 500 MB.
|
||
|
||
---
|
||
|
||
## 12 Change Log
|
||
|
||
| Version | Date | Notes |
|
||
|---------|------|-------|
|
||
| v1.2 | 2025‑07‑16 | Switched CLI to curl, removed DIY build, dropped “Location” column, clarified download example. |
|
||
| v1.1 | 2025‑07‑15 | Added UI upload flow, MinIO sync, usage rules, Cosign commands. |
|
||
| v1.0 | 2025‑07‑09 | Initial OUK admin guide |
|
||
|
||
*(End of Offline Update Kit Administration Guide v1.0)*
|