diff --git a/README.md b/README.md index 2a7e67e..30d2ae2 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,11 @@ sudo -u skyg slinuxm token revoke my-laptop --config /etc/skyg-linux-tracker.tom Revocation takes effect immediately; no restart is needed. +Notes: + +- `auth.db_path` must stay under the unit's `StateDirectory` (`/var/lib/skyg-linux-tracker`). The unit uses `ProtectSystem=strict`, so any other location needs a matching `ReadWritePaths=`. +- `token create` needs the state directory to exist, so start the service once first (systemd creates it with the right owner), then run the CLI as `skyg`. + ## REST Base: `http://127.0.0.1:9109`. Errors are `{"error":{"code","message"}}`. @@ -104,7 +109,7 @@ curl -si -X POST http://127.0.0.1:9109/mcp \ ### Origin and Host checks -`/mcp` validates `Origin` and `Host` to defend against DNS rebinding from browsers. Loopback names, `server.bind` and the configured port are accepted by default. Requests without an `Origin` header (non-browser clients) pass this check, so the bearer token remains the real gate. If you bind to `0.0.0.0` or serve behind a name, add the names clients use to `server.allowed_hosts` (for example `["monitor.lan:9109"]`) and any browser origins to `server.allowed_origins`. Terminate TLS in a reverse proxy if the host is reachable beyond a trusted network; the server itself speaks plain HTTP. +`/mcp` validates `Origin` and `Host` to defend against DNS rebinding from browsers. Loopback names, `server.bind` and the configured port are accepted by default. Requests without an `Origin` header (non-browser clients) pass this check, so the bearer token remains the real gate. If you bind to `0.0.0.0` or serve behind a name, add the names clients use to `server.allowed_hosts` (for example `["monitor.lan:9109"]`) and any browser origins to `server.allowed_origins`. With `auth.enabled = false` (loopback only), REST requests are checked against a Host allowlist (loopback names, `server.bind` and `server.allowed_hosts`) and get `403` otherwise, to blunt DNS rebinding. There is no Origin check on REST and no token in that mode, so keep auth enabled on any multi-user host. Terminate TLS in a reverse proxy if the host is reachable beyond a trusted network; the server itself speaks plain HTTP. ## Docker access @@ -115,7 +120,7 @@ Reading the Docker socket directly requires group `docker`, which is root-equiva docker_socket = "/run/docker-proxy/docker.sock" ``` -If the socket is missing or unreadable, Docker routes return `503` and everything else keeps working. +A stock install does not add the `docker` group, so out of the box the Docker routes return `503` until you either grant access or configure a proxy. If the socket is missing or unreadable, Docker routes return `503` and everything else keeps working. ## OpenTelemetry diff --git a/TODO.md b/TODO.md index a53fd6e..2276010 100644 --- a/TODO.md +++ b/TODO.md @@ -98,7 +98,7 @@ Design: [`plan.md`](plan.md) · Review fixes: [`plan/review.md`](plan/review.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) +- [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 diff --git a/plan/workstreams/P3-integration.md b/plan/workstreams/P3-integration.md index 8f6b732..6cf88ef 100644 --- a/plan/workstreams/P3-integration.md +++ b/plan/workstreams/P3-integration.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Backlog | +| Status | Review | | Owner | — | | Phase | 3 (single track) | | Depends on | WS-E, WS-F, WS-G (and transitively A–D) | @@ -59,3 +59,4 @@ Tick these in [`TODO.md`](../../TODO.md). - 2026-10-15: Card created. - 2026-10-15: Implemented on `p3/integration`. I1-I5 done; I6 partial. Router assembly lives in `src/server.rs` (`build_router`, `serve_listener`) so tests and `main` share it. Shutdown: signal -> cancel token -> graceful serve ends -> await exporter handles -> `guard.shutdown().await` -> close pool. `token` subcommand does not init telemetry. Unit uses a static `User=skyg` (not DynamicUser) so `sudo -u skyg slinuxm token ...` hits the same DB. I2: 8 tests in `tests/integration.rs` (raw HTTP client, no new deps). Release binary 19 MB; `ldd`: libsystemd, libgcc_s, libm, libc only. - I6 live results (release binary, loopback, real token via CLI, real systemd/journal/docker on this host): #1 build/tests pass; #2 serve + token create pass; #3 REST incl. `curl -N` journal SSE pass (docker log follow SSE not exercised live); #4 MCP initialize, tools/list, prompts/list, resources/list, 5 tool calls, no-token 401, bad Origin 403 pass via curl (MCP Inspector not run; not all 8 tools called); #5 OTel NOT RUN (otelcol-contrib not on PATH, devenv shell not started via `devenv up`); #6 pass via tests (401, auth-off+0.0.0.0 refuses, SIGTERM with open SSE exits 0 in <1s); missing-docker-socket 503 covered by WS-E fake test, not live. Unit file not installed on a clean host (only `systemd-analyze verify`, which cannot fully run here). +- 2026-10-15: Review follow-ups applied. Shutdown drain and exporter awaits are bounded (10s each) and the unit uses TimeoutStopSec=30; new test: SIGTERM with an open MCP session and an in-flight 60s `tail_journal` exits 0. Unit: SystemCallFilter, ProtectProc=invisible, ProcSubset=pid, RestrictSUIDSGID, UMask=0077; docker.service is `After=` only. Hardening was run via `systemd-run --user` with the same sandbox properties (REST systemd/journal/docker and SIGTERM all worked); not run as a system unit with User=skyg/StateDirectory. Host allowlist guard on `/api/v1` when auth is disabled (test). `server.port = 0` rejected (test). Integration tests extended (13 tests): unmatched paths (401 with auth on, route existence not disclosed), POST 401/405, GET/DELETE /mcp without token, revoked token, Basic scheme, good Origin, missing docker socket (503 vs 200). SIGTERM tests use env_clear; the pick-port-then-drop race remains (port 0 is now rejected by config). diff --git a/src/config.rs b/src/config.rs index 6e1c7c2..69611a5 100644 --- a/src/config.rs +++ b/src/config.rs @@ -249,6 +249,11 @@ impl Config { /// Cross-field validation. pub fn validate(&self) -> Result<(), ConfigError> { + if self.server.port == 0 { + return Err(ConfigError::Invalid( + "server.port must be greater than zero".into(), + )); + } if !self.auth.enabled && !self.server.bind.is_loopback() { return Err(ConfigError::Invalid(format!( "auth.enabled = false is only allowed on a loopback bind address (server.bind = {})", @@ -291,6 +296,18 @@ mod tests { Config::load(file.map(Path::new), cli) } + #[test] + fn port_zero_rejected() { + Jail::expect_with(|_| { + let cli = CliOverrides { + port: Some(0), + ..Default::default() + }; + assert!(load(None, &cli).is_err()); + Ok(()) + }); + } + #[test] fn defaults_only() { Jail::expect_with(|_| { diff --git a/src/main.rs b/src/main.rs index d4c8bce..a155782 100644 --- a/src/main.rs +++ b/src/main.rs @@ -99,6 +99,11 @@ async fn main() -> Result<()> { } } +/// Upper bounds for shutdown phases (the OTel flush adds up to 5s per +/// provider, so the unit uses TimeoutStopSec=30). +const DRAIN_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10); +const EXPORTER_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10); + async fn serve(config: Config) -> Result<()> { let guard = telemetry::init(&config).context("initialising telemetry")?; let db = if config.auth.enabled { @@ -125,11 +130,35 @@ async fn serve(config: Config) -> Result<()> { signal_token.cancel(); }); - let result = server::serve_listener(listener, app, shutdown.clone()).await; + // `serve_listener` returns once the shutdown token fires and connections + // drain. If the token has not fired it is a server error, so return + // immediately. Bound the drain so a stuck client cannot hang SIGTERM. + let serving = server::serve_listener(listener, app, shutdown.clone()); + tokio::pin!(serving); + let result = tokio::select! { + r = &mut serving => r, + _ = shutdown.cancelled() => { + match tokio::time::timeout(DRAIN_TIMEOUT, &mut serving).await { + Ok(r) => r, + Err(_) => { + tracing::warn!("graceful drain timed out; closing remaining connections"); + Ok(()) + } + } + } + }; // Reached on signal or server error: stop everything, then flush OTel. shutdown.cancel(); - for h in exporters { - let _ = h.await; + let join_all = async { + for h in exporters { + let _ = h.await; + } + }; + if tokio::time::timeout(EXPORTER_TIMEOUT, join_all) + .await + .is_err() + { + tracing::warn!("exporter tasks did not stop in time"); } guard.shutdown().await; if let Some(pool) = pool { diff --git a/src/server.rs b/src/server.rs index 17d128c..7948250 100644 --- a/src/server.rs +++ b/src/server.rs @@ -7,13 +7,33 @@ use axum::Router; use tokio_util::sync::CancellationToken; use tower_http::trace::TraceLayer; +use std::sync::Arc; + +use axum::extract::{Request, State}; +use axum::http::{header, StatusCode}; +use axum::middleware::Next; +use axum::response::{IntoResponse, Response}; +use axum::Json; + +use crate::config::Config; use crate::state::AppState; use crate::{api, auth, mcp}; /// `/healthz` public; `/api/v1/*` and `/mcp` behind the auth layer. pub fn build_router(state: AppState) -> Router { + // With auth off there is no bearer gate, so guard REST against DNS + // rebinding with a Host allowlist (MCP has its own check). + let rest = api::router(state.clone()); + let rest = if state.config.auth.enabled { + rest + } else { + rest.layer(axum::middleware::from_fn_with_state( + allowed_hosts(&state.config), + host_guard, + )) + }; let protected = Router::new() - .nest("/api/v1", api::router(state.clone())) + .nest("/api/v1", rest) .nest_service("/mcp", mcp::service(state.clone())) .layer(auth::layer(state)); Router::new() @@ -35,3 +55,66 @@ pub async fn serve_listener( .await .context("server error") } + +fn allowed_hosts(c: &Config) -> Arc> { + let mut v: Vec = ["localhost", "127.0.0.1", "::1"] + .into_iter() + .map(String::from) + .collect(); + if !c.server.bind.is_unspecified() { + v.push(c.server.bind.to_string()); + } + v.extend( + c.server + .allowed_hosts + .iter() + .map(|h| host_only(h).to_owned()), + ); + Arc::new(v) +} + +/// Strip an optional port and IPv6 brackets: `[::1]:9109` -> `::1`. +fn host_only(h: &str) -> &str { + let h = h.trim(); + if let Some(rest) = h.strip_prefix('[') { + return rest.split(']').next().unwrap_or(rest); + } + match h.rsplit_once(':') { + Some((host, port)) if !host.contains(':') && port.chars().all(|c| c.is_ascii_digit()) => { + host + } + _ => h, + } +} + +async fn host_guard(State(allowed): State>>, req: Request, next: Next) -> Response { + let host = req + .headers() + .get(header::HOST) + .and_then(|v| v.to_str().ok()) + .map(host_only); + match host { + Some(h) if !allowed.iter().any(|a| a.eq_ignore_ascii_case(h)) => ( + StatusCode::FORBIDDEN, + Json(serde_json::json!({"error": { + "code": "forbidden_host", + "message": "Host header not allowed; add it to server.allowed_hosts", + }})), + ) + .into_response(), + _ => next.run(req).await, + } +} + +#[cfg(test)] +mod tests { + use super::host_only; + + #[test] + fn host_parsing() { + assert_eq!(host_only("localhost:9109"), "localhost"); + assert_eq!(host_only("[::1]:9109"), "::1"); + assert_eq!(host_only("::1"), "::1"); + assert_eq!(host_only("10.0.0.5"), "10.0.0.5"); + } +} diff --git a/systemd/skyg-linux-tracker.service b/systemd/skyg-linux-tracker.service index 1a66f16..098e0ce 100644 --- a/systemd/skyg-linux-tracker.service +++ b/systemd/skyg-linux-tracker.service @@ -1,14 +1,13 @@ [Unit] Description=skyg-linux-tracker: read-only systemd, journal and Docker monitor (REST, MCP, OTel) After=network.target docker.service -Wants=docker.service [Service] Type=simple ExecStart=/usr/local/bin/slinuxm serve --config /etc/skyg-linux-tracker.toml Restart=on-failure RestartSec=5 -TimeoutStopSec=15 +TimeoutStopSec=30 # Dedicated user, created beforehand: useradd --system --no-create-home \ # --shell /usr/sbin/nologin skyg @@ -44,6 +43,12 @@ RestrictRealtime=yes LockPersonality=yes MemoryDenyWriteExecute=yes SystemCallArchitectures=native +SystemCallFilter=@system-service +SystemCallFilter=~@privileged @resources +ProtectProc=invisible +ProcSubset=pid +RestrictSUIDSGID=yes +UMask=0077 CapabilityBoundingSet= AmbientCapabilities= diff --git a/tests/integration.rs b/tests/integration.rs index 17c94b0..65c06d6 100644 --- a/tests/integration.rs +++ b/tests/integration.rs @@ -13,6 +13,7 @@ use tokio::net::{TcpListener, TcpStream}; use tokio_util::sync::CancellationToken; struct Harness { + state_db: Option, port: u16, token: String, shutdown: CancellationToken, @@ -38,9 +39,11 @@ async fn start(auth: bool) -> Harness { state.db = Some(pool); } let shutdown = state.shutdown.clone(); + let state_db = state.db.clone(); let app = server::build_router(state); let join = tokio::spawn(server::serve_listener(listener, app, shutdown.clone())); Harness { + state_db, port, token, shutdown, @@ -59,8 +62,10 @@ async fn http( wait: Duration, ) -> (u16, String, String) { let mut s = TcpStream::connect(("127.0.0.1", port)).await.unwrap(); - let mut req = - format!("{method} {path} HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\nConnection: close\r\n"); + let mut req = format!("{method} {path} HTTP/1.1\r\nConnection: close\r\n"); + if !headers.iter().any(|(k, _)| k.eq_ignore_ascii_case("host")) { + req.push_str(&format!("Host: 127.0.0.1:{port}\r\n")); + } for (k, v) in headers { req.push_str(&format!("{k}: {v}\r\n")); } @@ -128,7 +133,10 @@ async fn auth_and_healthz() { ); let (st, _, body) = get(&h, "/api/v1/systemd/units", true).await; assert_eq!(st, 200); - assert!(body.contains("ssh") || body.contains(".service"), "{body}"); + assert!( + body.contains("\"name\":") && body.contains("active_state"), + "{body}" + ); // /mcp is protected too. let (st, _, _) = http( h.port, @@ -140,9 +148,98 @@ async fn auth_and_healthz() { ) .await; assert_eq!(st, 401); + // Unmatched paths are 401 without a token too (the auth layer also wraps + // the fallback, so route existence is not disclosed). + assert_eq!(get(&h, "/foo", false).await.0, 401); + assert_eq!(get(&h, "/api/v1/nope", false).await.0, 401); + assert_eq!(get(&h, "/api/v1/nope", true).await.0, 404); + let auth = format!("Bearer {}", h.token); + // POST to a REST route: 401 without a token, 405 with one. + let (st, _, _) = http(h.port, "POST", "/api/v1/systemd/units", &[], None, SHORT).await; + assert_eq!(st, 401); + let (st, _, _) = http( + h.port, + "POST", + "/api/v1/systemd/units", + &[("Authorization", auth.as_str())], + None, + SHORT, + ) + .await; + assert_eq!(st, 405); + // GET and DELETE /mcp without a token. + assert_eq!(get(&h, "/mcp", false).await.0, 401); + assert_eq!( + http(h.port, "DELETE", "/mcp", &[], None, SHORT).await.0, + 401 + ); + // Non-Bearer scheme carrying a valid token string. + let basic = format!("Basic {}", h.token); + let (st, _, _) = http( + h.port, + "GET", + "/api/v1/systemd/units", + &[("Authorization", basic.as_str())], + None, + SHORT, + ) + .await; + assert_eq!(st, 401); h.shutdown.cancel(); } +#[tokio::test] +async fn revoked_token_is_rejected() { + let h = start(true).await; + assert_eq!(get(&h, "/api/v1/systemd/timers", true).await.0, 200); + tokens::revoke(h.state_db.as_ref().unwrap(), "test") + .await + .unwrap(); + assert_eq!(get(&h, "/api/v1/systemd/timers", true).await.0, 401); + h.shutdown.cancel(); +} + +#[tokio::test] +async fn host_allowlist_when_auth_disabled() { + let h = start(false).await; + assert_eq!(get(&h, "/api/v1/systemd/timers", false).await.0, 200); + let (st, _, _) = http( + h.port, + "GET", + "/api/v1/systemd/timers", + &[("Host", "evil.example")], + None, + SHORT, + ) + .await; + assert_eq!(st, 403); + h.shutdown.cancel(); +} + +#[tokio::test] +async fn docker_unavailable_does_not_affect_systemd() { + use skyg_linux_tracker::sources::docker::BollardDocker; + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let port = listener.local_addr().unwrap().port(); + let mut config = Config::default(); + config.server.port = port; + config.auth.enabled = false; + config.sources.docker_socket = "/nonexistent/docker.sock".into(); + let mut state = fake_state(config); + state.docker = std::sync::Arc::new(BollardDocker::new(&state.config, state.shutdown.clone())); + let shutdown = state.shutdown.clone(); + tokio::spawn(server::serve_listener( + listener, + server::build_router(state), + shutdown.clone(), + )); + let (st, _, _) = http(port, "GET", "/api/v1/docker/ps", &[], None, SHORT).await; + assert_eq!(st, 503); + let (st, _, _) = http(port, "GET", "/api/v1/systemd/units", &[], None, SHORT).await; + assert_eq!(st, 200); + shutdown.cancel(); +} + #[tokio::test] async fn rest_routes() { let h = start(true).await; @@ -276,11 +373,24 @@ async fn mcp_bad_origin_is_forbidden() { h.shutdown.cancel(); } +#[tokio::test] +async fn mcp_good_origin_is_accepted() { + let h = start(true).await; + let auth = format!("Bearer {}", h.token); + let origin = format!("http://127.0.0.1:{}", h.port); + let mut hdrs: Vec<(&str, &str)> = MCP_HEADERS.to_vec(); + hdrs.push(("Authorization", auth.as_str())); + hdrs.push(("Origin", origin.as_str())); + let (st, _, _) = http(h.port, "POST", "/mcp", &hdrs, Some(init_body()), SHORT).await; + assert_eq!(st, 200); + h.shutdown.cancel(); +} + #[test] fn nonloopback_without_auth_exits_nonzero() { let out = std::process::Command::new(env!("CARGO_BIN_EXE_slinuxm")) .args(["serve", "--auth-enabled", "false", "--bind", "0.0.0.0"]) - .env_remove("SKYG_CONFIG") + .env_clear() .output() .unwrap(); assert!(!out.status.success()); @@ -299,6 +409,7 @@ fn sigterm_with_open_sse_client_exits_promptly() { let mut child = std::process::Command::new(env!("CARGO_BIN_EXE_slinuxm")) .args(["serve", "--auth-enabled", "false", "--bind", "127.0.0.1"]) .args(["--port", &port.to_string()]) + .env_clear() .stderr(std::process::Stdio::null()) .spawn() .unwrap(); @@ -339,3 +450,93 @@ fn sigterm_with_open_sse_client_exits_promptly() { std::thread::sleep(Duration::from_millis(50)); } } + +/// Real binary: an open MCP session with an in-flight `tail_journal` call +/// (60s requested) must not stop SIGTERM from exiting 0 within the bound. +#[test] +fn sigterm_with_inflight_mcp_tail_exits_within_bound() { + use std::io::{Read, Write}; + use std::net::TcpStream as StdStream; + let port = { + let l = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); + l.local_addr().unwrap().port() + }; + let mut child = std::process::Command::new(env!("CARGO_BIN_EXE_slinuxm")) + .args(["serve", "--auth-enabled", "false", "--bind", "127.0.0.1"]) + .args(["--port", &port.to_string()]) + .env_clear() + .stderr(std::process::Stdio::null()) + .spawn() + .unwrap(); + let post = |body: &str, sid: Option<&str>, read_resp: bool| -> (StdStream, String) { + let mut c = None; + for _ in 0..50 { + if let Ok(s) = StdStream::connect(("127.0.0.1", port)) { + c = Some(s); + break; + } + std::thread::sleep(Duration::from_millis(100)); + } + let mut c = c.expect("server did not start"); + c.set_read_timeout(Some(Duration::from_millis(1500))) + .unwrap(); + let sid_h = sid + .map(|s| format!("Mcp-Session-Id: {s}\r\n")) + .unwrap_or_default(); + write!( + c, + "POST /mcp HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\nContent-Type: application/json\r\nAccept: application/json, text/event-stream\r\n{sid_h}Content-Length: {}\r\n\r\n{body}", + body.len() + ) + .unwrap(); + let mut out = Vec::new(); + if read_resp { + let mut buf = [0u8; 4096]; + while let Ok(n) = c.read(&mut buf) { + if n == 0 { + break; + } + out.extend_from_slice(&buf[..n]); + } + } else { + let mut buf = [0u8; 512]; + let _ = c.read(&mut buf); + } + (c, String::from_utf8_lossy(&out).to_lowercase()) + }; + let (_c1, head) = post(init_body(), None, true); + let sid = head + .lines() + .find_map(|l| l.strip_prefix("mcp-session-id: ")) + .expect("session id") + .trim() + .to_owned(); + let _ = post( + r#"{"jsonrpc":"2.0","method":"notifications/initialized"}"#, + Some(&sid), + true, + ); + let _inflight = post( + r#"{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"tail_journal","arguments":{"unit":"nonexistent.service","seconds":60}}}"#, + Some(&sid), + false, + ); + let pid = child.id().to_string(); + assert!(std::process::Command::new("kill") + .args(["-TERM", &pid]) + .status() + .unwrap() + .success()); + let start = std::time::Instant::now(); + loop { + if let Some(st) = child.try_wait().unwrap() { + assert!(st.success(), "exit status {st}"); + break; + } + if start.elapsed() > Duration::from_secs(25) { + let _ = child.kill(); + panic!("process did not exit within the shutdown bound"); + } + std::thread::sleep(Duration::from_millis(50)); + } +}