stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add initial documentation

Browse Source
This commit is contained in:
Vladimir Moushkov
2025-07-20 21:38:21 +03:00
parent 8ba0a0ba6d
commit 42d9d2d860
24 changed files with 4447 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
docs/24_OUK_ADMIN_GUIDE.md Normal file
View File

@ -0,0 +1,196 @@
# 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)*