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

11 KiB
Raw Blame History

TODO — skyg-linux-tracker

Master checklist. Tick boxes here only. Card status lives on plan/BOARD.md. Scope, owned files and design notes for each workstream live in plan/workstreams/.

Design: plan.md · Review fixes: plan/review.md · Open questions: plan/decisions.md

Before starting

  • Resolve DEC-1: binary and CLI are slinuxm
  • Accept or override the proposed decisions DEC-2 to DEC-7 (all accepted)

Phase 0 — Foundation · card

  • P0-1 devenv: pkg-config, systemd (libsystemd.pc), build/run/token scripts. No openssl. pkg-config --libs libsystemd works in the shell.
  • P0-2 Cargo.toml with [[bin]] name = "slinuxm" and every dependency pinned for all phases. rustls-only features. Release profile set to lto + strip.
  • P0-3 Time-boxed API spike to confirm rmcp, zbus_systemd, systemd-journal and bollard APIs. Findings go in the card. Update DEC-8.
  • 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.
  • P0-5 config.example.toml covering every key, with comments
  • P0-6 Shared DTOs in src/sources/mod.rs with serde + schemars derives and RFC3339 timestamps. Service-only fields are Option.
  • P0-7 Source traits plus in-memory fakes (src/sources/fake.rs)
  • P0-8 error.rs: AppError mapped to HTTP status + JSON body and to MCP ErrorData
  • P0-9 src/state.rs: AppState (sources, optional DB pool, config, CancellationToken)
  • P0-10 Stub every module with its final signatures. main.rs dispatches serve / token / --print-config to them.
  • P0-11 Unit tests for config precedence and validation
  • 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

  • A1 Shared system-bus zbus::Connection + ManagerProxy
  • A2 list_units(state) mapped to UnitSummary
  • A3 list_timers() via *.timer units + TimerProxy props (no ListTimers method exists)
  • 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.
  • A5 Unit-name validation. NoSuchUnit maps to NotFound.
  • A6 examples/systemd_dump.rs prints JSON from the live bus
  • A7 Unit tests for timestamp conversion and property mapping

WS-B journal · card

  • B1 All sd-journal access inside spawn_blocking. Optional namespace, depending on the spike.
  • B2 query(filter): unit, priority ≤ N, lines capped by limits.max_lines, returned in chronological order
  • B3 follow(filter) returns an mpsc receiver. wait() with a timeout. Exits on receiver drop or shutdown.
  • B4 Entry mapping with lossy UTF-8 for binary MESSAGE
  • B5 examples/journal_tail.rs
  • B6 Test: the follow thread exits after its receiver is dropped

WS-C docker · card

  • C1 Lazy bollard::Docker on the configured socket. Missing or denied socket maps to Unavailable.
  • C2 ps(): list + concurrent bounded inspect (health, uptime, restarts, image)
  • C3 container_status(name)
  • C4 logs(name, follow, tail, since) stream that stops on drop or shutdown
  • C5 tail capped by config
  • C6 examples/docker_ps.rs + log follow
  • C7 (nice-to-have) Smoke test against the Podman socket

WS-D auth + DB · card

  • D1 db.rs: open-or-create, dir 0700, WAL, busy_timeout, embedded migrations
  • D2 Migration for tokens(id, name UNIQUE, token_hash UNIQUE, created_at, revoked_at, last_used_at)
  • D3 tokens.rs: create (32 random bytes, slinuxm_ prefix, printed once), list, revoke. Uses runtime queries.
  • D4 slinuxm token create|list|revoke CLI wired via the Phase 0 stub
  • D5 Bearer middleware: sha256 + indexed lookup of non-revoked tokens. 401 + WWW-Authenticate JSON on failure.
  • D6 Middleware exposed as a layer for the protected router only. /healthz stays public.
  • 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

  • E1 api::router(state) using axum 0.8 {name} path syntax
  • E2 GET /systemd/units?state=, /systemd/units/{name}, /systemd/timers
  • E3 GET /journal?unit=&priority=&lines= with validation
  • E4 GET /journal/follow SSE with keep-alive. Ends on disconnect or shutdown.
  • E5 GET /docker/ps, /docker/containers/{name}, /docker/containers/{name}/logs (JSON, or SSE with follow=1)
  • E6 GET /healthz on the public router
  • E7 Consistent JSON error body from AppError
  • E8 Handler tests against fake sources (tower::ServiceExt::oneshot). Name/state validation is tested via a validating stub, not the fakes.
  • E9 Docker unavailable returns 503 on docker routes only

WS-F MCP · card

  • F1 TrackerService with #[tool_router] and 8 tools
  • F2 tail_journal capped by limits.max_follow_secs and an entry cap
  • F3 get_container_logs tail cap
  • F4 ServerHandler::get_info: instructions + capabilities (tools, prompts, resources)
  • F5 Tool descriptions that explain systemd states, health statuses and priorities
  • F6 Prompts diagnose_unit { name } and container_health_report {}
  • F7 Resources systemd://units/failed and docker://containers, read live, no subscriptions
  • F8 mcp::service(state) returns StreamableHttpService with Origin validation (DEC-8)
  • F9 Tests: tool list snapshot + each tool against fakes

WS-G OTel · card

  • G1 telemetry::init(cfg): OTLP grpc/http with headers. Resource has service.name, service.version, host.name. Returns a guard.
  • G2 tracing subscriber: fmt to stderr + tracing-opentelemetry layer when enabled
  • G3 Metrics poll loop feeds a snapshot. Observable gauges read it, so vanished series drop out.
  • G4 Metric set from plan.md with semconv attribute names, allowlists and the DEC-7 default scope
  • G5 Log export: journal follow + per-container docker follow, reconciled via the Docker events stream, with backoff
  • G6 Shutdown cancels tasks and flushes all providers
  • G7 dev/otelcol.yaml with a debug exporter, plus a devenv process to run it

Phase 3 — Integration & hardening · card

  • 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
  • I2 Automated negative tests (Verification #6)
  • 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)
  • I4 README: install, config reference, token workflow, MCP client setup, hardened docker option
  • 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

  • T1 Config server.tls.{enabled,cert_file,key_file} with validation and documented example keys
  • T2 Serve over rustls with a single pinned crypto provider. No openssl.
  • T3 Reload cert and key on SIGHUP without dropping connections. A bad cert keeps the old one.
  • T4 MCP allowed origins use https:// when TLS is on
  • T5 Startup warning for non-loopback bind without TLS
  • T6 Tests with a generated self-signed cert: HTTPS, 401/200 over TLS, plain HTTP rejected, SIGHUP reload, bad files, bounded shutdown
  • T7 README TLS section
  • T8 Live check with curl --cacert and an /mcp initialize over HTTPS

WS-H NixOS · card

  • H1 nix/package.nix: buildRustPackage from Cargo.lock with pkg-config, cmake, systemd. Binary slinuxm.
  • H2 flake.nix with packages.default, nixosModules.default and checks
  • H3 nix/module.nix options: enable, package, port (default 1984), bind (default loopback), tls.*, openFirewall, allowedHosts, docker.enable, settings, environmentFile
  • H4 Service: dedicated user, StateDirectory 0700, systemd-journal group, P3 hardening set, config at /etc/skyg-linux-tracker.toml
  • 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.
  • H6 Firewall: global openFirewall plus interface-scoped option. Eval assertion: non-loopback bind requires auth.
  • H7 README NixOS section: flake input, token workflow, exposure model, allowedHosts
  • 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.