diff --git a/flake.nix b/flake.nix new file mode 100644 index 0000000..5c95b5e --- /dev/null +++ b/flake.nix @@ -0,0 +1,32 @@ +{ + description = "skyg-linux-tracker: read-only systemd, journal and Docker monitor"; + + inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + + outputs = { self, nixpkgs }: + let + system = "x86_64-linux"; + systems = [ "x86_64-linux" "aarch64-linux" ]; + forAll = f: nixpkgs.lib.genAttrs systems (s: f nixpkgs.legacyPackages.${s}); + in + { + packages = forAll (pkgs: rec { + skyg-linux-tracker = pkgs.callPackage ./nix/package.nix { }; + default = skyg-linux-tracker; + }); + + nixosModules.default = { pkgs, lib, ... }: { + imports = [ ./nix/module.nix ]; + services.skyg-linux-tracker.package = + lib.mkDefault self.packages.${pkgs.stdenv.hostPlatform.system}.default; + }; + + checks.${system} = { + package = self.packages.${system}.default; + vm = import ./nix/tests/vm.nix { + pkgs = nixpkgs.legacyPackages.${system}; + module = self.nixosModules.default; + }; + }; + }; +} diff --git a/nix/module.nix b/nix/module.nix new file mode 100644 index 0000000..071ca56 --- /dev/null +++ b/nix/module.nix @@ -0,0 +1,204 @@ +{ config, lib, pkgs, ... }: + +let + cfg = config.services.skyg-linux-tracker; + inherit (lib) mkOption mkEnableOption mkIf types; + + name = "skyg-linux-tracker"; + credDir = "/run/credentials/${name}.service"; + toml = pkgs.formats.toml { }; + + moduleDefaults = { + server = { + bind = cfg.bind; + port = cfg.port; + allowed_hosts = lib.unique ([ + config.networking.hostName + "${config.networking.hostName}:${toString cfg.port}" + ] ++ cfg.allowedHosts); + } // lib.optionalAttrs cfg.tls.enable { + tls = { + enabled = true; + cert_file = "${credDir}/cert"; + key_file = "${credDir}/key"; + }; + }; + auth.db_path = "/var/lib/${name}/db.sqlite"; + } // lib.optionalAttrs cfg.docker.enable { + sources.docker_socket = "/var/run/docker.sock"; + }; + + settings = lib.recursiveUpdate moduleDefaults cfg.settings; + configFile = toml.generate "${name}.toml" settings; + + port = settings.server.port; + bind = settings.server.bind; + authEnabled = settings.auth.enabled or true; + isLoopback = a: lib.hasPrefix "127." a || a == "::1"; +in +{ + options.services.skyg-linux-tracker = { + enable = mkEnableOption "skyg-linux-tracker, a read-only systemd/journal/Docker monitor (REST, MCP, OTel)"; + + package = mkOption { + type = types.package; + description = "The skyg-linux-tracker package (provides `slinuxm`)."; + }; + + port = mkOption { + type = types.port; + default = 1984; + description = "TCP port for the REST API and /mcp."; + }; + + bind = mkOption { + type = types.str; + default = "127.0.0.1"; + description = '' + Listen address. A non-loopback address requires authentication to stay + enabled. Bearer tokens over plain HTTP are readable on a LAN; prefer + loopback plus a TLS proxy or Tailscale, or enable `tls`. + ''; + }; + + tls = { + enable = mkEnableOption "native TLS for REST and /mcp"; + certFile = mkOption { + type = types.nullOr types.path; + default = null; + description = "PEM certificate chain. Passed through systemd LoadCredential, so the service user needs no access to the original file."; + }; + keyFile = mkOption { + type = types.nullOr types.path; + default = null; + description = "PEM private key. Passed through systemd LoadCredential."; + }; + }; + + openFirewall = mkOption { + type = types.bool; + default = false; + description = "Open the port on all interfaces."; + }; + + firewallInterfaces = mkOption { + type = types.listOf types.str; + default = [ ]; + example = [ "enp3s0" ]; + description = "Open the port only on these interfaces (the recommended LAN setup)."; + }; + + allowedHosts = mkOption { + type = types.listOf types.str; + default = [ ]; + example = [ "monitor.lan:1984" ]; + description = "Extra Host/Origin names accepted on /mcp. `networking.hostName` is added automatically."; + }; + + docker.enable = mkEnableOption '' + Docker access by adding the service user to the `docker` group. + WARNING: that group is root-equivalent; prefer a read-only socket proxy + and `settings.sources.docker_socket`''; + + settings = mkOption { + type = toml.type; + default = { }; + example = { limits.max_lines = 500; }; + description = "Freeform config merged over the module defaults and written to /etc/skyg-linux-tracker.toml. Never put secrets here."; + }; + + environmentFile = mkOption { + type = types.nullOr types.path; + default = null; + example = "/run/secrets/skyg-linux-tracker.env"; + description = "systemd EnvironmentFile for secrets such as `SKYG_OTEL__HEADERS__AUTHORIZATION`, kept out of the store."; + }; + }; + + config = mkIf cfg.enable { + assertions = [ + { + assertion = isLoopback bind || authEnabled; + message = "services.skyg-linux-tracker: a non-loopback bind (${bind}) requires auth.enabled = true."; + } + { + assertion = !cfg.tls.enable || (cfg.tls.certFile != null && cfg.tls.keyFile != null); + message = "services.skyg-linux-tracker.tls.enable requires tls.certFile and tls.keyFile."; + } + ]; + + users.users.${name} = { + isSystemUser = true; + group = name; + extraGroups = lib.optional cfg.docker.enable "docker"; + }; + users.groups.${name} = { }; + + # Same path the app reads by default, so `slinuxm` and the service agree. + environment.etc."${name}.toml".source = configFile; + + # Plain binary, no wrapper. Mint tokens with + # sudo -u skyg-linux-tracker slinuxm token create + environment.systemPackages = [ cfg.package ]; + + networking.firewall = lib.mkMerge [ + (mkIf cfg.openFirewall { allowedTCPPorts = [ port ]; }) + { + interfaces = lib.genAttrs cfg.firewallInterfaces (_: { + allowedTCPPorts = [ port ]; + }); + } + ]; + + systemd.services.${name} = { + description = "skyg-linux-tracker: read-only systemd, journal and Docker monitor (REST, MCP, OTel)"; + wantedBy = [ "multi-user.target" ]; + after = [ "network.target" ] ++ lib.optional cfg.docker.enable "docker.service"; + restartTriggers = [ configFile ]; + + # Mirrors systemd/skyg-linux-tracker.service; keep the two in step. + serviceConfig = { + Type = "simple"; + ExecStart = "${lib.getExe cfg.package} serve --config /etc/${name}.toml"; + ExecReload = "${pkgs.coreutils}/bin/kill -HUP $MAINPID"; + Restart = "on-failure"; + RestartSec = 5; + TimeoutStopSec = 30; + + User = name; + Group = name; + SupplementaryGroups = [ "systemd-journal" ] ++ lib.optional cfg.docker.enable "docker"; + StateDirectory = name; + StateDirectoryMode = "0700"; + EnvironmentFile = mkIf (cfg.environmentFile != null) cfg.environmentFile; + LoadCredential = mkIf cfg.tls.enable [ + "cert:${toString cfg.tls.certFile}" + "key:${toString cfg.tls.keyFile}" + ]; + + NoNewPrivileges = true; + ProtectSystem = "strict"; + ProtectHome = true; + PrivateTmp = true; + PrivateDevices = true; + ProtectKernelTunables = true; + ProtectKernelModules = true; + ProtectControlGroups = true; + ProtectClock = true; + RestrictAddressFamilies = [ "AF_UNIX" "AF_INET" "AF_INET6" ]; + RestrictNamespaces = true; + RestrictRealtime = true; + LockPersonality = true; + MemoryDenyWriteExecute = true; + SystemCallArchitectures = "native"; + SystemCallFilter = [ "@system-service" "~@privileged @resources" ]; + ProtectProc = "invisible"; + ProcSubset = "pid"; + RestrictSUIDSGID = true; + UMask = "0077"; + CapabilityBoundingSet = ""; + AmbientCapabilities = ""; + }; + }; + }; +} diff --git a/nix/package.nix b/nix/package.nix new file mode 100644 index 0000000..1c4caf2 --- /dev/null +++ b/nix/package.nix @@ -0,0 +1,33 @@ +{ lib, rustPlatform, pkg-config, cmake, systemd }: + +rustPlatform.buildRustPackage { + pname = "skyg-linux-tracker"; + version = (lib.importTOML ../Cargo.toml).package.version; + + src = lib.fileset.toSource { + root = ../.; + fileset = lib.fileset.unions [ + ../Cargo.toml + ../Cargo.lock + ../config.example.toml + ../migrations + ../src + ../tests + ../examples + ]; + }; + + cargoLock.lockFile = ../Cargo.lock; + + # cmake: aws-lc-sys. Live-journal tests are #[ignore], so the sandbox runs + # the rest of the suite. + nativeBuildInputs = [ pkg-config cmake ]; + buildInputs = [ systemd ]; + + meta = { + description = "Read-only Linux system monitor: systemd, journald and Docker over REST, MCP and OpenTelemetry"; + license = lib.licenses.mit; + mainProgram = "slinuxm"; + platforms = lib.platforms.linux; + }; +} diff --git a/plan/BOARD.md b/plan/BOARD.md index 39df37b..7b3bf10 100644 --- a/plan/BOARD.md +++ b/plan/BOARD.md @@ -1,6 +1,6 @@ # Board -_Last updated: 2026-10-15_ +_Last updated: 2026-10-16_ Move a card by cutting its row into another column. Keep the card's own **Status** field in sync. Rules are in [`README.md`](README.md). @@ -26,36 +26,35 @@ Move a card by cutting its row into another column. Keep the card's own **Status | Card | Owner | PR | |---|---|---| -| [P0 Foundation](workstreams/P0-foundation.md) | — | branch `p0/foundation` | +| [P3 Integration](workstreams/P3-integration.md) | — | merged to `main`; I6 (manual Verification #1–#6 on a real host) outstanding | ## Done | Card | Completed | |---|---| -| — | | +| [P0 Foundation](workstreams/P0-foundation.md) | merged to `main` | +| [WS-A systemd](workstreams/WS-A-systemd.md) | merged to `main` | +| [WS-B journal](workstreams/WS-B-journal.md) | merged to `main` | +| [WS-C docker](workstreams/WS-C-docker.md) | merged to `main` | +| [WS-D auth + DB](workstreams/WS-D-auth.md) | merged to `main` | +| [WS-E REST](workstreams/WS-E-rest.md) | merged to `main` | +| [WS-F MCP](workstreams/WS-F-mcp.md) | merged to `main` | +| [WS-G OTel](workstreams/WS-G-otel.md) | merged to `main` | +| [WS-I TLS](workstreams/WS-I-tls.md) | merged to `main` | ## Backlog | Card | Waiting on | |---|---| -| [WS-A systemd](workstreams/WS-A-systemd.md) | P0 | -| [WS-B journal](workstreams/WS-B-journal.md) | P0 | -| [WS-C docker](workstreams/WS-C-docker.md) | P0 | -| [WS-D auth + DB](workstreams/WS-D-auth.md) | P0 | -| [WS-E REST](workstreams/WS-E-rest.md) | P0 to start; A, B, C, D to finish | -| [WS-F MCP](workstreams/WS-F-mcp.md) | P0 to start; A, B, C, D to finish | -| [WS-G OTel](workstreams/WS-G-otel.md) | P0 to start; A, B, C to finish | -| [P3 Integration](workstreams/P3-integration.md) | E, F, G | -| [WS-I TLS](workstreams/WS-I-tls.md) | P3 | -| [WS-H NixOS](workstreams/WS-H-nixos.md) | P3, WS-I | +| [WS-H NixOS](workstreams/WS-H-nixos.md) | P3 (I6 verification) | ## Milestones | Milestone | Gate | Status | |---|---|---| -| M0 Skeleton | `slinuxm serve --print-config` works. Clippy and tests are clean. No openssl. | 🟨 in review | -| M1 Sources live | All four Phase 1 examples run against a real host | ⬜ | +| M0 Skeleton | `slinuxm serve --print-config` works. Clippy and tests are clean. No openssl. | ✅ | +| M1 Sources live | All four Phase 1 examples run against a real host | 🟨 systemd, journal and docker verified live; merged | | M2 Surfaces | Verification #3, #4 and #5 pass | 🟨 #3 and #4 verified live on 2026-10-15; #5 (OTel smoke test) not run, no otelcol-contrib binary | | M3 Release | Verification #1–#6 pass. Unit file and README shipped. | ⬜ | | M4 NixOS | `nix flake check` passes including the VM test. `:1984` serves and a token is minted with the system-installed CLI. | ⬜ | -| M5 TLS | HTTPS serves REST and `/mcp`, SIGHUP reloads certs, no openssl. | 🟨 verified on ws-i/tls, not merged | +| M5 TLS | HTTPS serves REST and `/mcp`, SIGHUP reloads certs, no openssl. | ✅ merged to `main` | diff --git a/plan/workstreams/P0-foundation.md b/plan/workstreams/P0-foundation.md index ae0b82c..13f23f5 100644 --- a/plan/workstreams/P0-foundation.md +++ b/plan/workstreams/P0-foundation.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Review | +| Status | Done | | Owner | — | | Phase | 0 (blocking, single track) | | Depends on | — | diff --git a/plan/workstreams/WS-A-systemd.md b/plan/workstreams/WS-A-systemd.md index 817d2d4..368ca5b 100644 --- a/plan/workstreams/WS-A-systemd.md +++ b/plan/workstreams/WS-A-systemd.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Review | +| Status | Done | | Owner | — | | Phase | 1 (parallel) | | Depends on | P0 | diff --git a/plan/workstreams/WS-B-journal.md b/plan/workstreams/WS-B-journal.md index ab7b1ca..983d2ea 100644 --- a/plan/workstreams/WS-B-journal.md +++ b/plan/workstreams/WS-B-journal.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Review | +| Status | Done | | Owner | — | | Phase | 1 (parallel) | | Depends on | P0 (incl. spike findings on the `systemd` crate) | diff --git a/plan/workstreams/WS-C-docker.md b/plan/workstreams/WS-C-docker.md index 3083dc0..75f4e1a 100644 --- a/plan/workstreams/WS-C-docker.md +++ b/plan/workstreams/WS-C-docker.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Review | +| Status | Done | | Owner | — | | Phase | 1 (parallel) | | Depends on | P0 | diff --git a/plan/workstreams/WS-D-auth.md b/plan/workstreams/WS-D-auth.md index f21eab8..b48db6f 100644 --- a/plan/workstreams/WS-D-auth.md +++ b/plan/workstreams/WS-D-auth.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Backlog | +| Status | Done | | Owner | — | | Phase | 1 (parallel) | | Depends on | P0 | diff --git a/plan/workstreams/WS-E-rest.md b/plan/workstreams/WS-E-rest.md index eda9a81..bc9a0d5 100644 --- a/plan/workstreams/WS-E-rest.md +++ b/plan/workstreams/WS-E-rest.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Done (pending merge) | +| Status | Done | | Owner | — | | Phase | 2 (parallel) | | Depends on | P0 to start (fakes). A, B, C, D to finish. | diff --git a/plan/workstreams/WS-F-mcp.md b/plan/workstreams/WS-F-mcp.md index 6499cfa..98d8a62 100644 --- a/plan/workstreams/WS-F-mcp.md +++ b/plan/workstreams/WS-F-mcp.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Backlog | +| Status | Done | | Owner | — | | Phase | 2 (parallel) | | Depends on | P0 to start (fakes, spike findings). A, B, C, D to finish. | diff --git a/plan/workstreams/WS-G-otel.md b/plan/workstreams/WS-G-otel.md index 2686d4c..2e9ba63 100644 --- a/plan/workstreams/WS-G-otel.md +++ b/plan/workstreams/WS-G-otel.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Review | +| Status | Done | | Owner | — | | Phase | 2 (parallel) | | Depends on | P0 to start (fakes, spike findings). A, B, C to finish. | diff --git a/plan/workstreams/WS-I-tls.md b/plan/workstreams/WS-I-tls.md index 68074d7..7a1f058 100644 --- a/plan/workstreams/WS-I-tls.md +++ b/plan/workstreams/WS-I-tls.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Done on `ws-i/tls` (not merged) | +| Status | Done | | Owner | — | | Phase | 4 (single track, after P3, before WS-H) | | Depends on | P3 |