Files
skyg-linux-tracker/TODO.md
T
ariandClaude Sonnet 5.5 34da657fdf WS-H: NixOS module, VM test, README section
Module: Origin/Host allowlists from allowedHosts and the FQDN, credentials
refreshed on reload so SIGHUP rotates the TLS cert, string cert/key paths
kept out of the store, docker.enable asserts virtualisation.docker.
VM test covers healthz, 401, token mint/revoke via sudo -u, /mcp, Origin 403,
root refusal and a TLS node. Package skips two unit tests that need host
state the sandbox lacks.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017WMgwyHQQU9cB4ruRDrKow
2026-10-16 17:15:18 -04:00

136 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# TODO — skyg-linux-tracker
Master checklist. **Tick boxes here only.** Card status lives on [`plan/BOARD.md`](plan/BOARD.md). Scope, owned files and design notes for each workstream live in [`plan/workstreams/`](plan/workstreams/).
Design: [`plan.md`](plan.md) · Review fixes: [`plan/review.md`](plan/review.md) · Open questions: [`plan/decisions.md`](plan/decisions.md)
## Before starting
- [x] Resolve **DEC-1**: binary and CLI are `slinuxm`
- [x] Accept or override the proposed decisions DEC-2 to DEC-7 (all accepted)
## Phase 0 — Foundation · [card](plan/workstreams/P0-foundation.md)
- [x] **P0-1** devenv: `pkg-config`, `systemd` (libsystemd.pc), `build`/`run`/`token` scripts. No openssl. `pkg-config --libs libsystemd` works in the shell.
- [x] **P0-2** `Cargo.toml` with `[[bin]] name = "slinuxm"` and every dependency pinned for all phases. rustls-only features. Release profile set to lto + strip.
- [x] **P0-3** Time-boxed API spike to confirm rmcp, zbus_systemd, systemd-journal and bollard APIs. Findings go in the card. Update DEC-8.
- [x] **P0-4** `config.rs`: figment layering (defaults < TOML < `SKYG_*` env with `__` nesting < CLI). Add `otel.headers`, `otel.metrics.*` allowlists and `limits.*`. Validate the auth-disabled + non-loopback combination.
- [x] **P0-5** `config.example.toml` covering every key, with comments
- [x] **P0-6** Shared DTOs in `src/sources/mod.rs` with serde + schemars derives and RFC3339 timestamps. Service-only fields are `Option`.
- [x] **P0-7** Source traits plus in-memory fakes (`src/sources/fake.rs`)
- [x] **P0-8** `error.rs`: `AppError` mapped to HTTP status + JSON body and to MCP `ErrorData`
- [x] **P0-9** `src/state.rs`: `AppState` (sources, optional DB pool, config, `CancellationToken`)
- [x] **P0-10** Stub every module with its final signatures. `main.rs` dispatches `serve` / `token` / `--print-config` to them.
- [x] **P0-11** Unit tests for config precedence and validation
- [x] **Gate:** `slinuxm serve --print-config` prints effective config. Build, clippy, fmt and test are clean. `cargo tree -i openssl` is empty.
## Phase 1 — Sources + auth (parallel)
### WS-A systemd · [card](plan/workstreams/WS-A-systemd.md)
- [x] **A1** Shared system-bus `zbus::Connection` + `ManagerProxy`
- [x] **A2** `list_units(state)` mapped to `UnitSummary`
- [x] **A3** `list_timers()` via `*.timer` units + `TimerProxy` props (no `ListTimers` method exists)
- [x] **A4** `unit_status(name)`: `GetUnit` only (read-only; `LoadUnit` is never called, an unloaded unit is NotFound). `Unit` props always, `Service` props for `.service` only.
- [x] **A5** Unit-name validation. `NoSuchUnit` maps to `NotFound`.
- [x] **A6** `examples/systemd_dump.rs` prints JSON from the live bus
- [x] **A7** Unit tests for timestamp conversion and property mapping
### WS-B journal · [card](plan/workstreams/WS-B-journal.md)
- [x] **B1** All sd-journal access inside `spawn_blocking`. Optional namespace, depending on the spike.
- [x] **B2** `query(filter)`: unit, priority ≤ N, `lines` capped by `limits.max_lines`, returned in chronological order
- [x] **B3** `follow(filter)` returns an mpsc receiver. `wait()` with a timeout. Exits on receiver drop or shutdown.
- [x] **B4** Entry mapping with lossy UTF-8 for binary `MESSAGE`
- [x] **B5** `examples/journal_tail.rs`
- [x] **B6** Test: the follow thread exits after its receiver is dropped
### WS-C docker · [card](plan/workstreams/WS-C-docker.md)
- [x] **C1** Lazy `bollard::Docker` on the configured socket. Missing or denied socket maps to `Unavailable`.
- [x] **C2** `ps()`: list + concurrent bounded inspect (health, uptime, restarts, image)
- [x] **C3** `container_status(name)`
- [x] **C4** `logs(name, follow, tail, since)` stream that stops on drop or shutdown
- [x] **C5** `tail` capped by config
- [x] **C6** `examples/docker_ps.rs` + log follow
- [ ] **C7** *(nice-to-have)* Smoke test against the Podman socket
### WS-D auth + DB · [card](plan/workstreams/WS-D-auth.md)
- [x] **D1** `db.rs`: open-or-create, dir `0700`, WAL, `busy_timeout`, embedded migrations
- [x] **D2** Migration for `tokens(id, name UNIQUE, token_hash UNIQUE, created_at, revoked_at, last_used_at)`
- [x] **D3** `tokens.rs`: create (32 random bytes, `slinuxm_` prefix, printed once), list, revoke. Uses runtime queries.
- [x] **D4** `slinuxm token create|list|revoke` CLI wired via the Phase 0 stub
- [x] **D5** Bearer middleware: sha256 + indexed lookup of non-revoked tokens. 401 + `WWW-Authenticate` JSON on failure.
- [x] **D6** Middleware exposed as a layer for the protected router only. `/healthz` stays public.
- [x] **D7** Tests: create, accept, revoke, reject. Unknown token is rejected. Startup refuses auth-off + non-loopback.
## Phase 2 — Surfaces (parallel)
### WS-E REST API · [card](plan/workstreams/WS-E-rest.md)
- [x] **E1** `api::router(state)` using axum 0.8 `{name}` path syntax
- [x] **E2** `GET /systemd/units?state=`, `/systemd/units/{name}`, `/systemd/timers`
- [x] **E3** `GET /journal?unit=&priority=&lines=` with validation
- [x] **E4** `GET /journal/follow` SSE with keep-alive. Ends on disconnect or shutdown.
- [x] **E5** `GET /docker/ps`, `/docker/containers/{name}`, `/docker/containers/{name}/logs` (JSON, or SSE with `follow=1`)
- [x] **E6** `GET /healthz` on the public router
- [x] **E7** Consistent JSON error body from `AppError`
- [x] **E8** Handler tests against fake sources (`tower::ServiceExt::oneshot`). Name/state validation is tested via a validating stub, not the fakes.
- [x] **E9** Docker unavailable returns 503 on docker routes only
### WS-F MCP · [card](plan/workstreams/WS-F-mcp.md)
- [x] **F1** `TrackerService` with `#[tool_router]` and 8 tools
- [x] **F2** `tail_journal` capped by `limits.max_follow_secs` and an entry cap
- [x] **F3** `get_container_logs` tail cap
- [x] **F4** `ServerHandler::get_info`: instructions + capabilities (tools, prompts, resources)
- [x] **F5** Tool descriptions that explain systemd states, health statuses and priorities
- [x] **F6** Prompts `diagnose_unit { name }` and `container_health_report {}`
- [x] **F7** Resources `systemd://units/failed` and `docker://containers`, read live, no subscriptions
- [x] **F8** `mcp::service(state)` returns `StreamableHttpService` with Origin validation (DEC-8)
- [x] **F9** Tests: tool list snapshot + each tool against fakes
### WS-G OTel · [card](plan/workstreams/WS-G-otel.md)
- [x] **G1** `telemetry::init(cfg)`: OTLP grpc/http with headers. Resource has `service.name`, `service.version`, `host.name`. Returns a guard.
- [x] **G2** `tracing` subscriber: fmt to stderr + `tracing-opentelemetry` layer when enabled
- [x] **G3** Metrics poll loop feeds a snapshot. Observable gauges read it, so vanished series drop out.
- [x] **G4** Metric set from `plan.md` with semconv attribute names, allowlists and the DEC-7 default scope
- [x] **G5** Log export: journal follow + per-container docker follow, reconciled via the Docker events stream, with backoff
- [x] **G6** Shutdown cancels tasks and flushes all providers
- [x] **G7** `dev/otelcol.yaml` with a debug exporter, plus a devenv process to run it
## Phase 3 — Integration & hardening · [card](plan/workstreams/P3-integration.md)
- [x] **I1** `main.rs` wiring: protected router (`/api/v1` + `/mcp` + auth) merged with the public `/healthz`, `TraceLayer`, SIGTERM/SIGINT leading to cancel, drain and OTel flush
- [x] **I2** Automated negative tests (Verification #6)
- [x] **I3** `systemd/skyg-linux-tracker.service` running `slinuxm serve`: `StateDirectory=`, `ProtectSystem=strict`, `NoNewPrivileges`, `SupplementaryGroups=systemd-journal`, docker group commented (DEC-6) (verified only by systemd-analyze security --offline = 1.5 OK and a `systemd-run --user` run with the same sandbox properties; not installed as a system unit on a clean host)
- [x] **I4** README: install, config reference, token workflow, MCP client setup, hardened docker option
- [x] **I5** Release build: `ldd` shows only libc + libsystemd and its deps. Record binary size.
- [ ] **I6** Full manual Verification #1–#6 from `plan.md` passes on a real host
## Phase 4 — TLS and NixOS packaging
### WS-I TLS · [card](plan/workstreams/WS-I-tls.md)
- [x] **T1** Config `server.tls.{enabled,cert_file,key_file}` with validation and documented example keys
- [x] **T2** Serve over rustls with a single pinned crypto provider. No openssl.
- [x] **T3** Reload cert and key on SIGHUP without dropping connections. A bad cert keeps the old one.
- [x] **T4** MCP allowed origins use `https://` when TLS is on
- [x] **T5** Startup warning for non-loopback bind without TLS
- [x] **T6** Tests with a generated self-signed cert: HTTPS, 401/200 over TLS, plain HTTP rejected, SIGHUP reload, bad files, bounded shutdown
- [x] **T7** README TLS section
- [x] **T8** Live check with `curl --cacert` and an `/mcp` initialize over HTTPS
### WS-H NixOS · [card](plan/workstreams/WS-H-nixos.md)
- [x] **H1** `nix/package.nix`: `buildRustPackage` from `Cargo.lock` with pkg-config, cmake, systemd. Binary `slinuxm`.
- [x] **H2** `flake.nix` with `packages.default`, `nixosModules.default` and `checks`
- [x] **H3** `nix/module.nix` options: `enable`, `package`, `port` (default 1984), `bind` (default loopback), `tls.*`, `openFirewall`, `allowedHosts`, `docker.enable`, `settings`, `environmentFile`
- [x] **H4** Service: dedicated user, `StateDirectory` 0700, `systemd-journal` group, P3 hardening set, config at `/etc/skyg-linux-tracker.toml`
- [x] **H5** **CLI installed system-wide**, plain binary (DEC-10). Token commands refuse to run as root against another user's DB and print the `sudo -u skyg-linux-tracker …` command.
- [x] **H6** Firewall: global `openFirewall` plus interface-scoped option. Eval assertion: non-loopback bind requires auth.
- [x] **H7** README NixOS section: flake input, token workflow, exposure model, `allowedHosts`
- [x] **H8** NixOS VM test: healthz, 401, mint token via CLI (`sudo -u`), 200, `/mcp`, revoke, 401, bad Origin 403, plus a TLS case
- [ ] **Gate:** `nix build` and `nix flake check` pass. `ldd` shows no openssl. A fresh NixOS host serves `:1984` and a token can be minted from a login shell.
## Future
Logged from the final security review (2026-10-16). Not scheduled.
- [ ] **F-1** Cap concurrent follow streams. Each journal follow, `tail_journal` call or docker follow pins a `spawn_blocking` thread for up to `limits.max_follow_secs`. Add a global semaphore shared by REST and MCP (suggested 16) returning 429/503 when full. A client that stops reading may hold the thread past the deadline (untested); add a write timeout or a hard `tokio::time::timeout` around the producer.
- [ ] **F-2** Bound line and message length. Docker `LineSplitter` and journal `MESSAGE` are buffered without limit before the 256 KiB result cap applies. Truncate per line (suggested 64 KiB, with a visible marker) and cap total bytes collected.
- [ ] **F-3** Unit hardening: `ProtectKernelLogs`, `ProtectHostname`, `RemoveIPC`, `LimitNOFILE`, `TasksMax`, `MemoryMax`, narrower `RestrictAddressFamilies`, `PrivateUsers` (check journal group access). Test under the hardened unit on a clean host before enabling. Document how the service user gets read access to the TLS key.