diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..06aa372 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,28 @@ +# SoftVisor Infrastructure Monitoring System + +In the following document, the project description is elaborated along with engineering constraints. + +# Goal of the project +SoftVisor GmbH operates a root-server running with Debian on it. On the server runs a Kubernets cluster where Gitea is installed for source control of the company's projects. We want to monitor the server in a way that we always know a software version drift, if vulnerabilities exist and to handle backups. On one hand we want to backup the applications running on kubernets. This means, the gitea and postgres data shall be backuped separately, not the entire cluster. + +# How does the application look like? +We want you to develop a web app with modern authentication. WIth the web app we want to see what applications are installed on Debian, we want to manage the kubernetes cluster and we want to manage backup strategies. + +# Use cases +In the following important use cases are described: + +1. Update Management of the OS and packages/applications + As a user I want to see the current OS version and all the packages and applications that are installed on it. For every package, application and even the OS we want to update the version. +2. Vulnerability Management + As a user I want to see current vulnerabilities of packages, applications, pods on kubernetes, images and OS. I want to get notified by E-Mail if new vulnerabilities are detected. +3. Backup Strategy Management + As a user I want to create backup strategies. A backup strategy consists of the application/data/kubernetes volume/image/etc.pp to be saved, the interval and the remote target where the backup should be stored. The remote target may be a samba server or FTP. +4. User management and authentification + As an admin, I want to create and manage users who have access to the application. + +# Engineering constraints +Please use Rust as backend and webserver, Vue.js and Tailwind CSS as Frontend. Please use clean code techniques and use clean architecture patterns. Do not over-engineer, be pragmatic. Write short and consistend code. For every feature requested, commit and push the changes you did. Always make a plan and decide which options is the best to choose from in order to develop a feature. If you are unsure, please ask immediately for clarification. Use modern authentification techniques, and if required modern encryption. +Test-driven development is mandatory: when planning a new feature, plan and implement the tests BEFORE the feature implementation. Tests means unit tests, integration tests where applicable and UI tests. Write the test cases first (red), then implement the feature until they pass (green), then refactor. + +# Server access +The Debian root server is reachable via the SSH config alias `softvisor` (`ssh softvisor`). Use it to inspect the host, the Kubernetes cluster and to deploy/test the application on the real target. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..fc4ff4d --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,358 @@ +# SoftVisor Infrastructure Monitoring System – Roadmap + +Status: Draft v1 (2026-09-02) + +This document is derived from `CLAUDE.md`. It breaks the project into work packages (WPs), +fixes the technical decisions that are not dictated by `CLAUDE.md`, and lists the open +questions that must be answered before the affected WP starts. + +--- + +## 1. Analysis of the requirements + +### 1.1 What we are building + +A single web application that monitors and manages one Debian root server which hosts a +Kubernetes cluster with Gitea (and its PostgreSQL database). Four functional areas: + +| # | Area | Core capability | +|---|------|-----------------| +| 1 | Update management | Show OS + installed packages/apps with versions; trigger updates | +| 2 | Vulnerability management | Show CVEs for OS, packages, apps, pods, images; e-mail on new findings | +| 3 | Backup management | Define backup strategies (source, interval, target SMB/FTP); run them | +| 4 | User management | Admin creates/manages users; modern auth | + +### 1.2 Constraints from CLAUDE.md + +- Backend and web server: **Rust** +- Frontend: **Vue.js + Tailwind CSS** +- Clean architecture, pragmatic, no over-engineering, short consistent code +- Commit and push after every feature +- Modern authentication and, where needed, modern encryption +- Ask for clarification when unsure +- **TDD is mandatory:** for every feature, plan and implement the tests (unit, integration + where applicable, UI) *before* the feature code. Red → green → refactor. + +### 1.3 Key observations that shape the architecture + +1. **The app must execute privileged actions on the host** (apt, kubectl, reading volumes). + The safest pragmatic option is to run the backend *on the server itself* as a systemd + service (or as a pod with host access) and talk to `apt`, the Kubernetes API and the + filesystem locally. No remote SSH agent layer is needed for a single server. +2. **Backups are application-level, not cluster-level.** Gitea data (repositories, LFS, + attachments on its PVC) and PostgreSQL (`pg_dump`) are backed up separately. Kubernetes + manifests can optionally be exported as a third source. Velero or full-cluster snapshots + are explicitly *out of scope*. +3. **Vulnerability data needs an external scanner.** Writing a CVE matcher ourselves is + over-engineering. **Trivy** covers all requested targets (Debian packages via + `trivy rootfs /`, container images, Kubernetes resources) with one tool and JSON output. +4. **Single-tenant, few users.** A local user store with strong password hashing and + short-lived JWT + refresh tokens is sufficient. OIDC/SSO is a possible later addition, + not a requirement. +5. **Scheduling is a cross-cutting concern.** Package scans, vulnerability scans and backups + all run on intervals. One internal scheduler (cron-expressions, persisted state) serves + all three. +6. **TDD drives the design.** Host commands (apt, kubectl, trivy, smbclient) sit behind + traits so use cases can be unit-tested with fakes. Every WP starts by writing its tests + against the planned API/UI, which also fixes the interface before implementation. + +--- + +## 2. Technical decisions + +| Topic | Decision | Rationale | +|-------|----------|-----------| +| Web framework | `axum` + `tokio` | Mature, minimal, tower middleware ecosystem | +| Database | SQLite via `sqlx` (compile-time checked queries, migrations) | Single-server app; zero ops; easy backup of the app itself. Switch to Postgres only if ever needed | +| Auth | Argon2id password hashing, JWT access token (15 min) + rotating refresh token (HttpOnly cookie), optional TOTP 2FA in a later WP | Modern, stateless API auth, no external IdP needed | +| Secrets at rest (SMB/FTP credentials, SMTP password) | AES-256-GCM with a master key from env/file | Required by "modern encryption" for stored credentials | +| Package inventory | `apt list --installed` / `dpkg-query` + `apt-get -s upgrade` for available versions; `/etc/os-release` for OS | No extra deps; exact data the OS has | +| Package updates | `apt-get install --only-upgrade ` / `apt-get dist-upgrade` executed via a narrowly scoped `sudoers` rule; live log streamed to UI | Least privilege, auditable | +| Kubernetes access | `kube-rs` with in-cluster or kubeconfig auth | Native Rust client, typed, watch support | +| Vulnerability scanning | Trivy CLI (JSON output), invoked by the backend | One tool for OS, images, k8s; well maintained DB | +| E-mail | `lettre` (SMTP, STARTTLS/TLS) | Standard Rust mail crate | +| Backup execution | Gitea: tar of PVC data (via `kubectl exec` or hostPath); Postgres: `pg_dump` via `kubectl exec`; optional: manifest export. Compress + optional AES-GCM encrypt, then upload | Application-consistent, restorable without the cluster | +| Backup targets | SMB via `smbclient`/mount, FTP/FTPS via `suppaftp` | Both requested; use proven tooling rather than reimplementing SMB | +| Scheduler | In-process `tokio-cron-scheduler`, jobs persisted in SQLite | One scheduler for scans + backups | +| Frontend | Vue 3 (Composition API, `