stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
aaa5fbfb784e217a5797de2c9dc5b0ee17f8a0d7
git.stella-ops.org/docs/24_OFFLINE_KIT.md
master c72621c71a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
feat: Enhance SBOM composition with policy findings and update CycloneDX package 
- Added `PolicyFindings` property to `SbomCompositionRequest` to include policy findings in SBOM.
- Implemented `NormalizePolicyFindings` method to process and validate policy findings.
- Updated `SbomCompositionRequest.Create` method to accept policy findings as an argument.
- Upgraded CycloneDX.Core package from version 5.1.0 to 10.0.1.
- Marked several tasks as DONE in TASKS.md, reflecting completion of SBOM-related features.
- Introduced telemetry metrics for Go analyzer to track heuristic fallbacks.
- Added performance benchmarks for .NET and Go analyzers.
- Created new test fixtures for .NET applications, including dependencies and runtime configurations.
- Added licenses and nuspec files for logging and toolkit packages used in tests.
- Implemented `SbomPolicyFinding` record to encapsulate policy finding details and normalization logic.
2025-10-23 07:57:27 +03:00

7.9 KiB
Executable File
Raw Blame History

Offline Update Kit (OUK) — Air‑Gap Bundle

The Offline Update Kit packages everything Stella Ops needs to run on a completely isolated network:

