#  15 - Pragmatic UI Guide --- **Stella Ops** # Stella Ops Web UI A fast, modular single‑page application for controlling scans, policies, offline updates and platform‑wide settings. Built for sub‑second feedback, dark‑mode by default, and **no external CDNs** – everything ships inside the anonymous internal registry. --- ## 0 Fast Facts | Aspect | Detail | | ----------------- | -------------------------------------------------------------------------- | | Tech Stack | **Angular 17** + Vite dev server | | Styling | **Tailwind CSS** | | State | Angular Signals + RxJS | | API Client | OpenAPI v3 generated services (Axios) | | Auth | OAuth2 /OIDC (tokens from backend or external IdP) | | i18n | JSON bundles – **`/locales/{lang}.json`** (English, Russian shipped) | | Offline Updates 📌 | UI supports “OUK” tarball upload to refresh NVD / Trivy DB when air‑gapped | | Build Artifacts | (`ui/dist/`) pushed to `registry.git.stella-ops.ru/ui:${SHA}` | --- ## 1 Navigation Map ``` Dashboard └─ Scans ├─ Active ├─ History └─ Reports └─ Policies 📌 ├─ Editor (YAML / Rego) 📌 ├─ Import / Export 📌 └─ History └─ Settings ├─ SBOM Format 📌 ├─ Registry 📌 ├─ Offline Updates (OUK) 📌 ├─ Themes (Light / Dark / System) 📌 └─ Advanced └─ Plugins 🛠 └─ Help / About ``` *The **Offline Updates (OUK)** node under **Settings** is new.* --- ## 2 Technology Overview ### 2.1 Build & Deployment 1. `npm i && npm build` → generates `dist/` (~2.1 MB gzip). 2. A CI job tags and pushes the artifact as `ui:${GIT_SHA}` to the internal registry. 3. Backend serves static assets from `/srv/ui` (mounted from the image layer). _No external fonts or JS – true offline guarantee._ ### 2.2 Runtime Boot 1. **AppConfigService** pulls `/api/v1/config/ui` (contains feature flags, default theme, enabled plugins). 2. Locale JSON fetched (`/locales/{lang}.json`, falls back to `en`). 3. Root router mounts lazy‑loaded **feature modules** in the order supplied by backend – this is how future route plugins inject pages without forking the UI. --- ## 3 Feature Walk‑Throughs ### 3.1 Dashboard – Real‑Time Status * **Δ‑SBOM heat‑map** 📌 shows how many scans used delta mode vs. full unpack. * “Feed Age” tile turns **orange** if NVD feed is older than 24 h; reverts after an **OUK** upload 📌. * Live WebSocket updates for scans in progress (SignalR channel). * **Quota Tile** – shows **Scans Today / 333**; turns yellow at 200, red at 333. * **Token Expiry Tile** – shows days left on *client.jwt* (offline only); turns orange at < 7 days. ### 3.2 Scans Module | View | What you can do | | ----------- | ------------------------------------------------------------------------------------------------- | | **Active** | Watch progress bar (ETA ≤ 5 s) – newly added **Format** and **Δ** badges appear beside each item. | | **History** | Filter by repo, tag, policy result (pass/block/soft‑fail). | | **Reports** | Click row → HTML or PDF report rendered by backend (`/report/{digest}/html`). | ### 3.3 📌 Policies Module (new) *Embedded **Monaco** editor with YAML + Rego syntax highlighting.* | Tab | Capability | | ------------------- | ------------------------------------------------------------------------------------------------ | | **Editor** | Write or paste `scan-policy.yaml` or inline Rego snippet. Schema validation shown inline. | | **Import / Export** | Buttons map to `/policy/import` and `/policy/export`. Accepts `.yaml`, `.rego`, `.zip` (bundle). | | **History** | Immutable audit log; diff viewer highlights rule changes. | #### 3.3.1 YAML → Rego Bridge If you paste YAML but enable **Strict Mode** (toggle), backend converts to Rego under the hood, stores both representations, and shows a side‑by‑side diff. ### 3.4 📌 Settings Enhancements | Setting | Details | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **SBOM Format** | Dropdown – *Trivy JSON*, *SPDX JSON*, *CycloneDX JSON*. | | **Registry** | Displays pull URL (`registry.git.stella-ops.ru`) and Cosign key fingerprint. | | **Offline Updates (OUK)** 📌 | Upload **`ouk*.tar.gz`** produced by the Offline Update Kit CLI. Backend unpacks, verifies SHA‑256 checksum & Cosign signature, then reloads Redis caches without restart. | | **Theme** | Light, Dark, or Auto (system). | #### 3.4.1 OUK Upload Screen 📌 *Page path:* **Settings → Offline Updates (OUK)** *Components:* 1. **Drop Zone** – drag or select `.tar.gz` (max 1 GB). 2. **Progress Bar** – streaming upload with chunked HTTP. 3. **Verification Step** – backend returns status: * *Signature valid* ✔️ * *Digest mismatch* ❌ 4. **Feed Preview** – table shows *NVD date*, *OUI source build tag*, *CVE count delta*. 5. **Activate** – button issues `/feeds/activate/{id}`; on success the Dashboard “Feed Age” tile refreshes to green. 6. **History List** – previous OUK uploads with user, date, version; supports rollback. *All upload actions are recorded in the Policies → History audit log as type `ouk_update`.* ### 3.5 Plugins Panel 🛠 (ships after UI modularisation) Lists discovered UI plugins; each can inject routes/panels. Toggle on/off without reload. ### 3.6 Settings → **Quota & Tokens** (new) * View current **Client‑JWT claims** (tier, maxScansPerDay, expiry). * **Generate Offline Token** – admin‑only button → POST `/token/offline` (UI wraps the API). * Upload new token file for manual refresh. --- ## 4 i18n & l10n * JSON files under `/locales`. * Russian (`ru`) ships first‑class, translated security terms align with **GOST R ISO/IEC 27002‑2020**. * “Offline Update Kit” surfaces as **“Оффлайн‑обновление базы уязвимостей”** in Russian locale. * Community can add locales by uploading a new JSON via Plugins Panel once 🛠 ships. --- ## 5 Accessibility * WCAG 2.1 AA conformance targeted. * All color pairs pass contrast (checked by `vite-plugin-wcag`). * Keyboard navigation fully supported; focus outlines visible in both themes. --- ## 6 Theming 📌 | Layer | How to change | | --------------- | ------------------------------------------------------------ | | Tailwind | Palette variables under `tailwind.config.js > theme.colors`. | | Runtime toggle | Stored in `localStorage.theme`, synced across tabs. | | Plugin override | Future route plugins may expose additional palettes 🛠. | --- ## 7 Extensibility Hooks | Area | Contract | Example | | ------------- | ---------------------------------------- | ---------------------------------------------- | | New route | `window.stella.registerRoute()` | “Secrets” scanner plugin adds `/secrets` page. | | External link | `window.stella.addMenuLink(label, href)` | “Docs” link opens corporate Confluence. | | Theme | `window.stella.registerTheme()` | High‑contrast palette for accessibility. | --- ## 8 Road‑Map Tags | Feature | Status | | ------------------------- | ------ | | Policy Editor (YAML) | ✅ | | Inline Rego validation | 🛠 | | OUK Upload UI | ✅ | | Plugin Marketplace UI | 🚧 | | SLSA Verification banner | 🛠 | | Rekor Transparency viewer | 🚧 | --- ## 9 Non‑Commercial Usage Rules 📌 *(Extracted & harmonised from the Russian UI help page so that English docs remain licence‑complete.)* 1. **Free for internal security assessments.** 2. Commercial resale or SaaS re‑hosting **prohibited without prior written consent** under AGPL §13. 3. If you distribute a fork **with UI modifications**, you **must**: * Make the complete source code (including UI assets) publicly available. * Retain original project attribution in footer. 4. All dependencies listed in `ui/package.json` remain under their respective OSS licences (MIT, Apache 2.0, ISC). 5. Use in government‑classified environments must comply with **ФЗ‑187** export rules; consult your legal team. --- ## 10 Troubleshooting Tips | Symptom | Cause | Remedy | | ----------------------------------- | ----------------------------------- | ----------------------------------------------------------------- | | **White page** after login | `ui/dist/` hash mismatch | Clear browser cache; backend auto‑busts on version change. | | Policy editor shows “Unknown field” | YAML schema drift | Sync your policy file to latest sample in *Settings → Templates*. | | **OUK upload fails** at 99 % | Tarball built with outdated OUK CLI | Upgrade CLI (`ouk --version`) and rebuild package. | | Icons look broken in Safari | *SVG `mask` unsupported* | Use Safari 17+ or switch to PNG icon set in Settings > Advanced. | --- ## 11 Contributing * Run `npm dev` and open `http://localhost:5173`. * Ensure `ng lint` and `ng test` pass before PR. * Sign the **DCO** in your commit footer (`Signed-off-by`). --- ## 12 Change Log | Version | Date | Highlights | | ------- | ---------- | | v2.4 | 2025‑07‑15 | **Added full OUK Offline Update upload flow** – navigation node, Settings panel, dashboard linkage, audit hooks. | | v2.3 | 2025‑07‑14 | Added Policies module, SBOM Format & Registry settings, theming toggle, Δ‑SBOM indicators, extracted non‑commercial usage rules. | | v2.2 | 2025‑07‑12 | Added user tips/workflows, CI notes, DevSecOps section, troubleshooting, screenshots placeholders. | | v2.1 | 2025‑07‑12 | Removed PWA/Service‑worker; added oidc‑client‑ts; simplified roadmap | | v2.0 | 2025‑07‑12 | Accessibility, Storybook, perf budgets, security rules | | v1.1 | 2025‑07‑11 | Original OSS‑only guide | (End of Pragmatic UI Guide v2.2)