From 8b7569363c59a916fb6474123027400dac42a3f4 Mon Sep 17 00:00:00 2001 From: ari Date: Mon, 19 Oct 2026 21:12:45 -0400 Subject: [PATCH] C: review round 2 proxy query unit rule and shared status classifier Proxied journal/unit values now use the local unit-name helper instead of a second, stricter check, so escaped units pass through as text, %5C or %5c. The peer status table is one function shared with the transport, and the segment/encoding cases left untested get allowlist and rejection cases. --- docs/api.md | 2 +- plan/phase-5-consolidator/ws-c-rest.md | 7 ++ src/api/behaviour_tests.rs | 54 ++++++++ src/peers/proxy.rs | 163 ++++++++++++++++++++++--- 4 files changed, 210 insertions(+), 16 deletions(-) diff --git a/docs/api.md b/docs/api.md index 9441c3e..b8b73a0 100644 --- a/docs/api.md +++ b/docs/api.md @@ -43,7 +43,7 @@ Present only when `[peers] enabled = true`. The same inbound token as the rest o `server` is the TCP check and `api` is the authenticated ping. `auth` is `ok`, `rejected` or `unknown`. Before the first check, `up` is false, `auth` is `unknown` and the timestamps are null. An unknown name is `404` `{"error":{"code":"not_found","message":"peer : unknown peer"}}`. -`GET /api/v1/peers/{peer}/{path}` forwards a GET to that peer and returns the peer's status and body. The path has to be one of the documented read routes: `systemd/units`, `systemd/units/{name}`, `systemd/timers`, `journal`, `journal/follow`, `docker/ps`, `docker/containers/{name}`, `docker/containers/{name}/logs`. `ping` and `peers/...` are not forwarded. `systemd/units/{name}` accepts exactly what the local route accepts, including escaped names (`mnt-data\x2dbackup.mount`, sent as `%5C`) and `-.mount`. `..`, encoded slashes, NUL/CRLF, a second encoding layer and any other path are `400` `peer : path not allowed`. Query keys are the same ones the local route accepts (`state`, `unit`, `priority`, `lines`, `since`, `all`, `tail`, `follow`); anything else is `400` `peer : unsupported query parameter`. The caller's `Authorization` and `Cookie` are not forwarded; the consolidator sends the peer's own token. +`GET /api/v1/peers/{peer}/{path}` forwards a GET to that peer and returns the peer's status and body. The path has to be one of the documented read routes: `systemd/units`, `systemd/units/{name}`, `systemd/timers`, `journal`, `journal/follow`, `docker/ps`, `docker/containers/{name}`, `docker/containers/{name}/logs`. `ping` and `peers/...` are not forwarded. `systemd/units/{name}` accepts exactly what the local route accepts, including escaped names (`mnt-data\x2dbackup.mount`, sent as `%5C`) and `-.mount`. `..`, encoded slashes, NUL/CRLF, a second encoding layer and any other path are `400` `peer : path not allowed`. Query keys are the same ones the local route accepts (`state`, `unit`, `priority`, `lines`, `since`, `all`, `tail`, `follow`); anything else is `400` `peer : unsupported query parameter`. The `unit` value is checked with the same unit-name rule as `systemd/units/{name}`, so escaped names work as both `%5C` and a literal backslash (`/api/v1/peers/beta/journal?unit=mnt-data%5Cx2dbackup.mount`). The caller's `Authorization` and `Cookie` are not forwarded; the consolidator sends the peer's own token. A request that already has `x-slinuxm-hop` is `400` `peer : chained requests are not allowed`. Other methods are `405`. `journal/follow` and docker logs with `follow=1` are `text/event-stream` with `Cache-Control: no-cache`, like the local follow routes, cut off at `limits.max_follow_secs` or shutdown. Bodies larger than `peers.max_response_bytes` are `503` `peer : oversize`. Only `2xx` from the peer is passed through; any other status becomes the section 4 error for that peer (a peer `404` is `404 not_found`, a peer `401`/`403` is `503 peer rejected credentials`, anything else is `503 http_`), so a redirect or the peer's own error body never reaches the caller. diff --git a/plan/phase-5-consolidator/ws-c-rest.md b/plan/phase-5-consolidator/ws-c-rest.md index c768799..1a6d464 100644 --- a/plan/phase-5-consolidator/ws-c-rest.md +++ b/plan/phase-5-consolidator/ws-c-rest.md @@ -61,3 +61,10 @@ Behaviour tests with the fake transport for every error mapping row in D9; 405 o - Disabled peers are still proxied in this tree, but the gating belongs to `PeerRegistry::get` in `src/peers/registry.rs`, which WS-C does not own and WS-B's review already covers (its finding 2). A test here would have to assert behaviour C cannot change, so no C-side test is added; when B refuses disabled peers, the REST route inherits it unchanged because C only resolves the name via the registry. - The `raw_peer_path` `None` branch is kept: it is an `Option` check on the request URI, not an error-shape fallback, and it is cheap insurance if the route pattern changes. - `405` on a proxied path is still produced by the router fallback in `api/mod.rs` (not owned by WS-C), so it carries no `x-slinuxm-peer`; the contract's "every proxied response" is satisfied for responses that reach a peer handler, and WS-T does not assert the header on 405. +- 2026-10-19 (review round 2): fixes. + - Blocking: proxied journal query values now accept what the local route accepts on the unit side. `query_value_ok(key, value)` takes the key: for `unit` it calls `sources::systemd::validate_unit_name`, the helper the local `systemd/units/{name}` route already uses, so there is still one unit rule and no second validator. Escaped units (`mnt-data\x2dbackup.mount`, `dev-disk-by\x2did.device`) therefore work through `journal` and `journal/follow` as text, as `%5C` and as `%5c`; the value is forwarded decoded, which is what the transport re-encodes as one query pair. Other keys keep the generic `\`, `/` and `..` rejection, and every key keeps the length bound, the control-character rule and the second-encoding-layer rejection (`%252f`, `%255c`, `%2e%2e`). + - Tests: `journal_unit_values_are_forwarded_like_the_local_route` (raw, `%5C`, `%5c`, a second key, `-.mount`, `user@100.service`, and a decoded `unit` pair for the MCP path) and `journal_unit_values_still_reject_unsafe_text` in `proxy.rs`; behaviour-level `proxy_forwards_journal_unit_values_the_local_route_accepts` asserts the forwarded query values and that an unknown key or traversal text is still `400`. `proxy_forwards_unit_names_the_local_route_accepts` gained a raw-backslash systemd path next to the encoded ones, so both routes cover raw and encoded input. With the `unit` branch reverted, all three journal tests fail on the old check (the behaviour one with the reported `400`), so they pin the fix. + - Non-blocking 2: the status table is now `proxy::classify_status(u16) -> PeerError`, one function with one test (`status_classification_is_one_table`). `prepare_response` calls it and keeps the 2xx-only guard as defence in depth. Handoff to WS-B: the real transport classifies a live response with `crate::peers::proxy::classify_status` instead of copying the table, so the two cannot drift. + - Handoff to WS-D: `PeerRequest.query` carries decoded pairs. A `unit` argument reaches the proxy as the unit name itself (`dev-disk-by\x2did.device`, backslash included) and needs no encoding on D's side; the tool schema takes the plain name, so an already percent-encoded string such as `dev-disk-by%5Cx2did.device` is not a unit name and is `400`. + - Non-blocking 3: a `..` inside a single segment is not traversal, because segments cannot contain `/` and the forwarded path is re-encoded from them. Pinned by allowlist cases `systemd/units/foo..bar.mount` and `docker/containers/foo..bar`, plus a rejection case for an encoded `%2e%2e` inside one segment (`systemd/units/foo%2e%2ebar.mount`), which `encoding_forbidden` catches. + - `docs/api.md` states the `unit` query rule and the `%5C`/literal-backslash forms. diff --git a/src/api/behaviour_tests.rs b/src/api/behaviour_tests.rs index b13549c..a520687 100644 --- a/src/api/behaviour_tests.rs +++ b/src/api/behaviour_tests.rs @@ -518,6 +518,7 @@ async fn proxy_forwards_unit_names_the_local_route_accepts() { "/peers/beta/systemd/units/-.slice", "/peers/beta/systemd/units/mnt-data%5Cx2dbackup.mount", "/peers/beta/systemd/units/foo%5cx2db.mount", + "/peers/beta/systemd/units/foo\\x2db.mount", ] { let (status, headers, body) = call(&app, "GET", uri, &[]).await; assert_eq!(status, StatusCode::OK, "{uri}: {body}"); @@ -531,10 +532,63 @@ async fn proxy_forwards_unit_names_the_local_route_accepts() { "/systemd/units/-.slice", "/systemd/units/mnt-data%5Cx2dbackup.mount", "/systemd/units/foo%5Cx2db.mount", + "/systemd/units/foo%5Cx2db.mount", ] ); } +/// The journal `unit` filter is a unit name, so the proxy must accept the +/// escaped forms the local routes accept, whether the caller sends `%5C` or a +/// literal backslash. +#[tokio::test] +async fn proxy_forwards_journal_unit_values_the_local_route_accepts() { + let fake = FakeTransport::new(); + fake.peer("beta") + .respond("/journal/follow", 200, "text/event-stream", "") + .respond("/journal", 200, "application/json", "[]"); + let app = proxy_app(fake.clone()); + for uri in [ + "/peers/beta/journal?unit=mnt-data%5Cx2dbackup.mount", + "/peers/beta/journal?unit=mnt-data%5cx2dbackup.mount", + "/peers/beta/journal?unit=mnt-data\\x2dbackup.mount", + "/peers/beta/journal?unit=dev-disk-by%5Cx2did.device&priority=err", + "/peers/beta/journal/follow?unit=user@100.service", + ] { + let (status, headers, body) = call(&app, "GET", uri, &[]).await; + assert_eq!(status, StatusCode::OK, "{uri}: {body}"); + assert_eq!(peer_header(&headers), Some("beta"), "{uri}"); + } + let queries: Vec<_> = fake.calls().into_iter().map(|(_, req)| req.query).collect(); + assert_eq!( + queries, + vec![ + vec![("unit".into(), "mnt-data\\x2dbackup.mount".into())], + vec![("unit".into(), "mnt-data\\x2dbackup.mount".into())], + vec![("unit".into(), "mnt-data\\x2dbackup.mount".into())], + vec![ + ("unit".into(), "dev-disk-by\\x2did.device".into()), + ("priority".into(), "err".into()), + ], + vec![("unit".into(), "user@100.service".into())], + ] + ); + + // Still filtered: traversal text in the value and an unknown key. + for uri in [ + "/peers/beta/journal?unit=../x", + "/peers/beta/journal?unit=nginx.service&token=abc", + ] { + let (status, _, body) = call(&app, "GET", uri, &[]).await; + assert_eq!(status, StatusCode::BAD_REQUEST, "{uri}: {body}"); + assert_eq!( + json(&body)["error"]["message"], + "peer beta: unsupported query parameter", + "{uri}" + ); + } + assert_eq!(fake.calls().len(), 5); +} + /// The contract promises the peer's status only for 2xx; a transport that /// returns anything else must not turn into a redirect or a peer error body. #[tokio::test] diff --git a/src/peers/proxy.rs b/src/peers/proxy.rs index 940bf21..d2f14cd 100644 --- a/src/peers/proxy.rs +++ b/src/peers/proxy.rs @@ -116,6 +116,16 @@ pub(crate) struct PreparedResponse { pub body: PreparedBody, } +/// One table for peer statuses: the transport classifies a live response with +/// it and [`prepare_response`] checks again, so neither side can drift. +pub(crate) fn classify_status(status: u16) -> PeerError { + match status { + 404 => PeerError::NotFound, + 401 | 403 => PeerError::Rejected, + code => PeerError::Http(code), + } +} + /// The contract promises pass-through only for 2xx, so anything else is /// classified here rather than relayed: a transport that forgot to map a /// redirect or the peer's own error body must not reach the caller. @@ -128,14 +138,7 @@ pub(crate) fn prepare_response( ) -> Result { let status = match StatusCode::from_u16(resp.status) { Ok(status) if status.is_success() => status, - _ => { - let class = match resp.status { - 404 => PeerError::NotFound, - 401 | 403 => PeerError::Rejected, - code => PeerError::Http(code), - }; - return Err(peer_error_to_app(peer, &class)); - } + _ => return Err(peer_error_to_app(peer, &classify_status(resp.status))), }; let content_type = content_type(peer, resp.content_type.as_deref())?; let body = prepare_body(peer, resp.body, max_bytes, deadline, shutdown)?; @@ -367,7 +370,11 @@ fn allow_query( let mut out = Vec::with_capacity(query.len()); for (key, value) in query { let known = allowed.iter().any(|name| *name == key); - if !known || !query_key_ok(key) || !query_value_ok(value) || seen.contains(&key.as_str()) { + if !known + || !query_key_ok(key) + || !query_value_ok(key, value) + || seen.contains(&key.as_str()) + { return Err(query_rejected(peer.as_str())); } seen.push(key.as_str()); @@ -384,13 +391,21 @@ fn query_key_ok(key: &str) -> bool { .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_') } -fn query_value_ok(value: &str) -> bool { - value.len() <= 1024 - && !value - .chars() - .any(|c| c.is_control() || c == '\\' || c == '/') +/// Values arrive decoded and leave as encoded query pairs, so only control +/// characters and a second encoding layer are unsafe here. The journal `unit` +/// filter is a unit name, so it gets the local route's unit check verbatim: +/// that is where a backslash (systemd's escape) is legal. +fn query_value_ok(key: &str, value: &str) -> bool { + if value.len() > 1024 || encoding_forbidden(value) { + return false; + } + if key == "unit" { + return validate_unit_name(value).is_ok(); + } + !value + .chars() + .any(|c| c.is_control() || c == '\\' || c == '/') && !value.contains("..") - && !encoding_forbidden(value) } fn route_is_follow(route: &str, query: &[(String, String)]) -> bool { @@ -506,6 +521,10 @@ mod tests { "systemd/units/foo\\x2dbar.mount", "systemd/units/mnt-data%5Cx2dbackup.mount", "systemd/units/dev-disk-by%5cx2did.device", + // A `..` inside a name is not traversal: segments cannot contain + // a slash and the forwarded path is re-encoded from them. + "systemd/units/foo..bar.mount", + "/docker/containers/foo..bar", ]; for path in ok { get_with(fake.as_ref(), &peer, path, &[]).await.unwrap(); @@ -528,6 +547,8 @@ mod tests { "/systemd/units/foo%5Cx2dbar.mount", "/systemd/units/mnt-data%5Cx2dbackup.mount", "/systemd/units/dev-disk-by%5Cx2did.device", + "/systemd/units/foo..bar.mount", + "/docker/containers/foo..bar", ] ); } @@ -640,6 +661,9 @@ mod tests { "systemd/units/nginx%0d.service", "systemd/units/foo%25.service", "systemd/units/foo%zz.service", + // An encoded `..` anywhere is a second encoding layer, even when + // it sits inside one segment rather than being the segment. + "systemd/units/foo%2e%2ebar.mount", // A backslash is only a legal character inside a unit name. "systemd%5cunits", "journal%5cfollow", @@ -721,6 +745,115 @@ mod tests { assert!(calls[2].1.accept.is_none()); } + #[tokio::test] + async fn journal_unit_values_are_forwarded_like_the_local_route() { + let fake = FakeTransport::new(); + let peer = peer_cfg(); + // Raw text as an MCP caller would pass it, and the same values in a + // request target: `%5C` and a literal backslash both decode to one + // backslash, which is what systemd uses to escape a unit name. + let raw_queries = [ + "unit=mnt-data%5Cx2dbackup.mount", + "unit=mnt-data%5cx2dbackup.mount", + "unit=mnt-data\\x2dbackup.mount", + "unit=dev-disk-by%5Cx2did.device&priority=err", + "unit=-.mount", + "unit=user@100.service", + ]; + for raw in raw_queries { + let query = query_from_raw("beta", Some(raw)).unwrap(); + get_with(fake.as_ref(), &peer, "/journal", &query) + .await + .unwrap(); + } + get_with( + fake.as_ref(), + &peer, + "/journal/follow", + &[("unit".into(), "mnt-data\\x2dbackup.mount".into())], + ) + .await + .unwrap(); + assert_eq!( + fake.calls() + .into_iter() + .map(|(_, req)| req.query) + .collect::>(), + vec![ + vec![("unit".into(), "mnt-data\\x2dbackup.mount".into())], + vec![("unit".into(), "mnt-data\\x2dbackup.mount".into())], + vec![("unit".into(), "mnt-data\\x2dbackup.mount".into())], + vec![ + ("unit".into(), "dev-disk-by\\x2did.device".into()), + ("priority".into(), "err".into()), + ], + vec![("unit".into(), "-.mount".into())], + vec![("unit".into(), "user@100.service".into())], + vec![("unit".into(), "mnt-data\\x2dbackup.mount".into())], + ] + ); + } + + #[tokio::test] + async fn journal_unit_values_still_reject_unsafe_text() { + let fake = FakeTransport::new(); + let peer = peer_cfg(); + let bad = [ + // Not a unit name, so the local unit rule rejects it. + "unit=../x", + "unit=a/b", + "unit=nginx", + "unit=nginx.service%2fx", + "unit=mnt-data%5Cx2d.mount%2e", + "unit=mnt-data%0ax2d.mount", + "unit=a%255cb.mount", + ]; + for raw in bad { + // Some values are stopped while the raw query is parsed and the + // rest by the allowlist; both are the same 400. + let err = match query_from_raw("beta", Some(raw)) { + Ok(query) => get_with(fake.as_ref(), &peer, "/journal", &query) + .await + .unwrap_err(), + Err(err) => err, + }; + assert_eq!(err.code(), "bad_request", "{raw}"); + assert_eq!( + err.message(), + "peer beta: unsupported query parameter", + "{raw}" + ); + } + // Values that reach the check already decoded (the MCP path) are + // rejected there rather than by the raw parser. + for value in [ + "mnt-data\u{0}x2d.mount", + "mnt-data\nx2d.mount", + "mnt-data\rx2d.mount", + "mnt-data\x2d.mount/../../etc/passwd", + ] { + let err = get_with( + fake.as_ref(), + &peer, + "/journal", + &[("unit".into(), value.into())], + ) + .await + .unwrap_err(); + assert_eq!(err.code(), "bad_request", "{value:?}"); + } + assert!(fake.calls().is_empty()); + } + + #[test] + fn status_classification_is_one_table() { + assert!(matches!(classify_status(404), PeerError::NotFound)); + assert!(matches!(classify_status(401), PeerError::Rejected)); + assert!(matches!(classify_status(403), PeerError::Rejected)); + assert!(matches!(classify_status(302), PeerError::Http(302))); + assert!(matches!(classify_status(200), PeerError::Http(200))); + } + #[tokio::test] async fn slow_peer_is_a_timeout() { let fake = FakeTransport::new();