Component Contents
Merged vulnerability feeds OSV, GHSA plus optional NVD 2.0, CNNVD, CNVD, ENISA, JVN and BDU
Container images stella-ops, Zastava sidecar (x86‑64 & arm64)
Provenance Cosign signature, SPDX 2.3 SBOM, in‑toto SLSA attestation
Attested manifest offline-manifest.json + detached JWS covering bundle metadata, signed during export.
Delta patches Daily diff bundles keep size < 350 MB
Scanner plug-ins OS analyzers plus the Node.js, Go, and .NET language analyzers packaged under plugins/scanner/analyzers/** with manifests so Workers load deterministically offline.

RU BDU note: ship the official Russian Trusted Root/Sub CA bundle (certificates/russian_trusted_bundle.pem) inside the kit so concelier:httpClients:source.bdu:trustedRootPaths can resolve it when the service runs in an air‑gapped network. Drop the most recent vulxml.zip alongside the kit if operators need a cold-start cache.

Language analyzers: the kit now carries the restart-only Node.js, Go, and .NET analyzer plug-ins (plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Node/, plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Go/, plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.DotNet/). Drop the directories alongside Worker binaries so the unified plug-in catalog can load them without outbound fetches; upcoming Python/Rust plug-ins will follow the same layout.

Scanner core: C# 12 on .NET {{ dotnet }}.
Imports are idempotent and atomic — no service downtime.

1 · Download & verify

curl -LO https://get.stella-ops.org/ouk/stella-ops-offline-kit-<DATE>.tgz
curl -LO https://get.stella-ops.org/ouk/stella-ops-offline-kit-<DATE>.tgz.sig
curl -LO https://get.stella-ops.org/ouk/offline-manifest-<DATE>.json
curl -LO https://get.stella-ops.org/ouk/offline-manifest-<DATE>.json.jws

cosign verify-blob \
  --key https://stella-ops.org/keys/cosign.pub \
  --signature stella-ops-offline-kit-<DATE>.tgz.sig \
  stella-ops-offline-kit-<DATE>.tgz

CLI shortcut. stellaops-cli offline kit pull --destination ./offline-kit downloads the bundle, manifest, and detached signatures in one step, resumes partial transfers, and writes a .metadata.json summary for later import.

Verification prints OK and the SHA‑256 digest; cross‑check against the changelog.

Validate the attested manifest before distribution:

cosign verify-blob \
  --key https://stella-ops.org/keys/cosign.pub \
  --signature offline-manifest-<DATE>.json.jws \
  offline-manifest-<DATE>.json

jq '.artifacts[] | {name, sha256, size, capturedAt}' offline-manifest-<DATE>.json

The manifest enumerates every artefact (name, sha256, size, capturedAt) and is signed with the same key registry as Authority revocation bundles. Operators can ship the manifest alongside the tarball so downstream mirrors can re-verify without unpacking the kit.

Example excerpt (2025-10-23 kit) showing the Go and .NET analyzer plug-in payloads:

{
  "name": "plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Go/StellaOps.Scanner.Analyzers.Lang.Go.dll",
  "sha256": "a6dc850fc51151c8967ef46a3c4730f08b549667e041079431f39a8a72d0b641",
  "size": 33792,
  "capturedAt": "2025-10-23T00:00:00Z"
}
{
  "name": "plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Go/StellaOps.Scanner.Analyzers.Lang.Go.pdb",
  "sha256": "6cbdabf155282f458b89edf267e7f6bb2441a93029aad7aad45c8a9ec58b1b3b",
  "size": 32152,
  "capturedAt": "2025-10-23T00:00:00Z"
}
{
  "name": "plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Go/manifest.json",
  "sha256": "c19bfca2fcbb7cb18f1082b5d0d5a8f15fc799c648b50e95fce8d8b109ce48c9",
  "size": 622,
  "capturedAt": "2025-10-23T00:00:00Z"
}
{
  "name": "plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.DotNet/StellaOps.Scanner.Analyzers.Lang.DotNet.dll",
  "sha256": "0734d23e33277ce2ccb596782d2d42cfe394b3d372dc34da9cb28b59df9b9d22",
  "size": 70144,
  "capturedAt": "2025-10-23T00:00:00Z"
}
{
  "name": "plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.DotNet/StellaOps.Scanner.Analyzers.Lang.DotNet.pdb",
  "sha256": "b853c1ff4b196715f5bd1447e1a13edeb4940917527ec9bf153b5048da49abaf",
  "size": 40400,
  "capturedAt": "2025-10-23T00:00:00Z"
}
{
  "name": "plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.DotNet/manifest.json",
  "sha256": "5d483885f825f01bfd9943dcf2889ec2e0beba38ede92ecfe67d4f506cf14e37",
  "size": 647,
  "capturedAt": "2025-10-23T00:00:00Z"
}

2 · Import on the air‑gapped host

docker compose --env-file .env \
  -f docker-compose.stella-ops.yml \
  exec stella-ops \
  stella admin import-offline-usage-kit stella-ops-offline-kit-<DATE>.tgz

Alternatively, run

stellaops-cli offline kit import stella-ops-offline-kit-<DATE>.tgz \
  --manifest offline-manifest-<DATE>.json \
  --bundle-signature stella-ops-offline-kit-<DATE>.tgz.sig \
  --manifest-signature offline-manifest-<DATE>.json.jws

The CLI validates recorded digests (when .metadata.json is present) before streaming the multipart payload to /api/offline-kit/import.

  • The CLI validates the Cosign signature before activation.
  • Old feeds are kept until the new bundle is fully verified.
  • Import time on a SATA SSD: ≈ 25 s for a 300 MB kit.

Quick smoke test: before import, verify the tarball carries the Go analyzer plug-in:

tar -tzf stella-ops-offline-kit-<DATE>.tgz 'plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Go/*' 'plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.DotNet/*'

The manifest lookup above and this tar listing should both surface the Go analyzer DLL, PDB, and manifest entries before the kit is promoted.

3 · Delta patch workflow

  1. Connected site fetches stella-ouk-YYYY‑MM‑DD.delta.tgz.
  2. Transfer via any medium (USB, portable disk).
  3. stella admin import-offline-usage-kit <delta> applies only changed CVE rows & images.

Daily deltas are < 30 MB; weekly roll‑up produces a fresh full kit.

4 · Quota behaviour offline

The scanner enforces the same fair‑use limits offline:

  • Anonymous: {{ quota_anon }} scans per UTC day
  • Free JWT: {{ quota_token }} scans per UTC day

Soft reminder at 200 scans; throttle above the ceiling but never block. See the detailed rules in 33_333_QUOTA_OVERVIEW.md.

5 · Troubleshooting

Symptom Explanation Fix
could not verify SBOM hash Bundle corrupted in transit Re‑download / re‑copy
Import hangs at Applying feeds… Low disk space in /var/lib/stella Free ≥ 2 GiB before retry
quota exceeded same day after import Import resets counters at UTC 00:00 only Wait until next UTC day or load a JWT

6 · Related documentation

  • Install guide: /install/#air-gapped
  • Sovereign mode rationale: /sovereign/
  • Security policy: /security/#reporting-a-vulnerability
  • CERT-Bund snapshots: python tools/certbund_offline_snapshot.py --help (see docs/ops/concelier-certbund-operations.md)