From e456cb583fd8d9e8b5f25a681b19f92ae3248008 Mon Sep 17 00:00:00 2001 From: loki5512344 Date: Mon, 16 Nov 2026 12:36:29 +0100 Subject: [PATCH] feat(manager): SCAN inventory, pagination, request limits, graceful shutdown - Inventory nodes/servers use cursor SCAN plus MGET batches instead of KEYS and per-key GET; a Redis error returns 503 instead of an empty fleet. - GET /blacklist no longer writes: the legacy metadata backfill moved to a one-shot startup task. The list endpoint paginates (limit 100, max 1000, offset max 10000) instead of dumping SMEMBERS. - Router-wide DefaultBodyLimit 8 KiB and TimeoutLayer 10 s; every mutating endpoint is rate limited (30/min per client IP) with idle eviction, and the login limiter resets on success. reason > 256 bytes and malformed targets are rejected with 400. - SIGTERM/Ctrl-C trigger graceful shutdown; the heartbeat and eviction tasks are cancelled and joined so in-flight ban edits reach Redis. - MANAGER_TRUSTED_PROXIES enables X-Forwarded-For (right-to-left walk) only for configured proxy networks; otherwise the TCP peer is used. - tests/manager_api.rs covers 401/400/413/429/503 and CORS preflight through the real router; manager_security gains limiter and proxy-IP tests. --- Cargo.lock | 3 + Cargo.toml | 6 +- docs/api.md | 31 ++- src/bin/rampart-manager.rs | 103 +++++++--- src/manager/api/auth.rs | 42 ++-- src/manager/api/blacklist.rs | 37 +++- src/manager/api/blacklist/backfill.rs | 82 ++++++++ src/manager/api/blacklist/common.rs | 43 +++- src/manager/api/blacklist/list.rs | 168 +++++++++------ src/manager/api/blacklist/mutate.rs | 10 +- src/manager/api/guard/limit.rs | 89 ++++++++ src/manager/api/guard/mod.rs | 111 ++++++++++ src/manager/api/guard/proxy.rs | 86 ++++++++ src/manager/api/guard/router.rs | 76 +++++++ src/manager/api/inventory/mod.rs | 62 +++++- src/manager/api/inventory/nodes.rs | 51 ++--- src/manager/api/inventory/servers.rs | 51 ++--- src/manager/api/mod.rs | 8 + src/manager/security.rs | 87 +++++++- tests/manager_api.rs | 282 ++++++++++++++++++++++++++ tests/manager_security.rs | 129 +++++++++++- 21 files changed, 1377 insertions(+), 180 deletions(-) create mode 100644 src/manager/api/blacklist/backfill.rs create mode 100644 src/manager/api/guard/limit.rs create mode 100644 src/manager/api/guard/mod.rs create mode 100644 src/manager/api/guard/proxy.rs create mode 100644 src/manager/api/guard/router.rs create mode 100644 tests/manager_api.rs diff --git a/Cargo.lock b/Cargo.lock index 9273d77..957525f 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2110,6 +2110,7 @@ dependencies = [ "tokio", "tokio-splice", "toml", + "tower", "tower-http 0.7.1", "tracing", "tracing-subscriber", @@ -3201,8 +3202,10 @@ dependencies = [ "bitflags 2.13.2", "bytes", "http", + "http-body", "percent-encoding", "pin-project-lite", + "tokio", "tower-layer", "tower-service", ] diff --git a/Cargo.toml b/Cargo.toml index f2bc98d..b5fb057 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -68,7 +68,7 @@ ratatui = "0.30" crossterm = "0.29" axum = "0.8" -tower-http = { version = "0.7", features = ["cors"] } +tower-http = { version = "0.7", features = ["cors", "timeout"] } jsonwebtoken = { version = "11", features = ["aws_lc_rs"] } redis = { version = "1.7", optional = true, features = ["tokio-comp", "connection-manager"] } @@ -76,3 +76,7 @@ maxminddb = { version = "0.32", optional = true } tokio-splice = { version = "0.2", optional = true } libbpf-rs = { version = "0.27", optional = true } libc = { version = "0.2", optional = true } + +[dev-dependencies] +# `ServiceExt::oneshot` drives the axum router in integration tests. +tower = { version = "0.5", features = ["util"] } diff --git a/docs/api.md b/docs/api.md index 4f5e30e..cdd73fb 100644 --- a/docs/api.md +++ b/docs/api.md @@ -64,6 +64,8 @@ Authorization: Bearer ### `GET /api/v1/blacklist` 🔒 +Query: `limit` (по умолчанию 100, максимум 1000) и `offset` (максимум 10000). + ```json { "items": [ @@ -75,9 +77,16 @@ Authorization: Bearer ``` Источник: Redis set `rampart:blacklist` и hash `rampart:blacklist:metadata`. +Записи читаются через `SSCAN` порциями, поэтому set никогда не выгружается целиком; +порядок страниц не определён (Redis set) и при параллельных изменениях страницы +могут пересекаться. `total` — размер set по `SCARD`, он может включать истёкшие +записи, которые API скрывает в `items`. + Метаданные содержат причину, время создания и абсолютный срок истечения; API -скрывает истёкшие записи. Старые set-записи без метаданных получают один -ограниченный срок в пять минут при первом чтении или восстановлении edge. +скрывает истёкшие записи. `GET` ничего не пишет в Redis: старые set-записи без +метаданных показываются с временной записью «пять минут» только для чтения, а +сама метаданные восстанавливаются одноразовым фоновым backfill при старте +manager (или при восстановлении снимка edge). ### `POST /api/v1/blacklist` 🔒 @@ -89,6 +98,9 @@ Authorization: Bearer // с duration_secs и expires_at_unix опубликовано в rampart:blacklist:events. ``` +`target` — одиночный IPv4/IPv6-адрес (CIDR не поддерживается), `reason` — не +длиннее 256 байт; иначе `400 Bad Request`. + Edge подписывается на Pub/Sub перед загрузкой снимка из Redis. Поэтому события, пришедшие во время загрузки, будут применены после снимка. При старте и после переподключения активные Redis-баны восстанавливаются с оставшимся TTL; новые @@ -112,6 +124,9 @@ Edge подписывается на Pub/Sub перед загрузкой сн Список зарегистрированных edge-нод из Redis (`rampart:nodes:*`, heartbeat). +Если Redis недоступен, API возвращает `503 Service Unavailable`; пустой массив +означает исправное, но пустое окружение. + ```json { "nodes": [ @@ -129,8 +144,16 @@ Edge подписывается на Pub/Sub перед загрузкой сн - drain нод через API или CLI; - webhooks, metrics summary, challenge management; -- регистрации нод через `POST /api/v1/nodes`; -- rate limiting на сами запросы API (кроме login). +- регистрации нод через `POST /api/v1/nodes`. + +## Ограничения запросов + +- Тело запроса — не больше 8 КиБ (`413`), любой запрос — не дольше 10 секунд. +- `/api/v1/auth/login` — 5 попыток в минуту с одного клиентского адреса (`429`). +- `POST`/`DELETE /api/v1/blacklist` (и любые будущие mutating-методы) — 30 запросов + в минуту с одного клиентского адреса (`429`); успешный login сбрасывает счётчик. +- Клиентский адрес — TCP peer, если запрос не пришёл с сети из + `MANAGER_TRUSTED_PROXIES`; только тогда используется `X-Forwarded-For`. --- diff --git a/src/bin/rampart-manager.rs b/src/bin/rampart-manager.rs index 4f6c6bb..6346da5 100644 --- a/src/bin/rampart-manager.rs +++ b/src/bin/rampart-manager.rs @@ -1,14 +1,17 @@ //! Rampart manager daemon: HTTP API in front of the redis state store. -use axum::{ - Router, middleware, - routing::{get, post}, -}; use dashmap::DashMap; #[cfg(feature = "store-redis")] +use rampart::manager::api; +#[cfg(feature = "store-redis")] use rampart::manager::sync; -use rampart::manager::{AppState, api, auth, security}; +use rampart::manager::{ + AppState, SharedState, + api::{build_router, guard}, + security, +}; use std::sync::Arc; +use tokio::sync::watch; use tracing_subscriber::EnvFilter; #[tokio::main] @@ -39,7 +42,7 @@ async fn main() -> anyhow::Result<()> { let api_password = std::env::var("API_PASSWORD").map_err(|_| anyhow::anyhow!("API_PASSWORD must be set"))?; security::validate_api_password(&api_password)?; - let state = Arc::new(AppState { + let state: SharedState = Arc::new(AppState { #[cfg(feature = "store-redis")] redis_client, jwt_secret, @@ -48,41 +51,77 @@ async fn main() -> anyhow::Result<()> { api_password, login_limiter: DashMap::new(), }); + let guard = Arc::new(guard::RequestGuard::from_env()?); + // Background tasks share one shutdown signal, so SIGTERM stops them together + // with the HTTP server instead of leaving detached tasks behind. + let (shutdown_tx, shutdown_rx) = watch::channel(false); #[cfg(feature = "store-redis")] - tokio::spawn(sync::heartbeat::start_heartbeat_check(state.clone())); - - let public = Router::new() - .route("/api/v1/health", get(api::inventory::health::health_check)) - .route("/api/v1/auth/login", post(api::auth::login)); - - // Redis-backed routes only exist together with the feature; the manager bails - // out above without it, so 501 stubs here would be unreachable code. - let protected = Router::new(); + let heartbeat = spawn_heartbeat(state.clone(), shutdown_rx.clone()); + let eviction = guard::spawn_eviction(state.clone(), guard.clone(), shutdown_rx.clone()); + // One-shot legacy migration; losing it on shutdown is harmless because the + // read path no longer depends on the metadata being present. #[cfg(feature = "store-redis")] - let protected = protected - .route("/api/v1/servers", get(api::inventory::servers::list_servers)) - .route( - "/api/v1/blacklist", - get(api::blacklist::list_blacklist) - .post(api::blacklist::add_blacklist) - .delete(api::blacklist::remove_blacklist), - ) - .route("/api/v1/nodes", get(api::inventory::nodes::list_nodes)); - let protected = protected.route_layer(middleware::from_fn_with_state(state.clone(), auth::auth_middleware)); + tokio::spawn(api::blacklist::backfill_legacy_metadata(state.clone())); let cors_policy = security::CorsPolicy::parse(std::env::var("CORS_ORIGIN").ok().as_deref())?; tracing::info!("CORS policy: {cors_policy:?}"); - let mut app = Router::new().merge(public).merge(protected).with_state(state); - if let Some(cors) = cors_policy.cors_layer() { - app = app.layer(cors); - } - + let app = build_router(state, guard, cors_policy.cors_layer()); let addr = "0.0.0.0:8080"; - tracing::info!("Manager API listening on {addr}"); let listener = tokio::net::TcpListener::bind(addr).await?; + tracing::info!("Manager API listening on {addr}"); let app = app.into_make_service_with_connect_info::(); - axum::serve(listener, app).await?; + + // Graceful shutdown drains in-flight requests, so a ban removal that already + // reached a handler is written to Redis before the process exits. + axum::serve(listener, app) + .with_graceful_shutdown(shutdown_signal()) + .await?; + + let _ = shutdown_tx.send(true); + let _ = eviction.await; + #[cfg(feature = "store-redis")] + let _ = heartbeat.await; + tracing::info!("manager stopped"); Ok(()) } + +/// Spawns the heartbeat check loop and stops it on the shared shutdown signal. +#[cfg(feature = "store-redis")] +fn spawn_heartbeat(state: SharedState, mut shutdown: watch::Receiver) -> tokio::task::JoinHandle<()> { + tokio::spawn(async move { + tokio::select! { + () = sync::heartbeat::start_heartbeat_check(state) => {}, + _ = shutdown.changed() => {}, + } + }) +} + +/// Resolves on `SIGTERM` or Ctrl-C, whichever arrives first. +async fn shutdown_signal() { + let ctrl_c = async { + if let Err(error) = tokio::signal::ctrl_c().await { + tracing::error!("failed to listen for Ctrl-C: {error}"); + } + }; + #[cfg(unix)] + let terminate = async { + match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) { + Ok(mut signal) => { + signal.recv().await; + }, + Err(error) => { + tracing::error!("failed to listen for SIGTERM: {error}"); + std::future::pending::<()>().await; + }, + } + }; + #[cfg(not(unix))] + let terminate = std::future::pending::<()>(); + tokio::select! { + () = ctrl_c => {}, + () = terminate => {}, + } + tracing::info!("shutdown signal received: draining in-flight requests"); +} diff --git a/src/manager/api/auth.rs b/src/manager/api/auth.rs index 4d60333..8514a43 100644 --- a/src/manager/api/auth.rs +++ b/src/manager/api/auth.rs @@ -1,10 +1,11 @@ //! `POST /api/v1/auth/login`: password check with a per-IP attempt limiter. use crate::manager::AppState; +use crate::manager::api::guard::{RequestGuard, limit}; use axum::{ - Json, + Extension, Json, extract::{ConnectInfo, State}, - http::StatusCode, + http::{HeaderMap, StatusCode}, }; use dashmap::DashMap; use serde::Deserialize; @@ -14,20 +15,30 @@ use std::{ time::{Duration, Instant}, }; -const LOGIN_WINDOW: Duration = Duration::from_secs(60); -const LOGIN_MAX_ATTEMPTS: u32 = 5; +/// Window of the login limiter, exported for the eviction sweep. +pub const LOGIN_WINDOW: Duration = limit::LOGIN_WINDOW; +/// Login attempts allowed per window and source address. +pub const LOGIN_MAX_ATTEMPTS: u32 = limit::LOGIN_MAX_ATTEMPTS; #[derive(Deserialize)] pub struct LoginRequest { pub password: String, } +/// Verifies the API password and returns a bearer token. +/// +/// The client address comes from [`RequestGuard`]: the transport peer unless a +/// trusted reverse proxy forwarded the request. The attempt counter is reset +/// after a successful login so a legitimate administrator starts clean. pub async fn login( State(state): State>, ConnectInfo(addr): ConnectInfo, + Extension(guard): Extension>, + headers: HeaderMap, Json(req): Json, ) -> Result, (StatusCode, Json)> { - if !allow_login_attempt(&state.login_limiter, addr.ip()) { + let ip = guard.client_ip(addr.ip(), &headers); + if !allow_login_attempt(&state.login_limiter, ip) { return Err(( StatusCode::TOO_MANY_REQUESTS, Json(serde_json::json!({"error": "too many requests"})), @@ -40,6 +51,7 @@ pub async fn login( Json(serde_json::json!({"error": "invalid password"})), )); } + reset_login_attempts(&state.login_limiter, ip); match crate::manager::auth::create_token(&state.jwt_secret, state.jwt_expiration, &state.jwt_audience) { Ok(token) => Ok(Json(serde_json::json!({"token": token}))), @@ -52,19 +64,13 @@ pub async fn login( /// Records a login attempt for `ip` and reports whether it is within the window. /// -/// The limiter allows `LOGIN_MAX_ATTEMPTS` attempts per `LOGIN_WINDOW` and +/// The limiter allows [`LOGIN_MAX_ATTEMPTS`] attempts per [`LOGIN_WINDOW`] and /// resets the counter when the window elapses. pub fn allow_login_attempt(limiter: &DashMap, ip: IpAddr) -> bool { - let now = Instant::now(); - let mut slot = limiter.entry(ip).or_insert((now, 0)); - let (last_reset, attempts) = &mut *slot; - if now.duration_since(*last_reset) >= LOGIN_WINDOW { - *last_reset = now; - *attempts = 1; - } else if *attempts >= LOGIN_MAX_ATTEMPTS { - return false; - } else { - *attempts += 1; - } - true + limit::check_attempt(limiter, ip, LOGIN_WINDOW, LOGIN_MAX_ATTEMPTS) +} + +/// Clears the login counter of `ip` after a successful authentication. +pub fn reset_login_attempts(limiter: &DashMap, ip: IpAddr) { + limit::reset_attempts(limiter, ip); } diff --git a/src/manager/api/blacklist.rs b/src/manager/api/blacklist.rs index cc8cfd5..e8a0f11 100644 --- a/src/manager/api/blacklist.rs +++ b/src/manager/api/blacklist.rs @@ -1,5 +1,14 @@ +//! Blacklist endpoints: paginated listing plus add and remove mutations. + use serde::{Deserialize, Serialize}; +/// Entries returned when the request does not set `limit`. +pub const DEFAULT_PAGE_LIMIT: u64 = 100; +/// Upper bound of `limit`, independent of the request. +pub const MAX_PAGE_LIMIT: u64 = 1000; +/// Upper bound of `offset`, which bounds the work of a single request. +pub const MAX_PAGE_OFFSET: u64 = 10_000; + #[derive(Debug, Serialize, Deserialize)] pub struct BlacklistEntry { pub target: String, @@ -13,11 +22,10 @@ pub struct BlacklistEntry { #[derive(Serialize)] pub struct BlacklistResponse { pub items: Vec, - pub total: usize, + pub total: u64, } #[derive(Deserialize)] -#[allow(dead_code)] pub struct AddBlacklistRequest { pub target: String, #[serde(rename = "type")] @@ -31,6 +39,29 @@ pub struct RemoveBlacklistRequest { pub target: String, } +/// `limit`/`offset` query parameters of the list endpoint. +#[derive(Debug, Default, Deserialize)] +pub struct ListQuery { + pub limit: Option, + pub offset: Option, +} + +impl ListQuery { + /// Resolves the request into `(offset, limit)` inside the hard bounds. + /// + /// Missing values use [`DEFAULT_PAGE_LIMIT`] and zero, a too-large `limit` + /// is clamped to [`MAX_PAGE_LIMIT`] and a too-large `offset` to + /// [`MAX_PAGE_OFFSET`], so no request can ask for the whole set. + #[must_use] + pub fn bounds(&self) -> (u64, u64) { + let limit = self.limit.unwrap_or(DEFAULT_PAGE_LIMIT).min(MAX_PAGE_LIMIT); + let offset = self.offset.unwrap_or(0).min(MAX_PAGE_OFFSET); + (offset, limit) + } +} + +#[cfg(feature = "store-redis")] +mod backfill; #[cfg(feature = "store-redis")] mod common; #[cfg(feature = "store-redis")] @@ -38,6 +69,8 @@ mod list; #[cfg(feature = "store-redis")] mod mutate; +#[cfg(feature = "store-redis")] +pub use backfill::backfill_legacy_metadata; #[cfg(feature = "store-redis")] pub use list::list_blacklist; #[cfg(feature = "store-redis")] diff --git a/src/manager/api/blacklist/backfill.rs b/src/manager/api/blacklist/backfill.rs new file mode 100644 index 0000000..0f2a40b --- /dev/null +++ b/src/manager/api/blacklist/backfill.rs @@ -0,0 +1,82 @@ +//! One-shot startup backfill of legacy blacklist metadata. +//! +//! Older managers wrote `rampart:blacklist` members without a record in +//! `rampart:blacklist:metadata`. The read path is side-effect free now, so the +//! repair happens once at startup instead of on every `GET`: set members are +//! iterated with SSCAN, read in HMGET batches and filled with HSETNX, which +//! never overwrites metadata written by a concurrent add. + +use super::common::{ + BLACKLIST_KEY, BLACKLIST_METADATA_KEY, PAGE_SCAN_BATCH, legacy_metadata, redis_error, redis_unavailable, +}; +use crate::manager::{AppState, SharedState}; +use axum::{Json, http::StatusCode}; +use std::net::IpAddr; + +type ApiResult = Result)>; + +/// Repairs legacy members in the background; failures are logged, not fatal. +pub async fn backfill_legacy_metadata(state: SharedState) { + match backfill(&state).await { + Ok(0) => {}, + Ok(filled) => tracing::info!("blacklist metadata backfill repaired {filled} legacy entries"), + Err((_, Json(body))) => tracing::warn!("blacklist metadata backfill skipped: {body}"), + } +} + +/// Walks the ban set and persists fallback metadata for members without any. +/// +/// Returns the number of repaired members. A Redis failure aborts the run: the +/// next manager start retries, and the read path keeps serving meanwhile. +async fn backfill(state: &AppState) -> ApiResult { + let mut conn = state + .redis_client + .get_multiplexed_async_connection() + .await + .map_err(redis_unavailable)?; + let now = chrono::Utc::now().timestamp(); + let mut cursor = 0_u64; + let mut filled = 0_usize; + loop { + let (next, members): (u64, Vec) = redis::cmd("SSCAN") + .arg(BLACKLIST_KEY) + .arg(cursor) + .arg("COUNT") + .arg(PAGE_SCAN_BATCH) + .query_async(&mut conn) + .await + .map_err(redis_error)?; + let targets: Vec = members + .into_iter() + .filter(|target| target.parse::().is_ok()) + .collect(); + if !targets.is_empty() { + let existing: Vec> = redis::cmd("HMGET") + .arg(BLACKLIST_METADATA_KEY) + .arg(&targets) + .query_async(&mut conn) + .await + .map_err(redis_error)?; + for (target, encoded) in targets.iter().zip(existing) { + if encoded.is_some() { + continue; + } + let encoded = serde_json::to_string(&legacy_metadata(now)).map_err(|_| { + super::common::api_error(StatusCode::INTERNAL_SERVER_ERROR, "failed to encode blacklist metadata") + })?; + let _: i64 = redis::cmd("HSETNX") + .arg(BLACKLIST_METADATA_KEY) + .arg(target) + .arg(encoded) + .query_async(&mut conn) + .await + .map_err(redis_error)?; + filled += 1; + } + } + cursor = next; + if cursor == 0 { + return Ok(filled); + } + } +} diff --git a/src/manager/api/blacklist/common.rs b/src/manager/api/blacklist/common.rs index a3195c8..8b7e176 100644 --- a/src/manager/api/blacklist/common.rs +++ b/src/manager/api/blacklist/common.rs @@ -1,5 +1,8 @@ +//! Shared keys, metadata records and request validation of the blacklist API. + use axum::{Json, http::StatusCode}; use serde::{Deserialize, Serialize}; +use std::net::IpAddr; #[derive(Serialize)] pub(super) struct BlacklistEvent<'a> { @@ -23,9 +26,17 @@ pub(super) const BLACKLIST_CHANNEL: &str = "rampart:blacklist:events"; pub(super) const DEFAULT_BAN_DURATION_SECS: u64 = 300; pub(super) const LEGACY_BAN_DURATION_SECS: u64 = 300; pub(super) const MAX_BAN_DURATION_SECS: u64 = 31_536_000; +/// Maximum accepted length of a ban reason, in bytes. +pub(super) const MAX_REASON_BYTES: usize = 256; +/// Batch size of SSCAN/HMGET/MGET calls on the blacklist. +pub(super) const PAGE_SCAN_BATCH: usize = 100; pub(super) const ADD_BAN_SCRIPT: &str = "redis.call('HSET', KEYS[2], ARGV[1], ARGV[2]); redis.call('SADD', KEYS[1], ARGV[1]); redis.call('PUBLISH', KEYS[3], ARGV[3]); return 1"; pub(super) const REMOVE_BAN_SCRIPT: &str = "redis.call('SREM', KEYS[1], ARGV[1]); redis.call('HDEL', KEYS[2], ARGV[1]); redis.call('PUBLISH', KEYS[3], ARGV[2]); return 1"; +/// Metadata shown for a set member written by an older manager. +/// +/// The read path only displays this record; persisting it is the job of the +/// startup backfill, so a GET never writes to Redis. pub(super) fn legacy_metadata(now: i64) -> BlacklistMetadata { BlacklistMetadata { created_at_unix: now, @@ -55,10 +66,34 @@ pub(super) fn event_payload( .map_err(|_| api_error(StatusCode::INTERNAL_SERVER_ERROR, "failed to serialize blacklist event")) } -pub(super) fn parse_ip(target: &str) -> Result)> { - target - .parse() - .map_err(|_| api_error(StatusCode::BAD_REQUEST, "target must be an IP address")) +/// Validates the `target` of a mutate request. +/// +/// The Redis ban snapshot is keyed by a single address, so a CIDR network is +/// syntactically valid but unsupported and is rejected with an explicit message +/// instead of being stored as an entry the edges cannot apply. +pub(super) fn validate_target(target: &str) -> Result)> { + let target = target.trim(); + if let Ok(ip) = target.parse::() { + return Ok(ip); + } + if crate::manager::security::IpNet::parse(target).is_ok() { + return Err(api_error( + StatusCode::BAD_REQUEST, + "CIDR targets are not supported; ban a single IP address", + )); + } + Err(api_error( + StatusCode::BAD_REQUEST, + "target must be a valid IPv4 or IPv6 address", + )) +} + +/// Rejects a `reason` longer than [`MAX_REASON_BYTES`] bytes. +pub(super) fn validate_reason(reason: &str) -> Result<(), (StatusCode, Json)> { + if reason.len() > MAX_REASON_BYTES { + return Err(api_error(StatusCode::BAD_REQUEST, "reason must not exceed 256 bytes")); + } + Ok(()) } pub(super) fn api_error(status: StatusCode, message: &str) -> (StatusCode, Json) { diff --git a/src/manager/api/blacklist/list.rs b/src/manager/api/blacklist/list.rs index 043cdeb..998401f 100644 --- a/src/manager/api/blacklist/list.rs +++ b/src/manager/api/blacklist/list.rs @@ -1,79 +1,131 @@ +//! `GET /api/v1/blacklist`: paginated, read-only view of the Redis bans. +//! +//! The endpoint never writes: legacy members keep showing a read-only fallback +//! record and are persisted by [`super::backfill_legacy_metadata`] at startup, +//! so retries and shared caches see an idempotent response. + use super::common::{ - BLACKLIST_KEY, BLACKLIST_METADATA_KEY, BlacklistMetadata, format_timestamp, legacy_metadata, redis_error, - redis_unavailable, + BLACKLIST_KEY, BLACKLIST_METADATA_KEY, BlacklistMetadata, PAGE_SCAN_BATCH, format_timestamp, legacy_metadata, + redis_error, redis_unavailable, }; -use super::{BlacklistEntry, BlacklistResponse}; +use super::{BlacklistEntry, BlacklistResponse, ListQuery}; use crate::manager::AppState; -use axum::{Json, extract::State, http::StatusCode}; -use redis::AsyncCommands; +use axum::{ + Json, + extract::{Query, State}, + http::StatusCode, +}; +use redis::aio::MultiplexedConnection; use std::collections::HashMap; +use std::net::IpAddr; use std::sync::Arc; +type ApiResult = Result)>; + pub async fn list_blacklist( State(state): State>, -) -> Result, (StatusCode, Json)> { + Query(query): Query, +) -> ApiResult> { + let (offset, limit) = query.bounds(); let mut conn = state .redis_client .get_multiplexed_async_connection() .await .map_err(redis_unavailable)?; - let members: Vec = redis::cmd("SMEMBERS") + let total: u64 = redis::cmd("SCARD") .arg(BLACKLIST_KEY) .query_async(&mut conn) .await .map_err(redis_error)?; - let metadata: HashMap = conn.hgetall(BLACKLIST_METADATA_KEY).await.map_err(redis_error)?; - let now = chrono::Utc::now().timestamp(); - let mut items = Vec::with_capacity(members.len()); - - for target in members { - let Ok(ip) = target.parse::() else { - continue; - }; - let record = match metadata.get(&target) { - Some(encoded) => match serde_json::from_str::(encoded) { - Ok(record) => record, - Err(_) => continue, - }, - None => { - let legacy = legacy_metadata(now); - let encoded = serde_json::to_string(&legacy).map_err(|_| { - super::common::api_error(StatusCode::INTERNAL_SERVER_ERROR, "failed to encode blacklist metadata") - })?; - let inserted: i64 = redis::cmd("HSETNX") - .arg(BLACKLIST_METADATA_KEY) - .arg(&target) - .arg(encoded) - .query_async(&mut conn) - .await - .map_err(redis_error)?; - if inserted == 1 { - legacy - } else { - let current: Option = - conn.hget(BLACKLIST_METADATA_KEY, &target).await.map_err(redis_error)?; - match current.and_then(|value| serde_json::from_str(&value).ok()) { - Some(record) => record, - None => continue, - } - } - }, - }; - if record.expires_at_unix <= now - || chrono::DateTime::from_timestamp(record.created_at_unix, 0).is_none() - || chrono::DateTime::from_timestamp(record.expires_at_unix, 0).is_none() - { - continue; - } - items.push(BlacklistEntry { - target: ip.to_string(), - entry_type: "ip".to_string(), - reason: record.reason, - created_at: format_timestamp(record.created_at_unix), - expires_at: Some(format_timestamp(record.expires_at_unix)), - }); + if limit == 0 { + return Ok(Json(BlacklistResponse { + items: Vec::new(), + total, + })); } - let total = items.len(); + // SSCAN is capped at the requested window, so the set is never materialised. + let targets = scan_targets(&mut conn, offset.saturating_add(limit)).await?; + let page: Vec = targets + .into_iter() + .skip(usize::try_from(offset).unwrap_or(usize::MAX)) + .take(usize::try_from(limit).unwrap_or(usize::MAX)) + .collect(); + let metadata = load_metadata(&mut conn, &page).await?; + let now = chrono::Utc::now().timestamp(); + let items = page + .iter() + .filter_map(|target| entry(target, metadata.get(target), now)) + .collect(); Ok(Json(BlacklistResponse { items, total })) } + +/// Collects at most `wanted` set members with SSCAN. +async fn scan_targets(conn: &mut MultiplexedConnection, wanted: u64) -> ApiResult> { + let mut targets = Vec::new(); + let mut cursor = 0_u64; + loop { + let (next, batch): (u64, Vec) = redis::cmd("SSCAN") + .arg(BLACKLIST_KEY) + .arg(cursor) + .arg("COUNT") + .arg(PAGE_SCAN_BATCH) + .query_async(conn) + .await + .map_err(redis_error)?; + targets.extend(batch); + cursor = next; + if cursor == 0 || u64::try_from(targets.len()).unwrap_or(u64::MAX) >= wanted { + return Ok(targets); + } + } +} + +/// Fetches metadata for `targets` in HMGET batches. +/// +/// A present key with an unparseable record maps to `None`, which the caller +/// skips; an absent key means the member predates metadata and gets a fallback. +async fn load_metadata( + conn: &mut MultiplexedConnection, + targets: &[String], +) -> ApiResult>> { + let mut metadata = HashMap::with_capacity(targets.len()); + for chunk in targets.chunks(PAGE_SCAN_BATCH) { + let values: Vec> = redis::cmd("HMGET") + .arg(BLACKLIST_METADATA_KEY) + .arg(chunk) + .query_async(conn) + .await + .map_err(redis_error)?; + for (target, encoded) in chunk.iter().zip(values) { + metadata.insert( + target.clone(), + encoded.and_then(|value| serde_json::from_str(&value).ok()), + ); + } + } + Ok(metadata) +} + +/// Builds one response entry, dropping expired and malformed records. +fn entry(target: &str, metadata: Option<&Option>, now: i64) -> Option { + let ip: IpAddr = target.parse().ok()?; + let record = match metadata { + Some(Some(record)) => record.clone(), + Some(None) => return None, + None => legacy_metadata(now), + }; + if record.expires_at_unix <= now + || chrono::DateTime::from_timestamp(record.created_at_unix, 0).is_none() + || chrono::DateTime::from_timestamp(record.expires_at_unix, 0).is_none() + { + return None; + } + Some(BlacklistEntry { + target: ip.to_string(), + entry_type: "ip".to_string(), + reason: record.reason, + created_at: format_timestamp(record.created_at_unix), + expires_at: Some(format_timestamp(record.expires_at_unix)), + }) +} diff --git a/src/manager/api/blacklist/mutate.rs b/src/manager/api/blacklist/mutate.rs index ceaa5e5..1038ee2 100644 --- a/src/manager/api/blacklist/mutate.rs +++ b/src/manager/api/blacklist/mutate.rs @@ -1,6 +1,9 @@ +//! `POST`/`DELETE /api/v1/blacklist`: validated ban and unban mutations. + use super::common::{ ADD_BAN_SCRIPT, BLACKLIST_CHANNEL, BLACKLIST_KEY, BLACKLIST_METADATA_KEY, DEFAULT_BAN_DURATION_SECS, - MAX_BAN_DURATION_SECS, REMOVE_BAN_SCRIPT, api_error, event_payload, parse_ip, redis_error, redis_unavailable, + MAX_BAN_DURATION_SECS, REMOVE_BAN_SCRIPT, api_error, event_payload, redis_error, redis_unavailable, + validate_reason, validate_target, }; use super::{AddBlacklistRequest, RemoveBlacklistRequest}; use crate::manager::AppState; @@ -11,7 +14,8 @@ pub async fn add_blacklist( State(state): State>, Json(req): Json, ) -> Result, (StatusCode, Json)> { - let ip = parse_ip(&req.target)?; + let ip = validate_target(&req.target)?; + validate_reason(&req.reason)?; if req.entry_type != "ip" { return Err(api_error( StatusCode::BAD_REQUEST, @@ -73,7 +77,7 @@ pub async fn remove_blacklist( State(state): State>, Json(req): Json, ) -> Result, (StatusCode, Json)> { - let ip = parse_ip(&req.target)?; + let ip = validate_target(&req.target)?; let target = ip.to_string(); let event = event_payload(&target, "unban", 0, None)?; let mut conn = state diff --git a/src/manager/api/guard/limit.rs b/src/manager/api/guard/limit.rs new file mode 100644 index 0000000..2a1d92f --- /dev/null +++ b/src/manager/api/guard/limit.rs @@ -0,0 +1,89 @@ +//! Per-IP attempt throttling for login and mutating requests. +//! +//! Both limiters share one representation, `IpAddr -> (window start, attempts)`. +//! A counter resets when its window elapses, a successful login clears the entry +//! outright, and an eviction sweep keeps the map from growing one entry per +//! source address forever. + +use super::RequestGuard; +use axum::{ + Json, + extract::{Request, State}, + http::StatusCode, + middleware::Next, + response::Response, +}; +use dashmap::DashMap; +use std::net::IpAddr; +use std::sync::Arc; +use std::time::{Duration, Instant}; + +/// Sliding window of the login limiter. +pub const LOGIN_WINDOW: Duration = Duration::from_secs(60); +/// Login attempts allowed per window and source address. +pub const LOGIN_MAX_ATTEMPTS: u32 = 5; +/// Sliding window of the mutating-request limiter. +pub const MUTATION_WINDOW: Duration = Duration::from_secs(60); +/// Mutating requests allowed per window and source address. +pub const MUTATION_MAX_ATTEMPTS: u32 = 30; + +/// Records one attempt for `ip` and reports whether it is allowed. +/// +/// The first attempt after `window` starts a fresh window; once `max` attempts +/// were spent the call returns `false` without extending the window. +pub fn check_attempt(limiter: &DashMap, ip: IpAddr, window: Duration, max: u32) -> bool { + let now = Instant::now(); + let mut slot = limiter.entry(ip).or_insert((now, 0)); + let (window_start, attempts) = &mut *slot; + if now.duration_since(*window_start) >= window { + *window_start = now; + *attempts = 1; + } else if *attempts >= max { + return false; + } else { + *attempts += 1; + } + true +} + +/// Drops the counter of `ip`, used after a successful login. +pub fn reset_attempts(limiter: &DashMap, ip: IpAddr) { + limiter.remove(&ip); +} + +/// Removes every counter whose window already elapsed. +pub fn evict_idle(limiter: &DashMap, window: Duration) { + let now = Instant::now(); + limiter.retain(|_, (window_start, _)| now.duration_since(*window_start) < window); +} + +/// Reports whether `method` changes server state and therefore is rate limited. +#[must_use] +pub fn is_mutating(method: &axum::http::Method) -> bool { + matches!( + *method, + axum::http::Method::POST | axum::http::Method::PUT | axum::http::Method::PATCH | axum::http::Method::DELETE + ) +} + +/// Middleware that throttles mutating requests per client address. +/// +/// Read-only requests pass through untouched so the limiter never affects the +/// inventory and blacklist views. Authenticated mutations share one budget per +/// address, regardless of which endpoint they target. +pub async fn rate_limit_mutations( + State(guard): State>, + request: Request, + next: Next, +) -> Result)> { + if is_mutating(request.method()) { + let ip = guard.request_client_ip(&request); + if !guard.allow_mutation(ip) { + return Err(( + StatusCode::TOO_MANY_REQUESTS, + Json(serde_json::json!({"error": "too many requests"})), + )); + } + } + Ok(next.run(request).await) +} diff --git a/src/manager/api/guard/mod.rs b/src/manager/api/guard/mod.rs new file mode 100644 index 0000000..91be304 --- /dev/null +++ b/src/manager/api/guard/mod.rs @@ -0,0 +1,111 @@ +//! HTTP hardening shared by the manager endpoints. +//! +//! Owns the [`RequestGuard`] (proxy-aware client address plus the mutating +//! request limiter), the per-IP attempt helpers and [`build_router`], so the +//! daemon and the integration tests exercise the same body limit, timeout, CORS +//! and rate-limit stack. + +pub mod limit; +pub mod proxy; +mod router; + +use axum::extract::ConnectInfo; +pub use limit::{check_attempt, evict_idle, reset_attempts}; +pub use proxy::{TRUSTED_PROXIES_ENV, TrustedProxies}; +pub use router::{MAX_BODY_BYTES, REQUEST_TIMEOUT, build_router}; + +use crate::manager::SharedState; +use axum::{extract::Request, http::HeaderMap}; +use dashmap::DashMap; +use std::net::{IpAddr, Ipv4Addr, SocketAddr}; +use std::sync::Arc; +use std::time::{Duration, Instant}; +use tokio::sync::watch; +use tokio::task::JoinHandle; + +/// How often the background eviction task sweeps idle limiter entries. +const EVICTION_INTERVAL: Duration = Duration::from_secs(60); + +/// Per-request security context: trusted proxies and the mutation budget. +pub struct RequestGuard { + trusted_proxies: TrustedProxies, + mutations: DashMap, +} + +impl RequestGuard { + /// Builds a guard for `trusted_proxies` with an empty mutation budget. + #[must_use] + pub fn new(trusted_proxies: TrustedProxies) -> Self { + Self { + trusted_proxies, + mutations: DashMap::new(), + } + } + + /// Builds a guard from `MANAGER_TRUSTED_PROXIES`. + /// + /// # Errors + /// Fails when the variable contains a malformed network entry. + pub fn from_env() -> anyhow::Result { + Ok(Self::new(TrustedProxies::from_env()?)) + } + + /// Resolves the client address from the peer address and forwarded chain. + #[must_use] + pub fn client_ip(&self, peer: IpAddr, headers: &HeaderMap) -> IpAddr { + self.trusted_proxies.client_ip(peer, headers.get("x-forwarded-for")) + } + + /// Resolves the client address of `request`, falling back to the unspecified + /// address when the server was built without connect info. + #[must_use] + pub fn request_client_ip(&self, request: &Request) -> IpAddr { + let peer = request + .extensions() + .get::>() + .map_or(IpAddr::V4(Ipv4Addr::UNSPECIFIED), |info| info.0.ip()); + self.client_ip(peer, request.headers()) + } + + /// Records one mutating request for `ip` and reports whether it is allowed. + pub fn allow_mutation(&self, ip: IpAddr) -> bool { + check_attempt( + &self.mutations, + ip, + limit::MUTATION_WINDOW, + limit::MUTATION_MAX_ATTEMPTS, + ) + } + + /// Drops mutation counters whose window elapsed. + pub fn evict_idle(&self) { + evict_idle(&self.mutations, limit::MUTATION_WINDOW); + } +} + +/// Sweeps idle login and mutation counters until shutdown is requested. +/// +/// Without the sweep a long-lived manager keeps one map entry per source +/// address forever, which slowly turns the limiters into a memory leak. +pub async fn run_eviction(state: SharedState, guard: Arc, mut shutdown: watch::Receiver) { + let mut ticker = tokio::time::interval(EVICTION_INTERVAL); + ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay); + loop { + tokio::select! { + _ = ticker.tick() => { + evict_idle(&state.login_limiter, limit::LOGIN_WINDOW); + guard.evict_idle(); + }, + changed = shutdown.changed() => { + if changed.is_err() || *shutdown.borrow_and_update() { + return; + } + }, + } + } +} + +/// Spawns [`run_eviction`] on the current runtime. +pub fn spawn_eviction(state: SharedState, guard: Arc, shutdown: watch::Receiver) -> JoinHandle<()> { + tokio::spawn(run_eviction(state, guard, shutdown)) +} diff --git a/src/manager/api/guard/proxy.rs b/src/manager/api/guard/proxy.rs new file mode 100644 index 0000000..04edd77 --- /dev/null +++ b/src/manager/api/guard/proxy.rs @@ -0,0 +1,86 @@ +//! Proxy-aware client address resolution. +//! +//! Behind a reverse proxy every request arrives from the proxy address, so a +//! per-IP limiter would throttle all administrators together. `X-Forwarded-For` +//! is therefore trusted only when the TCP peer belongs to an explicitly +//! configured network; otherwise the header is ignored and the peer address is +//! used, which keeps a directly connected client from spoofing its identity. + +use crate::manager::security::IpNet; +use anyhow::Result; +use axum::http::HeaderValue; +use std::net::IpAddr; + +/// Environment variable listing trusted proxy networks, comma separated. +pub const TRUSTED_PROXIES_ENV: &str = "MANAGER_TRUSTED_PROXIES"; + +/// Networks whose `X-Forwarded-For` header is trusted. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct TrustedProxies { + nets: Vec, +} + +impl TrustedProxies { + /// Parses a comma-separated list of networks. + /// + /// An empty or whitespace-only value trusts no proxy, which is the safe + /// default for a manager exposed directly. + /// + /// # Errors + /// Fails on an empty entry or on a malformed address/CIDR, so a typo cannot + /// silently widen the trust boundary. + pub fn parse(raw: &str) -> Result { + let raw = raw.trim(); + if raw.is_empty() { + return Ok(Self::default()); + } + let mut nets = Vec::new(); + for entry in raw.split(',') { + let entry = entry.trim(); + if entry.is_empty() { + anyhow::bail!("{TRUSTED_PROXIES_ENV} contains an empty entry"); + } + nets.push(IpNet::parse(entry)?); + } + Ok(Self { nets }) + } + + /// Reads [`TRUSTED_PROXIES_ENV`] from the process environment. + /// + /// # Errors + /// Propagates the same validation as [`TrustedProxies::parse`]. + pub fn from_env() -> Result { + Self::parse(&std::env::var(TRUSTED_PROXIES_ENV).unwrap_or_default()) + } + + /// Reports whether `ip` is a configured proxy. + #[must_use] + pub fn is_trusted(&self, ip: IpAddr) -> bool { + self.nets.iter().any(|net| net.contains(ip)) + } + + /// Resolves the client address for a request from `peer`. + /// + /// The forwarded chain is walked from right to left, skipping proxies the + /// manager trusts, and the first untrusted hop wins: that is the address + /// the nearest trusted proxy observed. A malformed chain falls back to the + /// last trusted hop resolved so far, never to an unvalidated entry. + #[must_use] + pub fn client_ip(&self, peer: IpAddr, forwarded_for: Option<&HeaderValue>) -> IpAddr { + if !self.is_trusted(peer) { + return peer; + } + let Some(chain) = forwarded_for.and_then(|value| value.to_str().ok()) else { + return peer; + }; + let mut resolved = peer; + for entry in chain.split(',').rev() { + match entry.trim().parse::() { + Ok(ip) if !self.is_trusted(ip) => return ip, + Ok(ip) => resolved = ip, + Err(_) => break, + } + } + resolved + } +} diff --git a/src/manager/api/guard/router.rs b/src/manager/api/guard/router.rs new file mode 100644 index 0000000..3bf661f --- /dev/null +++ b/src/manager/api/guard/router.rs @@ -0,0 +1,76 @@ +//! Router assembly for the manager API. +//! +//! Every deployment path, including integration tests, builds the router here +//! so the body limit, request deadline, CORS policy and per-IP rate limiting +//! cannot drift between the daemon and its tests. + +use super::RequestGuard; +#[cfg(feature = "store-redis")] +use super::limit::rate_limit_mutations; +#[cfg(feature = "store-redis")] +use crate::manager::auth; +use crate::manager::{SharedState, api}; +#[cfg(feature = "store-redis")] +use axum::middleware; +use axum::{ + Extension, Router, + extract::DefaultBodyLimit, + http::StatusCode, + routing::{get, post}, +}; +use std::sync::Arc; +use std::time::Duration; +use tower_http::{cors::CorsLayer, timeout::TimeoutLayer}; + +/// Hard cap on any request body accepted by the manager API. +/// +/// The largest documented payload is a blacklist entry with a 256-byte reason, +/// so 8 KiB leaves room for JSON overhead while keeping an unauthenticated +/// client from buffering megabytes. +pub const MAX_BODY_BYTES: usize = 8 * 1024; +/// Whole-request deadline, including authentication and a Redis round trip. +pub const REQUEST_TIMEOUT: Duration = Duration::from_secs(10); + +/// Builds the complete manager router. +/// +/// `cors` is the layer derived from `CORS_ORIGIN`; `None` serves no cross-origin +/// policy at all. The returned router is ready to be attached to a listener +/// through `into_make_service_with_connect_info`, which the handlers require for +/// the client address. +pub fn build_router(state: SharedState, guard: Arc, cors: Option) -> Router { + let public = Router::new() + .route("/api/v1/health", get(api::inventory::health::health_check)) + .route("/api/v1/auth/login", post(api::auth::login)); + + // Redis-backed routes only exist together with the feature; the manager + // refuses to start without it, so 501 stubs here would be unreachable. + #[cfg(feature = "store-redis")] + let protected = Router::new() + .route("/api/v1/servers", get(api::inventory::servers::list_servers)) + .route( + "/api/v1/blacklist", + get(api::blacklist::list_blacklist) + .post(api::blacklist::add_blacklist) + .delete(api::blacklist::remove_blacklist), + ) + .route("/api/v1/nodes", get(api::inventory::nodes::list_nodes)) + .route_layer(middleware::from_fn_with_state(guard.clone(), rate_limit_mutations)) + .route_layer(middleware::from_fn_with_state(state.clone(), auth::auth_middleware)); + #[cfg(not(feature = "store-redis"))] + let protected = Router::new(); + + let mut app = Router::new() + .merge(public) + .merge(protected) + .with_state(state) + .layer(Extension(guard)) + .layer(DefaultBodyLimit::max(MAX_BODY_BYTES)) + .layer(TimeoutLayer::with_status_code( + StatusCode::REQUEST_TIMEOUT, + REQUEST_TIMEOUT, + )); + if let Some(cors) = cors { + app = app.layer(cors); + } + app +} diff --git a/src/manager/api/inventory/mod.rs b/src/manager/api/inventory/mod.rs index c969e20..ae05bc6 100644 --- a/src/manager/api/inventory/mod.rs +++ b/src/manager/api/inventory/mod.rs @@ -1,6 +1,66 @@ //! Manager API inventory: health, nodes and servers. //! -//! Owns the read-side endpoints that describe the fleet as the manager sees it. +//! Owns the read-side endpoints that describe the fleet as the manager sees it, +//! plus the shared SCAN/MGET reader that keeps those reads non-blocking. + pub mod health; pub mod nodes; pub mod servers; + +/// SCAN and MGET batch size of a fleet read. +#[cfg(feature = "store-redis")] +const READ_BATCH: usize = 100; + +/// Reads every value stored under `pattern` via SCAN and batched MGET. +/// +/// SCAN is used instead of `KEYS` because the latter blocks Redis for every +/// edge in the fleet. Values are fetched in MGET batches instead of one GET per +/// key, so a large fleet costs a bounded number of round trips. +/// +/// # Errors +/// Returns the Redis error unchanged: the caller answers 503, because an empty +/// fleet and an unreachable store must stay distinguishable. +#[cfg(feature = "store-redis")] +pub(super) async fn scan_values( + conn: &mut redis::aio::MultiplexedConnection, + pattern: &str, +) -> redis::RedisResult> { + use futures::StreamExt; + use redis::AsyncCommands; + + let opts = redis::ScanOptions::default() + .with_pattern(pattern) + .with_count(READ_BATCH); + let mut iter = conn.scan_options::(opts).await?; + let mut keys = Vec::new(); + while let Some(key) = iter.next().await { + keys.push(key?); + } + drop(iter); + + let mut values = Vec::with_capacity(keys.len()); + for chunk in keys.chunks(READ_BATCH) { + let batch: Vec> = redis::cmd("MGET").arg(chunk).query_async(conn).await?; + values.extend(batch.into_iter().flatten()); + } + Ok(values) +} + +/// Parses every value that is a valid JSON record, skipping corrupt entries. +#[cfg(feature = "store-redis")] +pub(super) fn decode_all(values: &[String]) -> Vec { + values + .iter() + .filter_map(|value| serde_json::from_str(value).ok()) + .collect() +} + +/// Maps a Redis read failure to 503 so it cannot be mistaken for an empty fleet. +#[cfg(feature = "store-redis")] +pub(super) fn unavailable(error: &redis::RedisError) -> (axum::http::StatusCode, axum::Json) { + tracing::error!("inventory Redis read failed: {error}"); + ( + axum::http::StatusCode::SERVICE_UNAVAILABLE, + axum::Json(serde_json::json!({"error": "redis unavailable"})), + ) +} diff --git a/src/manager/api/inventory/nodes.rs b/src/manager/api/inventory/nodes.rs index 73ec5c7..cef4a8f 100644 --- a/src/manager/api/inventory/nodes.rs +++ b/src/manager/api/inventory/nodes.rs @@ -1,13 +1,17 @@ +//! `GET /api/v1/nodes`: registered edge nodes from the Redis heartbeat keys. + #[cfg(feature = "store-redis")] use crate::manager::AppState; #[cfg(feature = "store-redis")] -use axum::{Json, extract::State}; -#[cfg(feature = "store-redis")] -use redis::AsyncCommands; +use axum::{Json, extract::State, http::StatusCode}; use serde::{Deserialize, Serialize}; #[cfg(feature = "store-redis")] use std::sync::Arc; +/// SCAN pattern of node records. +#[cfg(feature = "store-redis")] +const NODES_PATTERN: &str = "rampart:nodes:*"; + #[derive(Debug, Serialize, Deserialize)] pub struct NodeInfo { pub id: String, @@ -22,27 +26,24 @@ pub struct NodesResponse { pub nodes: Vec, } +/// Lists the fleet with SSCAN-style iteration and batched reads. +/// +/// # Errors +/// Returns 503 when Redis is unreachable or a command fails; an empty `nodes` +/// array then always means a healthy but empty fleet. #[cfg(feature = "store-redis")] -pub async fn list_nodes(State(state): State>) -> Json { - let mut conn = match state.redis_client.get_multiplexed_async_connection().await { - Ok(c) => c, - Err(_) => return Json(NodesResponse { nodes: vec![] }), - }; - - let keys: Vec = match redis::cmd("KEYS").arg("rampart:nodes:*").query_async(&mut conn).await { - Ok(k) => k, - Err(_) => return Json(NodesResponse { nodes: vec![] }), - }; - - let mut nodes = Vec::with_capacity(keys.len()); - for key in &keys { - let raw: Option = conn.get(key).await.unwrap_or(None); - if let Some(json) = raw - && let Ok(node) = serde_json::from_str::(&json) - { - nodes.push(node); - } - } - - Json(NodesResponse { nodes }) +pub async fn list_nodes( + State(state): State>, +) -> Result, (StatusCode, Json)> { + let mut conn = state + .redis_client + .get_multiplexed_async_connection() + .await + .map_err(|error| super::unavailable(&error))?; + let values = super::scan_values(&mut conn, NODES_PATTERN) + .await + .map_err(|error| super::unavailable(&error))?; + Ok(Json(NodesResponse { + nodes: super::decode_all(&values), + })) } diff --git a/src/manager/api/inventory/servers.rs b/src/manager/api/inventory/servers.rs index fa009a1..94778a4 100644 --- a/src/manager/api/inventory/servers.rs +++ b/src/manager/api/inventory/servers.rs @@ -1,13 +1,17 @@ +//! `GET /api/v1/servers`: backend servers from the Redis registry keys. + #[cfg(feature = "store-redis")] use crate::manager::AppState; #[cfg(feature = "store-redis")] -use axum::{Json, extract::State}; -#[cfg(feature = "store-redis")] -use redis::AsyncCommands; +use axum::{Json, extract::State, http::StatusCode}; use serde::{Deserialize, Serialize}; #[cfg(feature = "store-redis")] use std::sync::Arc; +/// SCAN pattern of server records. +#[cfg(feature = "store-redis")] +const SERVERS_PATTERN: &str = "rampart:servers:*"; + #[derive(Debug, Serialize, Deserialize)] pub struct ServerEntry { pub name: String, @@ -23,27 +27,24 @@ pub struct ServersResponse { pub servers: Vec, } +/// Lists the registry with SCAN and batched MGET reads. +/// +/// # Errors +/// Returns 503 when Redis is unreachable or a command fails; an empty `servers` +/// array then always means a healthy but empty registry. #[cfg(feature = "store-redis")] -pub async fn list_servers(State(state): State>) -> Json { - let mut conn = match state.redis_client.get_multiplexed_async_connection().await { - Ok(c) => c, - Err(_) => return Json(ServersResponse { servers: vec![] }), - }; - - let keys: Vec = match redis::cmd("KEYS").arg("rampart:servers:*").query_async(&mut conn).await { - Ok(k) => k, - Err(_) => return Json(ServersResponse { servers: vec![] }), - }; - - let mut servers = Vec::with_capacity(keys.len()); - for key in &keys { - let raw: Option = conn.get(key).await.unwrap_or(None); - if let Some(json) = raw - && let Ok(server) = serde_json::from_str::(&json) - { - servers.push(server); - } - } - - Json(ServersResponse { servers }) +pub async fn list_servers( + State(state): State>, +) -> Result, (StatusCode, Json)> { + let mut conn = state + .redis_client + .get_multiplexed_async_connection() + .await + .map_err(|error| super::unavailable(&error))?; + let values = super::scan_values(&mut conn, SERVERS_PATTERN) + .await + .map_err(|error| super::unavailable(&error))?; + Ok(Json(ServersResponse { + servers: super::decode_all(&values), + })) } diff --git a/src/manager/api/mod.rs b/src/manager/api/mod.rs index 9181329..6c2aa7c 100644 --- a/src/manager/api/mod.rs +++ b/src/manager/api/mod.rs @@ -1,3 +1,11 @@ +//! Manager HTTP API. +//! +//! Owns the route handlers (`auth`, `blacklist`, `inventory`) and the shared +//! HTTP hardening in [`guard`], including the only supported way to assemble +//! the service. pub mod auth; pub mod blacklist; +pub mod guard; pub mod inventory; + +pub use guard::build_router; diff --git a/src/manager/security.rs b/src/manager/security.rs index 305b45e..e7a46a6 100644 --- a/src/manager/security.rs +++ b/src/manager/security.rs @@ -7,8 +7,9 @@ //! `CORS_ORIGIN` value instead of silently allowing every origin. use anyhow::{Result, bail}; +use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; use subtle::ConstantTimeEq; -use tower_http::cors::{AllowOrigin, Any, CorsLayer}; +use tower_http::cors::{AllowOrigin, CorsLayer}; /// Minimum length of `API_PASSWORD` in characters. const MIN_API_PASSWORD_CHARS: usize = 16; @@ -117,19 +118,95 @@ impl CorsPolicy { /// Builds the axum CORS layer for this policy. /// + /// The layer only configures origins, methods and headers, so a browser + /// preflight reaches the same endpoints the API documents. It does not + /// enable credentials: the manager authenticates with a bearer token. + /// /// Returns `None` for [`CorsPolicy::Deny`] so the router is served without /// any cross-origin layer. #[must_use] pub fn cors_layer(&self) -> Option { - match self { - Self::Deny => None, - Self::Any => Some(CorsLayer::new().allow_origin(Any)), + let origin = match self { + Self::Deny => return None, + Self::Any => AllowOrigin::any(), Self::AllowList(origins) => { let allowed = origins .iter() .filter_map(|origin| axum::http::HeaderValue::from_str(origin).ok()); - Some(CorsLayer::new().allow_origin(AllowOrigin::list(allowed))) + AllowOrigin::list(allowed) }, + }; + Some( + CorsLayer::new() + .allow_origin(origin) + .allow_methods([ + axum::http::Method::GET, + axum::http::Method::POST, + axum::http::Method::DELETE, + ]) + .allow_headers([axum::http::header::AUTHORIZATION, axum::http::header::CONTENT_TYPE]), + ) + } +} + +/// An IPv4 or IPv6 network in CIDR notation. +/// +/// A bare address parses as a host route (`/32` or `/128`). Used for the +/// `MANAGER_TRUSTED_PROXIES` policy, where a too-broad entry would let a +/// client spoof its address through `X-Forwarded-For`. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct IpNet { + addr: IpAddr, + prefix: u8, +} + +impl IpNet { + /// Parses `10.0.0.0/8`, `2001:db8::/32` or a bare address. + /// + /// # Errors + /// Fails when the address or the prefix is malformed, and when the prefix + /// length exceeds the address width (32 or 128 bits). + pub fn parse(value: &str) -> Result { + let value = value.trim(); + let (addr, prefix) = match value.split_once('/') { + Some((addr, prefix)) => (addr, Some(prefix)), + None => (value, None), + }; + let addr: IpAddr = addr + .parse() + .map_err(|_| anyhow::anyhow!("'{value}' is not an IP address or CIDR network"))?; + let width = if addr.is_ipv4() { 32 } else { 128 }; + let prefix = match prefix { + Some(prefix) => prefix + .parse::() + .map_err(|_| anyhow::anyhow!("'{value}' has an invalid prefix length"))?, + None => width, + }; + if prefix > width { + bail!("'{value}' prefix length exceeds the {width}-bit address width"); + } + Ok(Self { addr, prefix }) + } + + /// Reports whether `ip` belongs to this network. + #[must_use] + pub fn contains(&self, ip: IpAddr) -> bool { + match (self.addr, ip) { + (IpAddr::V4(net), IpAddr::V4(ip)) => mask_v4(net, self.prefix) == mask_v4(ip, self.prefix), + (IpAddr::V6(net), IpAddr::V6(ip)) => mask_v6(net, self.prefix) == mask_v6(ip, self.prefix), + _ => false, } } } + +/// Returns the network bits of `addr`; a zero prefix masks everything. +fn mask_v4(addr: Ipv4Addr, prefix: u8) -> u32 { + let shift = u32::from(32_u8.saturating_sub(prefix)); + u32::from(addr) & u32::MAX.checked_shl(shift).unwrap_or(0) +} + +/// Returns the network bits of `addr`; a zero prefix masks everything. +fn mask_v6(addr: Ipv6Addr, prefix: u8) -> u128 { + let shift = u32::from(128_u8.saturating_sub(prefix)); + u128::from(addr) & u128::MAX.checked_shl(shift).unwrap_or(0) +} diff --git a/tests/manager_api.rs b/tests/manager_api.rs new file mode 100644 index 0000000..2dbd045 --- /dev/null +++ b/tests/manager_api.rs @@ -0,0 +1,282 @@ +//! Manager HTTP API contract: authentication, request validation, body limit, +//! per-IP rate limiting, Redis failure mapping and CORS preflight. +//! +//! The tests drive the production router through `tower::ServiceExt::oneshot`, +//! so they exercise the same layer stack as the daemon without opening a +//! listening socket. The Redis URL points at a closed loopback port; no server +//! is started and no external network is used. + +#![cfg(feature = "store-redis")] + +use axum::{ + Router, + body::Body, + extract::ConnectInfo, + http::{Method, Request, StatusCode, header}, +}; +use dashmap::DashMap; +use rampart::manager::{ + AppState, + api::{ + blacklist::{DEFAULT_PAGE_LIMIT, ListQuery, MAX_PAGE_LIMIT, MAX_PAGE_OFFSET}, + build_router, + guard::RequestGuard, + guard::limit::MUTATION_MAX_ATTEMPTS, + guard::proxy::TrustedProxies, + }, + auth::create_token, + security::CorsPolicy, +}; +use std::net::SocketAddr; +use std::sync::Arc; +use tower::ServiceExt; + +const SECRET: &str = "0123456789abcdef0123456789abcdef"; +const AUDIENCE: &str = "rampart"; +const PASSWORD: &str = "correct-horse-battery-staple"; +const UNREACHABLE_REDIS: &str = "redis://127.0.0.1:1/0"; +const LOGIN_BODY: &str = r#"{"password":"wrong-password"}"#; +const BAN_BODY: &str = r#"{"target":"1.2.3.4","type":"ip","reason":"manual_ban"}"#; + +fn peer() -> SocketAddr { + SocketAddr::from(([10, 0, 0, 5], 53_000)) +} + +fn state(redis_url: &str) -> Arc { + Arc::new(AppState { + redis_client: redis::Client::open(redis_url).expect("redis URL must parse"), + jwt_secret: SECRET.to_string(), + jwt_audience: AUDIENCE.to_string(), + jwt_expiration: 3600, + api_password: PASSWORD.to_string(), + login_limiter: DashMap::new(), + }) +} + +/// Builds the production router with no trusted proxy and no CORS layer. +fn app() -> Router { + build_router( + state(UNREACHABLE_REDIS), + Arc::new(RequestGuard::new(TrustedProxies::default())), + None, + ) +} + +fn request(method: Method, uri: &str, body: Body) -> Request { + Request::builder() + .method(method) + .uri(uri) + .extension(ConnectInfo(peer())) + .header(header::CONTENT_TYPE, "application/json") + .body(body) + .expect("request must build") +} + +fn authorized(mut request: Request) -> Request { + let token = create_token(SECRET, 3600, AUDIENCE).expect("token must be created"); + request.headers_mut().insert( + header::AUTHORIZATION, + format!("Bearer {token}").parse().expect("header value must be valid"), + ); + request +} + +async fn status(router: &Router, request: Request) -> StatusCode { + router + .clone() + .oneshot(request) + .await + .expect("router must answer") + .status() +} + +#[tokio::test] +async fn protected_routes_require_a_token() { + let router = app(); + for uri in ["/api/v1/servers", "/api/v1/nodes", "/api/v1/blacklist"] { + let response = status(&router, request(Method::GET, uri, Body::empty())).await; + assert_eq!(response, StatusCode::UNAUTHORIZED, "{uri} must reject anonymous access"); + } +} + +#[tokio::test] +async fn blacklist_rejects_invalid_targets() { + let router = app(); + for target in ["not-an-ip", "10.0.0.0/8", "999.1.1.1", ""] { + let body = format!(r#"{{"target":"{target}","type":"ip","reason":"manual_ban"}}"#); + let response = status( + &router, + authorized(request(Method::POST, "/api/v1/blacklist", Body::from(body))), + ) + .await; + assert_eq!(response, StatusCode::BAD_REQUEST, "target '{target}' must be rejected"); + } + let body = r#"{"target":"300.1.1.1"}"#; + let response = status( + &router, + authorized(request(Method::DELETE, "/api/v1/blacklist", Body::from(body))), + ) + .await; + assert_eq!(response, StatusCode::BAD_REQUEST); +} + +#[tokio::test] +async fn blacklist_rejects_an_overlong_reason() { + let reason = "a".repeat(257); + let body = format!(r#"{{"target":"1.2.3.4","type":"ip","reason":"{reason}"}}"#); + let response = status( + &app(), + authorized(request(Method::POST, "/api/v1/blacklist", Body::from(body))), + ) + .await; + assert_eq!(response, StatusCode::BAD_REQUEST); +} + +#[tokio::test] +async fn oversized_body_is_rejected_before_the_handler() { + let reason = "a".repeat(9 * 1024); + let body = format!(r#"{{"target":"1.2.3.4","type":"ip","reason":"{reason}"}}"#); + let response = status( + &app(), + authorized(request(Method::POST, "/api/v1/blacklist", Body::from(body))), + ) + .await; + assert_eq!(response, StatusCode::PAYLOAD_TOO_LARGE); +} + +#[tokio::test] +async fn login_is_rate_limited_per_client() { + let router = app(); + for attempt in 1..=5 { + let response = status( + &router, + request(Method::POST, "/api/v1/auth/login", Body::from(LOGIN_BODY)), + ) + .await; + assert_eq!( + response, + StatusCode::UNAUTHORIZED, + "attempt {attempt} must reach the password check" + ); + } + let response = status( + &router, + request(Method::POST, "/api/v1/auth/login", Body::from(LOGIN_BODY)), + ) + .await; + assert_eq!(response, StatusCode::TOO_MANY_REQUESTS); +} + +#[tokio::test] +async fn mutating_requests_are_rate_limited_per_client() { + let router = app(); + for _ in 0..MUTATION_MAX_ATTEMPTS { + let response = status( + &router, + authorized(request(Method::POST, "/api/v1/blacklist", Body::from(BAN_BODY))), + ) + .await; + assert_ne!( + response, + StatusCode::TOO_MANY_REQUESTS, + "budget must cover the first window" + ); + } + let response = status( + &router, + authorized(request(Method::POST, "/api/v1/blacklist", Body::from(BAN_BODY))), + ) + .await; + assert_eq!(response, StatusCode::TOO_MANY_REQUESTS); +} + +#[tokio::test] +async fn redis_failure_is_distinguishable_from_an_empty_fleet() { + let router = app(); + for uri in ["/api/v1/nodes", "/api/v1/servers", "/api/v1/blacklist"] { + let response = status(&router, authorized(request(Method::GET, uri, Body::empty()))).await; + assert_eq!( + response, + StatusCode::SERVICE_UNAVAILABLE, + "{uri} must report a store failure" + ); + } +} + +#[tokio::test] +async fn cors_preflight_answers_only_configured_origins() { + let policy = CorsPolicy::parse(Some("https://admin.example")).expect("policy must parse"); + let router = build_router( + state(UNREACHABLE_REDIS), + Arc::new(RequestGuard::new(TrustedProxies::default())), + policy.cors_layer(), + ); + + let allowed = preflight(&router, "https://admin.example").await; + assert_eq!(allowed.status(), StatusCode::OK); + assert_eq!( + allowed + .headers() + .get(header::ACCESS_CONTROL_ALLOW_ORIGIN) + .and_then(|value| value.to_str().ok()), + Some("https://admin.example") + ); + let methods = allowed + .headers() + .get(header::ACCESS_CONTROL_ALLOW_METHODS) + .and_then(|value| value.to_str().ok()) + .unwrap_or_default(); + assert!(methods.contains("POST"), "preflight must advertise the mutating verb"); + + let denied = preflight(&router, "https://evil.example").await; + assert_eq!(denied.status(), StatusCode::OK); + assert!(denied.headers().get(header::ACCESS_CONTROL_ALLOW_ORIGIN).is_none()); +} + +async fn preflight(router: &Router, origin: &str) -> axum::response::Response { + let request = Request::builder() + .method(Method::OPTIONS) + .uri("/api/v1/blacklist") + .header(header::ORIGIN, origin) + .header(header::ACCESS_CONTROL_REQUEST_METHOD, "POST") + .extension(ConnectInfo(peer())) + .body(Body::empty()) + .expect("preflight request must build"); + router.clone().oneshot(request).await.expect("router must answer") +} + +#[test] +fn list_query_is_capped_regardless_of_the_request() { + assert_eq!( + ListQuery { + limit: None, + offset: None + } + .bounds(), + (0, DEFAULT_PAGE_LIMIT) + ); + assert_eq!( + ListQuery { + limit: Some(5000), + offset: Some(50) + } + .bounds(), + (50, MAX_PAGE_LIMIT) + ); + assert_eq!( + ListQuery { + limit: Some(10), + offset: Some(u64::MAX) + } + .bounds(), + (MAX_PAGE_OFFSET, 10) + ); + assert_eq!( + ListQuery { + limit: Some(0), + offset: Some(0) + } + .bounds(), + (0, 0) + ); +} diff --git a/tests/manager_security.rs b/tests/manager_security.rs index 2d9d3e6..5ba7e20 100644 --- a/tests/manager_security.rs +++ b/tests/manager_security.rs @@ -3,10 +3,14 @@ //! Regression tests for the authentication bypass where an empty //! `API_PASSWORD` matched an empty login (`verify_password("", "")`). +use axum::http::HeaderValue; use dashmap::DashMap; -use rampart::manager::api::auth::allow_login_attempt; -use rampart::manager::security::{CorsPolicy, validate_api_password, validate_jwt_secret, verify_password}; +use rampart::manager::api::auth::{allow_login_attempt, reset_login_attempts}; +use rampart::manager::api::guard::limit::{LOGIN_MAX_ATTEMPTS, check_attempt, evict_idle}; +use rampart::manager::api::guard::proxy::TrustedProxies; +use rampart::manager::security::{CorsPolicy, IpNet, validate_api_password, validate_jwt_secret, verify_password}; use std::net::IpAddr; +use std::time::Duration; const STRONG_PASSWORD: &str = "correct-horse-battery-staple"; const STRONG_SECRET: &str = "0123456789abcdef0123456789abcdef"; @@ -122,3 +126,124 @@ fn login_limiter_blocks_after_five_attempts() { } assert!(!allow_login_attempt(&limiter, ip)); } + +#[test] +fn successful_login_resets_the_counter() { + let limiter = DashMap::new(); + let ip = IpAddr::from([127, 0, 0, 1]); + for _ in 0..LOGIN_MAX_ATTEMPTS { + assert!(allow_login_attempt(&limiter, ip)); + } + assert!(!allow_login_attempt(&limiter, ip)); + + reset_login_attempts(&limiter, ip); + for _ in 0..LOGIN_MAX_ATTEMPTS { + assert!( + allow_login_attempt(&limiter, ip), + "a successful login must give a fresh budget" + ); + } +} + +#[test] +fn idle_limiter_entries_are_evicted() { + let limiter = DashMap::new(); + let first = IpAddr::from([127, 0, 0, 1]); + let second = IpAddr::from([127, 0, 0, 2]); + assert!(check_attempt(&limiter, first, Duration::from_secs(60), 5)); + assert!(check_attempt(&limiter, second, Duration::from_secs(60), 5)); + + evict_idle(&limiter, Duration::from_secs(600)); + assert_eq!(limiter.len(), 2, "a live window must survive the sweep"); + + evict_idle(&limiter, Duration::ZERO); + assert!(limiter.is_empty(), "expired counters must not accumulate forever"); +} + +#[test] +fn forwarded_for_is_ignored_from_an_untrusted_peer() { + let proxies = TrustedProxies::parse("10.0.0.0/8").expect("network must parse"); + let peer: IpAddr = "203.0.113.7".parse().expect("peer must parse"); + let forwarded = HeaderValue::from_static("198.51.100.9"); + assert_eq!(proxies.client_ip(peer, Some(&forwarded)), peer); +} + +#[test] +fn forwarded_for_is_used_from_a_trusted_peer() { + let proxies = TrustedProxies::parse("10.0.0.0/8,2001:db8::/32").expect("networks must parse"); + let peer: IpAddr = "10.1.2.3".parse().expect("peer must parse"); + let forwarded = HeaderValue::from_static("203.0.113.9"); + assert_eq!( + proxies.client_ip(peer, Some(&forwarded)), + "203.0.113.9".parse::().expect("client must parse") + ); + let v6_peer: IpAddr = "2001:db8::5".parse().expect("peer must parse"); + assert_eq!( + proxies.client_ip(v6_peer, Some(&forwarded)), + "203.0.113.9".parse::().expect("client must parse") + ); +} + +#[test] +fn forwarded_chain_is_walked_right_to_left() { + let proxies = TrustedProxies::parse("10.0.0.0/8").expect("network must parse"); + let peer: IpAddr = "10.1.2.3".parse().expect("peer must parse"); + + let chain = HeaderValue::from_static("203.0.113.9, 10.9.9.9"); + assert_eq!( + proxies.client_ip(peer, Some(&chain)), + "203.0.113.9".parse::().expect("client must parse") + ); + + // The leftmost entry is client supplied: the nearest untrusted hop wins. + let spoofed = HeaderValue::from_static("1.2.3.4, 198.51.100.7"); + assert_eq!( + proxies.client_ip(peer, Some(&spoofed)), + "198.51.100.7".parse::().expect("client must parse") + ); +} + +#[test] +fn malformed_forwarded_chain_falls_back_to_the_peer() { + let proxies = TrustedProxies::parse("10.0.0.0/8").expect("network must parse"); + let peer: IpAddr = "10.1.2.3".parse().expect("peer must parse"); + assert_eq!(proxies.client_ip(peer, None), peer); + let garbage = HeaderValue::from_static("not-an-address"); + assert_eq!(proxies.client_ip(peer, Some(&garbage)), peer); +} + +#[test] +fn trusted_proxy_list_rejects_malformed_entries() { + assert!( + !TrustedProxies::parse("") + .expect("empty is valid") + .is_trusted("10.0.0.1".parse().expect("ip")) + ); + assert!(TrustedProxies::parse("10.0.0.0/8,").is_err()); + assert!(TrustedProxies::parse("10.0.0.0/33").is_err()); + assert!(TrustedProxies::parse("not-a-network").is_err()); + assert!(TrustedProxies::parse("::/129").is_err()); +} + +#[test] +fn ip_net_matches_the_configured_prefix() { + let network = IpNet::parse("192.168.1.0/24").expect("network must parse"); + assert!(network.contains("192.168.1.200".parse().expect("ip"))); + assert!(!network.contains("192.168.2.1".parse().expect("ip"))); + assert!(!network.contains("::ffff:192.168.1.1".parse().expect("ip"))); + + let host = IpNet::parse("192.168.1.5").expect("host route must parse"); + assert!(host.contains("192.168.1.5".parse().expect("ip"))); + assert!(!host.contains("192.168.1.6".parse().expect("ip"))); + + let v6 = IpNet::parse("2001:db8::/32").expect("network must parse"); + assert!(v6.contains("2001:db8::1".parse().expect("ip"))); + assert!(!v6.contains("2001:db9::1".parse().expect("ip"))); + + assert!( + IpNet::parse("0.0.0.0/0") + .expect("default route must parse") + .contains("203.0.113.1".parse().expect("ip")) + ); + assert!(IpNet::parse("bad").is_err()); +}