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
11 KiB
11 KiB
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/tokenscripts. No openssl.pkg-config --libs libsystemdworks in the shell. - P0-2
Cargo.tomlwith[[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). Addotel.headers,otel.metrics.*allowlists andlimits.*. Validate the auth-disabled + non-loopback combination. - P0-5
config.example.tomlcovering every key, with comments - P0-6 Shared DTOs in
src/sources/mod.rswith serde + schemars derives and RFC3339 timestamps. Service-only fields areOption. - P0-7 Source traits plus in-memory fakes (
src/sources/fake.rs) - P0-8
error.rs:AppErrormapped to HTTP status + JSON body and to MCPErrorData - P0-9
src/state.rs:AppState(sources, optional DB pool, config,CancellationToken) - P0-10 Stub every module with its final signatures.
main.rsdispatchesserve/token/--print-configto them. - P0-11 Unit tests for config precedence and validation
- Gate:
slinuxm serve --print-configprints effective config. Build, clippy, fmt and test are clean.cargo tree -i opensslis empty.
Phase 1 — Sources + auth (parallel)
WS-A systemd · card
- A1 Shared system-bus
zbus::Connection+ManagerProxy - A2
list_units(state)mapped toUnitSummary - A3
list_timers()via*.timerunits +TimerProxyprops (noListTimersmethod exists) - A4
unit_status(name):GetUnitonly (read-only;LoadUnitis never called, an unloaded unit is NotFound).Unitprops always,Serviceprops for.serviceonly. - A5 Unit-name validation.
NoSuchUnitmaps toNotFound. - A6
examples/systemd_dump.rsprints 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,linescapped bylimits.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::Dockeron the configured socket. Missing or denied socket maps toUnavailable. - 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
tailcapped 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, dir0700, 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|revokeCLI wired via the Phase 0 stub - D5 Bearer middleware: sha256 + indexed lookup of non-revoked tokens. 401 +
WWW-AuthenticateJSON on failure. - D6 Middleware exposed as a layer for the protected router only.
/healthzstays 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/followSSE with keep-alive. Ends on disconnect or shutdown. - E5
GET /docker/ps,/docker/containers/{name},/docker/containers/{name}/logs(JSON, or SSE withfollow=1) - E6
GET /healthzon 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
TrackerServicewith#[tool_router]and 8 tools - F2
tail_journalcapped bylimits.max_follow_secsand an entry cap - F3
get_container_logstail 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 }andcontainer_health_report {} - F7 Resources
systemd://units/failedanddocker://containers, read live, no subscriptions - F8
mcp::service(state)returnsStreamableHttpServicewith 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 hasservice.name,service.version,host.name. Returns a guard. - G2
tracingsubscriber: fmt to stderr +tracing-opentelemetrylayer when enabled - G3 Metrics poll loop feeds a snapshot. Observable gauges read it, so vanished series drop out.
- G4 Metric set from
plan.mdwith 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.yamlwith a debug exporter, plus a devenv process to run it
Phase 3 — Integration & hardening · card
- I1
main.rswiring: 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.servicerunningslinuxm serve:StateDirectory=,ProtectSystem=strict,NoNewPrivileges,SupplementaryGroups=systemd-journal, docker group commented (DEC-6) (verified only by systemd-analyze security --offline = 1.5 OK and asystemd-run --userrun 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:
lddshows only libc + libsystemd and its deps. Record binary size. - I6 Full manual Verification #1–#6 from
plan.mdpasses 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 --cacertand an/mcpinitialize over HTTPS
WS-H NixOS · card
- H1
nix/package.nix:buildRustPackagefromCargo.lockwith pkg-config, cmake, systemd. Binaryslinuxm. - H2
flake.nixwithpackages.default,nixosModules.defaultandchecks - H3
nix/module.nixoptions:enable,package,port(default 1984),bind(default loopback),tls.*,openFirewall,allowedHosts,docker.enable,settings,environmentFile - H4 Service: dedicated user,
StateDirectory0700,systemd-journalgroup, 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
openFirewallplus 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 buildandnix flake checkpass.lddshows no openssl. A fresh NixOS host serves:1984and 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_journalcall or docker follow pins aspawn_blockingthread for up tolimits.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 hardtokio::time::timeoutaround the producer. - F-2 Bound line and message length. Docker
LineSplitterand journalMESSAGEare 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, narrowerRestrictAddressFamilies,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.