stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
git.stella-ops.org/docs/24_OUK_ADMIN_GUIDE.md

7.6 KiB
Raw Permalink Blame History

# 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
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
  1. Verify the Cosign signature
cosign verify-blob \
    --key cosign.pub \
    --signature ouk-20250715.tar.gz.sig \
    ouk-20250715.tar.gz

  1. 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.

  2. UI → Settings → Offline Updates → Upload the tarball

  3. Wait for the toast: “Feeds updated · Trivy DB 2025‑07‑14 · NVD 2025‑07‑15”

  4. 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:
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.

  1. 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.

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:
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)