Add initial documentation
This commit is contained in:
234
docs/15_UI_GUIDE.md
Normal file
234
docs/15_UI_GUIDE.md
Normal file
@ -0,0 +1,234 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user