master
1e41ba7ffa
- Added NotifyPanelComponent for managing notification channels and rules. - Implemented reactive forms for channel and rule management. - Created unit tests for NotifyPanelComponent to validate functionality. - Developed MockNotifyApiService to simulate API interactions for testing. - Added mock data for channels, rules, and deliveries to facilitate testing. - Introduced RuntimeEventFactoryTests to ensure correct event creation with build ID.
265 lines
14 KiB
Markdown
Executable File
265 lines
14 KiB
Markdown
Executable File
# 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 {{ angular }}** + 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.org/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 / {{ quota_token }}**; turns yellow at **≤ 10% remaining** (≈ 90% used),
|
||
red at {{ quota_token }} .
|
||
* **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.3.2 Preview / Report Fixtures
|
||
|
||
- Use the offline fixtures (`samples/policy/policy-preview-unknown.json` and `samples/policy/policy-report-unknown.json`) to exercise the Policies screens without a live backend; both payloads include confidence bands, unknown-age tags, and scoring inputs that map directly to the UI panels.
|
||
- Keep them in lock-step with the API by validating any edits with Ajv:
|
||
|
||
```bash
|
||
# install once per checkout (offline-safe):
|
||
npm install --no-save ajv-cli@5 ajv-formats@2
|
||
|
||
npx ajv validate --spec=draft2020 -c ajv-formats \
|
||
-s docs/schemas/policy-preview-sample@1.json \
|
||
-d samples/policy/policy-preview-unknown.json
|
||
|
||
npx ajv validate --spec=draft2020 -c ajv-formats \
|
||
-s docs/schemas/policy-report-sample@1.json \
|
||
-d samples/policy/policy-report-unknown.json
|
||
```
|
||
|
||
### 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.
|
||
|
||
### 3.7 Notifications Panel (new)
|
||
|
||
Route: **`/notify`** (header shortcut “Notify”). The panel now exposes every Notify control-plane primitive without depending on the backend being online.
|
||
|
||
| Area | What you can do |
|
||
| --- | --- |
|
||
| **Channels** | Create/edit Slack/Teams/Email/Webhook channels, toggle enablement, maintain labels/metadata, and execute **test send** previews. Channel health cards show mocked status + trace IDs so ops can validate wiring before Notify.WebService is reachable. |
|
||
| **Rules** | Manage routing rules (matchers, severity gates, throttles/digests, locale hints). A single-action form keeps Signal-style configuration quick while mirroring Notify schema (`match`, `actions[]`). |
|
||
| **Deliveries** | Browsable ledger with status filter (All/Sent/Failed/Throttled/…), showing targets, kinds, and timestamps so operators confirm noise controls. |
|
||
|
||
The component leans on the mocked Notify API service in `src/app/testing/mock-notify-api.service.ts`, meaning Offline Kit demos run instantly yet the view stays API-shaped (same DTOs + tenant header expectations).
|
||
|
||
---
|
||
|
||
## 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**applicable local regulations** governing cryptography and software distribution.
|
||
|
||
---
|
||
|
||
## 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)
|