Compare commits

...

4 commits

Author SHA1 Message Date
da87d2a11f
test: move the last inline test modules to tests/, document new signals
- All remaining #[cfg(test)] modules left src/ (manager auth/heartbeat,
  protocol registry and HTTP parser, traffic hook/prefix/profile, TUI
  Prometheus); 41 tests moved into 10 integration suites with the same names
  and assertions, so `grep -rn '#[cfg(test)]' src/` is now empty.
- runbook.md: degradation signals (overloaded connections, ClickHouse drops,
  XDP drops, generic mode, EMFILE backoff) and how to verify XDP was detached.
- troubleshooting.md: accept backoff, orphaned XDP, password/JWT startup
  requirements, ClickHouse event loss.
- TODO: review round recorded as fixed/deferred.
2026-11-16 12:36:29 +01:00
e456cb583f
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.
2026-11-16 12:36:29 +01:00
324ef12b27
fix(edge): IPv6 bind, configurable relay idle, per-gateway budget, PROXY identity
- bind.address is parsed as IpAddr (no ":::port"), the socket domain follows
  the family, and "::" binds dual-stack. IPv6 was impossible before.
- limits.relay_idle_timeout_secs (default 300, 1..=86400) replaces the
  hardcoded relay constant; the deploy examples document it.
- The connection budget is an Arc<Semaphore> owned by Gateway instead of a
  process-wide OnceLock, so tests and multiple gateways stay independent.
- PROXY header identity is validated: unspecified, loopback, link-local,
  multicast, broadcast and addresses inside trusted_cidrs are rejected, and
  IPv4-mapped IPv6 is normalised first. An invalid header falls back to the
  transport peer. Bans targeting trusted_cidrs are suppressed, closing the
  ban-amplification path through a trusted load balancer.
- TrustedProxyCidr::contains no longer overflows its mask for IPv6 prefixes
  shorter than /96.
2026-11-16 12:36:19 +01:00
9baae25acb
feat(xdp): estimate distinct sources in prefix stats, fix the detection window
The subnet detector's spoof gate needs the number of distinct sources in a
prefix, but the XDP path reported 0, so a /24 flooded from a botnet could never
reach the Block verdict and the whole subnet detector was inert with XDP on.

- prefix_stats carries a 64-bit bitmap of hashed source addresses (interface
  ID for IPv6, address for IPv4); userspace counts the set bits.
- read_prefix_stats now resets each entry after reading: the counters are
  documented as per-window and compared against fixed thresholds, but were
  cumulative, so with enough traffic every active prefix eventually looked
  like an attack.
- The monitor no longer suppresses Block on the XDP path and no longer carries
  the now-dead "no source diversity" branch.

ABI: the prefix_stats value grows 24 -> 32 bytes; the xdp_object_maps test
pins the new size.
2026-11-16 12:36:19 +01:00
65 changed files with 2595 additions and 833 deletions

3
Cargo.lock generated
View file

@ -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",
]

View file

@ -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"] }

22
TODO.md
View file

@ -258,6 +258,9 @@ module-size, secrets, `cargo deny`, rustdoc без warning'ов, clang+verifier,
исправленный v6 SYN-ACK, `inc_drop()` на всех DROP-путях, per-CPU инкремент без atomic.
- XDP: VLAN/QinQ до L3, фрагменты проверяются по blacklist, неизвестный non-SYN поток → PASS
(«stateless-фильтр, не firewall»), `whitelist6_map`, whitelist до state machine.
- XDP spoof-gate: в `prefix_stats` добавлен 64-битный bitmap хешей source-адресов, userspace
считает popcount и сбрасывает счётчики при чтении → `Block` работает и на XDP-пути, а окно
детектора стало честным (раньше счётчики были кумулятивными и со временем «банили» всё).
- XDP: протухшие префиксные баны удаляются userspace-reaper'ом раз в 60 с (пакетный путь
больше не пытается удалить `/24` ключом `/32`).
- Загрузчик: запоминается фактический attach-флаг (native/skb) и проверяется detach;
@ -284,22 +287,27 @@ module-size, secrets, `cargo deny`, rustdoc без warning'ов, clang+verifier,
### Осталось (следующий раунд)
- [ ] API manager'а: `KEYS` → `SCAN`, batch `MGET` вместо N+1, ошибки Redis → 503 (а не
`200 []`), `DefaultBodyLimit`/`TimeoutLayer`, лимит длины `reason`, graceful shutdown,
эвикция login-лимитера, ключ по `X-Forwarded-For` за доверенным прокси.
- [x] API manager'а: `SCAN`+`MGET` вместо `KEYS`/N+1, 503 вместо `200 []`, пагинация
`limit`/`offset` (100 по умолчанию, 1000 максимум), GET без записи (бэкфилл метаданных
вынесен в стартовую задачу), `DefaultBodyLimit` 8 КиБ, `TimeoutLayer` 10 с, rate-limit
на все мутирующие ручки, graceful shutdown с SIGTERM и join heartbeat, эвикция
login-лимитера, `MANAGER_TRUSTED_PROXIES` для `X-Forwarded-For`. Тесты —
`tests/manager_api.rs` (9) и `tests/manager_security.rs` (23).
- [ ] `trusted_cidrs` + PROXY-header IP как ключ всех политик: банить/лимитировать по
transport-IP, header-IP — только после валидации (ban-amplification через LB).
- [ ] XDP spoof-gate: `unique_sources = 0` на XDP-пути делает `Block` недостижимым —
либо counting в ядре, либо явная документация (сейчас логируется).
- [ ] IPv6 bind в listener (`Domain::IPV4` + строковый парсинг адреса).
- [ ] `relay_idle_timeout_secs` в `[limits]` (сейчас константа 300 с) и семафор бюджета
полем `Gateway` вместо `OnceLock`.
- [ ] Оставшиеся инлайн-тесты (10 файлов) мигрировать в `tests/`.
- [x] Инлайн-тесты мигрированы: `grep -rn "#\[cfg(test)\]" src/` пуст, 41 тест переехал в
10 новых сюит (`manager_auth`, `manager_heartbeat`, `protocol_http_*`, `traffic_*`,
`tui_prometheus`); счётчик тестов не изменился.
## 3. Backlog
- [ ] Мигрировать существующие инлайн-тесты (`#[cfg(test)]` в src/) в `tests/` —
- [x] Мигрировать существующие инлайн-тесты (`#[cfg(test)]` в src/) в `tests/` —
правило §0.7; при миграции хелперы, нужные тестам, получают `pub` с потребителем.
Сделано 2026-11-16: в `src/` не осталось ни одного `#[cfg(test)]`.
- [ ] protocol-gRPC plugin (после http)
- [ ] BPF hook #1 реальный: HTTP поверх XDP (rate-limit до userspace)
- [ ] GeoIP/ASN reputation (enum есть, реализации нет)

View file

@ -23,6 +23,7 @@ handshake_timeout_secs = 5
max_connections_per_ip = 10
rate_limit_pps = 5.0
rate_limit_burst = 10.0
relay_idle_timeout_secs = 300
[ban]
ban_duration_secs = 3600

View file

@ -16,6 +16,7 @@ handshake_timeout_secs = 5
max_connections_per_ip = 10
rate_limit_pps = 5.0
rate_limit_burst = 10.0
relay_idle_timeout_secs = 300
[ban]
ban_duration_secs = 3600

View file

@ -26,6 +26,7 @@ handshake_timeout_secs = 5
max_connections_per_ip = 10
rate_limit_pps = 5.0
rate_limit_burst = 10.0
relay_idle_timeout_secs = 300
[ban]
ban_duration_secs = 3600

View file

@ -64,6 +64,8 @@ Authorization: Bearer <token>
### `GET /api/v1/blacklist` 🔒
Query: `limit` (по умолчанию 100, максимум 1000) и `offset` (максимум 10000).
```json
{
"items": [
@ -75,9 +77,16 @@ Authorization: Bearer <token>
```
Источник: 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 <token>
// с 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`.
---

View file

@ -31,6 +31,7 @@ handshake_timeout_secs = 5 # таймаут чтения (slowloris-защ
max_connections_per_ip = 10 # одновременные соединения с одного IP
rate_limit_pps = 5.0 # лимит коннектов/сек с одного IP
rate_limit_burst = 10.0 # burst
relay_idle_timeout_secs = 300 # простой relay до разрыва, 1..86400
[ban]
ban_duration_secs = 3600
@ -84,6 +85,15 @@ max_header_bytes = 512
Все секции опциональны — при отсутствии используются дефолты из таблицы выше.
Для ingress PROXY v2 укажи сети именно прокси в `trusted_cidrs`; включение без
доверенной сети отклоняется при чтении конфига.
`trusted_cidrs` — это точные адреса/CIDR самих прокси, а не «весь DC»: IP из
заголовка используется для per-IP лимитов, репутации и банов, поэтому любой хост
внутри `trusted_cidrs` может назвать себя кем угодно. Заголовок с адресом из
`trusted_cidrs` (прокси не может быть клиентом за самим собой) или с
unspecified/loopback/link-local/multicast/broadcast адресом отклоняется, и
клиентом считается transport peer — событие пишется в debug один раз на
соединение. Адреса из `trusted_cidrs` никогда не банятся локально, в Redis и XDP;
попытка бана подавляется с предупреждением в логе.
`send_proxy_protocol` отправляет заголовок на Paper backend; прежнее имя
`proxy_protocol` внутри `[protocol.minecraft]` остаётся допустимым alias.
@ -97,6 +107,7 @@ max_header_bytes = 512
| `JWT_EXPIRATION_SECS` | нет | `86400` | Время жизни токена |
| `API_PASSWORD` | да | — | Пароль для `/api/v1/auth/login`, минимум 16 символов; `changeme` запрещён |
| `CORS_ORIGIN` | нет | — (CORS выключен) | `*` — разрешить все источники; список через запятую; пусто/не задано — запретить cross-origin |
| `MANAGER_TRUSTED_PROXIES` | нет | — (никому не доверяем) | Сети reverse-прокси через запятую (`10.0.0.0/8,2001:db8::/32`). `X-Forwarded-For` учитывается только для запросов, пришедших с адреса из этих сетей; иначе клиентом считается TCP peer. Пусто/не задано — заголовок игнорируется полностью. Опечатка или пустая запись в списке не даёт менеджеру стартовать |
Manager всегда слушает `0.0.0.0:8080`.
@ -150,6 +161,10 @@ clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/universal_filter
`whitelist6_map`) при attach и обходит state machine, throttle и баны.
- **CIDR-баны**: XDP матчит по LPM-трие, userspace — по диапазонам адресов, поэтому бан
`/24` или `/64` покрывает всю подсеть.
- **Оценка числа источников** в префиксе: XDP ведёт 64-битный bitmap хешей source-адресов,
userspace считает popcount. Благодаря этому spoof-gate (не банить `/24`, если в нём лишь
пара адресов) работает и на XDP-пути. Счётчики префиксов сбрасываются при каждом чтении,
то есть окно = интервал опроса монитора.
Покрытие семейств адресов:

View file

@ -58,6 +58,31 @@ clickhouse-client --query "SELECT count() FROM rampart.events WHERE event_type='
> Честно: hot-reload конфига не реализован — изменения применяются рестартом.
> ASN/CIDR-баны, GeoIP-блокировки стран и выбор типов challenge через CLI не
> реализованы; blacklist принимает цели в том виде, в котором их хранит Manager.
---
## 2. Сигналы деградации — что смотреть
| Метрика / лог | Что значит | Что делать |
|---------------|-----------|------------|
| `rampart_connections_total{result="overloaded"}` | исчерпан глобальный бюджет соединений (4×workers×max_connections_per_ip) | проверить, не атака ли; при легитимной нагрузке — поднять `max_connections_per_ip`/`workers.count` |
| `rampart_xdp_dropped_total` растёт, `passed_total` — нет | XDP дропает всё | проверить `protected_port_start/end`, баны и `xdp_feature_*`; смотреть `stats_map` через `bpftool` |
| `rampart_clickhouse_dropped_total` > 0 | события не успевают уходить в ClickHouse | проверить доступность/латентность ClickHouse; события потеряны, защита работает |
| `rampart_xdp_whitelist_total` растёт | трафик от whitelist-адресов | норма, но если это неожиданно — проверить `whitelist` в конфиге |
| лог `global connection budget exhausted` | то же, что `overloaded` | см. выше |
| лог `accept error ... backing off` | кончились fd (`EMFILE`) или память под сокеты | поднять `ulimit -n`, проверить утечки соединений |
| лог `XDP filter attached ... (mode: generic (skb))` | драйвер не умеет native XDP | ожидаемо для virtio/veth; generic дороже по CPU |
| лог `XDP .rodata map expects N bytes` | рассинхрон `config.h` и `XdpGlobals` | это баг сборки: не запускать, сообщить с числами из лога |
Проверить, что XDP действительно снят после остановки демона:
```bash
bpftool net show dev eth0 # не должно быть xdp-программы
ip link show eth0 | grep xdp # пусто
```
Если программа осталась — это регрессия загрузчика, а не норма: снимать вручную
`ip link set dev eth0 xdp off` и заводить баг.
> Команды `emergency`, `drain` и `config set` пока не реализованы и завершатся
> явной ошибкой вместо изменения состояния.

View file

@ -19,6 +19,31 @@ clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/uf.o
# Не помогло — отключи XDP в config.toml ([xdp] enabled = false) и рестарт.
```
### "accept error: ... backing off" / "Too many open files"
```bash
# Кончились дескрипторы: демон сам делает backoff, но сервис уже деградирует
ulimit -n # для процесса
systemctl show rampart -p LimitNOFILE
journalctl -u rampart | grep -E "accept error|EMFILE|backing off"
ss -s | head -5
```
Поднять `LimitNOFILE` (например, 65535), перезапустить, проверить утечки
соединений (`ss -tan state established | wc -l`). Backoff в списке логов — это
симптом, а не причина.
### "XDP не снимается после остановки демона"
```bash
bpftool net show dev eth0
ip link show eth0 | grep -i xdp
```
Если программа осталась — загрузчик не снял её (регрессия), снять вручную
`ip link set dev eth0 xdp off` и завести баг с режимом attach из лога
(`native (drv)` / `generic (skb)`).
### "Rate limit блокирует реальных клиентов"
```bash
@ -31,7 +56,6 @@ curl -s http://EDGE_IP:9090/metrics | grep rate_limit
```
### "Высокое CPU на edge ноде"
```bash
top -p $(pgrep rampart)
perf top -p $(pgrep rampart)
@ -63,6 +87,16 @@ export REDIS_URL="redis://127.0.0.1:6379/0" # опционально
rampart-manager
```
### "Manager не стартует: API_PASSWORD must be ..."
`API_PASSWORD` должен быть непустым и не короче 16 символов, `JWT_SECRET` —
не короче 32 непробельных байт. Пустой пароль раньше принимался как валидный,
поэтому теперь это ошибка старта, а не тихий вход без пароля.
```bash
systemctl show rampart-manager -p Environment | tr ' ' '\n' | grep -E "API_PASSWORD|JWT_SECRET" | sed 's/=.*/=<redacted>/'
```
### "Manager отдаёт 401"
Токен истёк (`JWT_EXPIRATION_SECS`, дефолт 86400) — перелогинься:
@ -108,7 +142,15 @@ df -h /var/lib/clickhouse
```
Запись настраивается `store.clickhouse_url` в config.toml. Ошибки записи не
роняют edge — они уходят в debug-лог.
роняют edge: события складываются в bounded-буфер (10 000) и при переполнении
или таймауте учитываются в `rampart_clickhouse_dropped_total`.
```bash
curl -s http://EDGE_IP:9090/metrics | grep clickhouse_dropped
```
Растущий счётчик = ClickHouse не успевает; защита при этом работает, но
аналитика теряет события.
---

View file

@ -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::<std::net::SocketAddr>();
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<bool>) -> 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");
}

View file

@ -21,7 +21,6 @@ impl Default for BindConfig {
}
}
}
fn default_bind_address() -> String {
"0.0.0.0".to_string()
}
@ -43,7 +42,6 @@ impl Default for BackendConfig {
}
}
}
fn default_upstreams() -> Vec<String> {
vec!["127.0.0.1:25566".to_string()]
}
@ -60,7 +58,6 @@ impl Default for WorkerConfig {
Self { count: 4 }
}
}
fn default_worker_count() -> usize {
4
}
@ -76,6 +73,11 @@ pub struct LimitsConfig {
pub rate_limit_pps: f64,
#[serde(default = "default_rate_limit_burst")]
pub rate_limit_burst: f64,
#[serde(
default = "default_relay_idle_timeout",
deserialize_with = "deserialize_relay_idle_timeout"
)]
pub relay_idle_timeout_secs: u64,
}
impl Default for LimitsConfig {
@ -85,10 +87,10 @@ impl Default for LimitsConfig {
max_connections_per_ip: default_max_connections_per_ip(),
rate_limit_pps: default_rate_limit_pps(),
rate_limit_burst: default_rate_limit_burst(),
relay_idle_timeout_secs: default_relay_idle_timeout(),
}
}
}
fn default_handshake_timeout() -> u64 {
5
}
@ -101,6 +103,22 @@ fn default_rate_limit_pps() -> f64 {
fn default_rate_limit_burst() -> f64 {
10.0
}
fn default_relay_idle_timeout() -> u64 {
300
}
/// Deserializes and validates `limits.relay_idle_timeout_secs`.
/// # Errors
/// Fails outside `1..=86_400`; zero would cut every relayed session immediately.
fn deserialize_relay_idle_timeout<'de, D: Deserializer<'de>>(deserializer: D) -> Result<u64, D::Error> {
let secs = u64::deserialize(deserializer)?;
if (1..=86_400).contains(&secs) {
return Ok(secs);
}
Err(serde::de::Error::custom(
"limits.relay_idle_timeout_secs must be between 1 and 86400",
))
}
/// `[ban]` section: default ban duration.
#[derive(Debug, Clone, Deserialize)]
@ -116,7 +134,6 @@ impl Default for BanConfig {
}
}
}
fn default_ban_duration() -> u64 {
3600
}
@ -153,11 +170,11 @@ impl TrustedProxyCidr {
/// Returns whether `ip` belongs to this network.
#[must_use]
pub fn contains(&self, ip: IpAddr) -> bool {
let mask4 = mask_v4(self.prefix_len);
let mask6 = mask_v6(self.prefix_len);
// Masks are family-specific: a prefix above 32 would underflow the v4 shift.
let prefix = self.prefix_len;
match (self.network, ip) {
(IpAddr::V4(network), IpAddr::V4(ip)) => u32::from(network) & mask4 == u32::from(ip) & mask4,
(IpAddr::V6(network), IpAddr::V6(ip)) => u128::from(network) & mask6 == u128::from(ip) & mask6,
(IpAddr::V4(net), IpAddr::V4(ip)) => u32::from(net) & mask_v4(prefix) == u32::from(ip) & mask_v4(prefix),
(IpAddr::V6(net), IpAddr::V6(ip)) => u128::from(net) & mask_v6(prefix) == u128::from(ip) & mask_v6(prefix),
_ => false,
}
}
@ -167,18 +184,12 @@ impl FromStr for TrustedProxyCidr {
type Err = String;
fn from_str(value: &str) -> Result<Self, Self::Err> {
let (address, prefix) = match value.split_once('/') {
Some((address, prefix)) => (address, Some(prefix)),
None => (value, None),
};
let (address, prefix) = value.split_once('/').map_or((value, None), |(a, p)| (a, Some(p)));
let network = IpAddr::from_str(address).map_err(|_| format!("invalid trusted proxy CIDR: {value}"))?;
let max_prefix = if network.is_ipv4() { 32 } else { 128 };
let prefix_len = match prefix {
Some(prefix) => prefix
.parse::<u8>()
.map_err(|_| format!("invalid trusted proxy CIDR prefix: {value}"))?,
None => max_prefix,
};
let prefix_len = prefix
.map_or(Ok(max_prefix), |prefix| prefix.parse::<u8>())
.map_err(|_| format!("invalid trusted proxy CIDR prefix: {value}"))?;
if prefix_len > max_prefix {
return Err(format!("trusted proxy CIDR prefix is too large: {value}"));
}
@ -231,7 +242,6 @@ impl Default for ProxyProtocolConfig {
}
}
}
fn default_proxy_protocol_timeout_ms() -> u64 {
750
}

View file

@ -3,8 +3,10 @@
use crate::config::Config;
use crate::engine::tunnel::Gateway;
use crate::traffic::hook::TrafficHook;
use anyhow::Context;
use socket2::{Domain, Socket, Type};
use std::io::ErrorKind;
use std::net::{IpAddr, SocketAddr};
use std::sync::Arc;
use std::time::Duration;
use tokio::net::TcpListener;
@ -119,7 +121,7 @@ pub async fn run(
hook: Arc<TrafficHook>,
shutdown: watch::Receiver<bool>,
) -> anyhow::Result<()> {
let addr: std::net::SocketAddr = format!("{}:{}", config.bind.address, config.bind.port).parse()?;
let addr = parse_listen_addr(&config.bind.address, config.bind.port)?;
let workers = config.workers.count.max(1);
let mut handles = Vec::with_capacity(workers);
@ -139,11 +141,39 @@ pub async fn run(
Ok(())
}
fn build_listener(addr: std::net::SocketAddr) -> anyhow::Result<TcpListener> {
let socket = Socket::new(Domain::IPV4, Type::STREAM, None)?;
/// Parses the configured listen address into a socket address.
///
/// The address must be an IP literal: resolving a host name at startup would
/// make the bound family depend on resolver state, and the listener needs the
/// family up front to pick the correct socket domain.
///
/// # Errors
/// Fails when `address` is not a valid IPv4 or IPv6 literal.
pub fn parse_listen_addr(address: &str, port: u16) -> anyhow::Result<SocketAddr> {
let ip: IpAddr = address
.parse()
.with_context(|| format!("bind.address must be an IP address, got {address:?}"))?;
Ok(SocketAddr::new(ip, port))
}
/// Binds a TCP listener on `addr` with `SO_REUSEPORT` and `SO_REUSEADDR`.
///
/// The socket domain follows the address family, so IPv6 listen addresses work
/// as well as IPv4 ones. An IPv6 wildcard socket is switched to dual-stack mode
/// (`IPV6_V6ONLY=0`), which keeps `bind.address = "::"` accepting IPv4 clients
/// through IPv4-mapped addresses.
///
/// # Errors
/// Fails when the socket cannot be created, configured or bound.
pub fn build_listener(addr: SocketAddr) -> anyhow::Result<TcpListener> {
let domain = if addr.is_ipv4() { Domain::IPV4 } else { Domain::IPV6 };
let socket = Socket::new(domain, Type::STREAM, None)?;
socket.set_reuse_port(true)?;
socket.set_reuse_address(true)?;
socket.set_nonblocking(true)?;
if addr.is_ipv6() && addr.ip().is_unspecified() {
socket.set_only_v6(false)?;
}
socket.bind(&addr.into())?;
socket.listen(65535)?;
Ok(TcpListener::from_std(socket.into())?)

View file

@ -31,15 +31,6 @@ impl Source {
Source::Tracker(tracker) => tracker.snapshot().await,
}
}
/// Whether the source reports distinct source addresses per prefix.
fn counts_unique_sources(&self) -> bool {
match self {
#[cfg(feature = "xdp")]
Source::Xdp(_) => false,
Source::Tracker(_) => true,
}
}
}
/// Verdict enforcement settings shared by every snapshot tick.
@ -82,7 +73,6 @@ pub fn spawn(
ttl: ban_ttl,
trusted: trusted_peer,
};
let extreme_threshold = detect.syn_threshold.saturating_mul(4);
tokio::spawn(async move {
let mut tick = tokio::time::interval(window);
@ -99,7 +89,7 @@ pub fn spawn(
match source.snapshot().await {
Ok(snaps) => {
let verdicts = detector.evaluate(&snaps);
apply_verdicts(&verdicts, &source, &policy, extreme_threshold);
apply_verdicts(&verdicts, &source, &policy);
},
Err(e) => tracing::debug!("prefix stats unavailable: {e}"),
}
@ -119,7 +109,7 @@ fn build_source(tracker: Option<Arc<SubnetTracker>>, xdp: Option<Arc<Mutex<XdpFi
tracker.map(|t| Source::Tracker(TrackerSource { tracker: t }))
}
fn apply_verdicts(verdicts: &[PrefixVerdict], source: &Source, policy: &BanPolicy, extreme_threshold: u64) {
fn apply_verdicts(verdicts: &[PrefixVerdict], source: &Source, policy: &BanPolicy) {
for pv in verdicts {
metrics::SUBNET_VERDICTS
.with_label_values(&[verdict_name(pv.verdict)])
@ -131,18 +121,6 @@ fn apply_verdicts(verdicts: &[PrefixVerdict], source: &Source, policy: &BanPolic
verdict = verdict_name(pv.verdict),
"subnet verdict"
);
if pv.verdict == SubnetVerdict::Challenge
&& !source.counts_unique_sources()
&& pv.snapshot.syn_count >= extreme_threshold
{
// XDP does not count distinct sources, so the spoof gate can never
// confirm `Block` on that path; make the cap visible instead of silent.
tracing::info!(
prefix = %pv.prefix,
syn = pv.snapshot.syn_count,
"spoof gate suppressed block: XDP has no source diversity data; escalating at L7 only"
);
}
}
match source {
#[cfg(feature = "xdp")]

View file

@ -17,9 +17,33 @@ use std::sync::Arc;
use std::sync::Mutex;
use std::sync::atomic::{AtomicU64, AtomicUsize};
use tokio::sync::Mutex as TokioMutex;
use tokio::sync::Semaphore;
mod gateway;
#[cfg(feature = "protocol-minecraft")]
mod proxy;
#[cfg(feature = "protocol-minecraft")]
pub use proxy::{ClientIpRejection, validate_client_ip};
/// Multiplier applied to the per-IP limit when sizing the global connection
/// budget: `4 x workers x max_connections_per_ip` in-flight connections.
const CONNECTION_BUDGET_FACTOR: usize = 4;
/// Ceiling of the global budget, so a large worker count cannot exhaust the
/// file-descriptor table of the host.
const CONNECTION_BUDGET_MAX: usize = 100_000;
/// Returns the in-flight connection budget of one gateway instance.
///
/// The budget lives on the gateway instead of in a process-wide static so an
/// embedded or test gateway gets its own limiter and configuration changes are
/// visible without restarting the process.
fn connection_budget_capacity(config: &Config) -> usize {
let workers = config.workers.count.max(1);
let per_ip = config.limits.max_connections_per_ip.max(1) as usize;
workers
.saturating_mul(per_ip)
.saturating_mul(CONNECTION_BUDGET_FACTOR)
.clamp(1, CONNECTION_BUDGET_MAX)
}
/// Shared edge engine state handed to every accept loop by [`Arc`].
pub struct Gateway {
@ -35,6 +59,8 @@ pub struct Gateway {
pub allowed_1s: Arc<AtomicU64>,
pub registry: Arc<ProtocolRegistry>,
pub subnet_tracker: Option<Arc<SubnetTracker>>,
budget: Arc<Semaphore>,
budget_rejections: AtomicU64,
upstream_cursor: AtomicUsize,
}

View file

@ -10,8 +10,6 @@ mod challenge;
mod pipeline;
mod relay;
pub use relay::RELAY_IDLE_TIMEOUT;
#[cfg(feature = "protocol-minecraft")]
use super::proxy;
use super::{Gateway, GatewayOutcome};
@ -31,6 +29,7 @@ use std::sync::atomic::AtomicU64;
use std::sync::{Arc, Mutex};
use tokio::net::TcpStream;
use tokio::sync::Mutex as TokioMutex;
use tokio::sync::Semaphore;
impl Gateway {
#[allow(clippy::too_many_arguments)]
@ -48,6 +47,7 @@ impl Gateway {
subnet_tracker: Option<Arc<SubnetTracker>>,
) -> Self {
let max_connections = config.limits.max_connections_per_ip as usize;
let budget = Arc::new(Semaphore::new(super::connection_budget_capacity(&config)));
Self {
config,
rate_limiter,
@ -61,6 +61,8 @@ impl Gateway {
allowed_1s,
registry,
subnet_tracker,
budget,
budget_rejections: AtomicU64::new(0),
upstream_cursor: std::sync::atomic::AtomicUsize::new(0),
}
}

View file

@ -21,6 +21,17 @@ impl Gateway {
metrics::CONNECTIONS_TOTAL.with_label_values(&["blocked"]).inc();
self.reputation.record_bad(ip);
if self.reputation.score(ip) < -40 {
// Defence in depth: a trusted proxy address must never enter the ban
// path, even when reputation escalation is reached. Bans are
// replicated to Redis and XDP on every node, so one wrong identity
// here could take the ingress proxy out of the whole cluster.
if self.is_trusted_proxy(ip) {
tracing::warn!(
%ip,
"suppressed ban for an address inside proxy_protocol.trusted_cidrs"
);
return;
}
let duration_secs = Duration::from_secs(self.config.ban.ban_duration_secs);
self.blacklist.add(ip, duration_secs, "low_reputation");
if !self.config.proxy_protocol.ingress_enabled {
@ -31,6 +42,15 @@ impl Gateway {
}
}
/// Returns whether `ip` belongs to a configured trusted proxy network.
fn is_trusted_proxy(&self, ip: IpAddr) -> bool {
self.config
.proxy_protocol
.trusted_cidrs
.iter()
.any(|cidr| cidr.contains(ip))
}
/// Mirrors a ban into the XDP map, if the kernel filter is attached.
fn xdp_ban(&self, ip: IpAddr, duration_secs: u64) {
let Some(xdp) = &self.xdp else {

View file

@ -1,48 +1,16 @@
//! Filter order and upstream establishment for one accepted connection.
use super::Gateway;
use super::RELAY_IDLE_TIMEOUT;
use crate::metrics;
use std::sync::OnceLock;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::atomic::Ordering;
use std::time::Duration;
use tokio::io::AsyncWriteExt;
use tokio::net::TcpStream;
use tokio::sync::Semaphore;
/// Multiplier applied to the per-IP limit when sizing the global connection
/// budget: `4 x workers x max_connections_per_ip` in-flight connections.
const GLOBAL_BUDGET_FACTOR: usize = 4;
/// Ceiling of the global budget, so a large worker count cannot exhaust the
/// file-descriptor table of the host.
const GLOBAL_BUDGET_MAX: usize = 100_000;
/// One in every `BUDGET_LOG_EVERY` budget rejections is logged.
const BUDGET_LOG_EVERY: u64 = 128;
/// Process-wide in-flight connection budget.
///
/// Initialised on first use from the worker count and the per-IP limit of the
/// gateway configuration. A process-wide value is intentional: the budget caps
/// descriptors and tasks for the whole edge node, and there is exactly one
/// gateway per process in production.
static GLOBAL_BUDGET: OnceLock<Semaphore> = OnceLock::new();
/// Total connections rejected by the global budget, used for log rate limiting.
static BUDGET_REJECTIONS: AtomicU64 = AtomicU64::new(0);
impl Gateway {
/// Returns the process-wide in-flight connection budget.
fn global_budget(&self) -> &'static Semaphore {
GLOBAL_BUDGET.get_or_init(|| {
let workers = self.config.workers.count.max(1);
let per_ip = self.config.limits.max_connections_per_ip.max(1) as usize;
let capacity = workers
.saturating_mul(per_ip)
.saturating_mul(GLOBAL_BUDGET_FACTOR)
.clamp(1, GLOBAL_BUDGET_MAX);
Semaphore::new(capacity)
})
}
/// Runs the filter stages, PoW gate, protocol handshake and relay.
///
/// # Errors
@ -86,11 +54,11 @@ impl Gateway {
let _global_permit = if trusted {
None
} else {
match self.global_budget().try_acquire() {
match self.budget.try_acquire() {
Ok(permit) => Some(permit),
Err(_) => {
metrics::CONNECTIONS_TOTAL.with_label_values(&["overloaded"]).inc();
let seen = BUDGET_REJECTIONS.fetch_add(1, Ordering::Relaxed);
let seen = self.budget_rejections.fetch_add(1, Ordering::Relaxed);
if seen % BUDGET_LOG_EVERY == 0 {
tracing::warn!(
"global connection budget exhausted after {seen} rejections, dropping {peer_ip}"
@ -145,7 +113,7 @@ impl Gateway {
handshake_budget,
)
.await?;
self.relay_with_idle(client, backend, RELAY_IDLE_TIMEOUT).await
self.relay_with_idle(client, backend, self.relay_idle_timeout()).await
}
/// Opens the upstream connection under the handshake timeout.

View file

@ -8,17 +8,17 @@ use tokio::net::TcpStream;
const RELAY_BUFFER_BYTES: usize = 16 * 1024;
/// Idle budget of the client/backend relay.
///
/// Minecraft keeps one connection alive for a whole session and a legitimately
/// silent gap (menus, chunk loading, AFK timeouts) can last minutes, so 300s is
/// the safe default: it never cuts a real session and still reaps dead peers.
/// The value is a constant because `[limits]` is owned by a parallel change; it
/// is plumbed as a parameter through [`Gateway::relay_with_idle`] so a config
/// field can be wired in without touching the relay itself.
pub const RELAY_IDLE_TIMEOUT: Duration = Duration::from_secs(300);
impl Gateway {
/// Returns the configured idle budget of the client/backend relay.
///
/// `limits.relay_idle_timeout_secs` defaults to 300s: Minecraft keeps one
/// connection alive for a whole session and a legitimately silent gap
/// (menus, chunk loading, AFK timeouts) can last minutes, so a short budget
/// would cut real sessions while a missing one would pin descriptors.
pub fn relay_idle_timeout(&self) -> Duration {
Duration::from_secs(self.config.limits.relay_idle_timeout_secs)
}
/// Relays bytes in both directions until either side closes, an I/O error
/// occurs or a direction stays silent for `idle`.
///

View file

@ -2,19 +2,85 @@
//! parsing of headers injected by trusted ingress peers.
use crate::config::ProxyProtocolConfig;
use std::net::SocketAddr;
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use std::time::Duration;
use tokio::net::TcpStream;
mod inbound;
pub(super) use inbound::read_v2_header;
/// Reason a PROXY header client address is rejected as an identity.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ClientIpRejection {
/// `0.0.0.0` or `::`: no host behind the header.
Unspecified,
/// The header claims a loopback address, which is never a real client.
Loopback,
/// The header claims a link-local address (`169.254.0.0/16`, `fe80::/10`).
LinkLocal,
/// The header claims a multicast address.
Multicast,
/// The header claims the limited IPv4 broadcast address.
Broadcast,
/// The header claims an address of the proxy network itself.
TrustedProxy,
}
/// Validates the client IP claimed in an inbound PROXY v2 header.
///
/// A trusted proxy is allowed to state who the client is, but it must not be
/// able to name an address that can never be a real remote client (host-local,
/// link-local, multicast, broadcast) or another trusted proxy. Without this
/// check a single compromised or misconfigured proxy could ban arbitrary
/// addresses cluster-wide or poison their reputation.
///
/// # Errors
/// Returns the reason `ip` is not usable as a client identity.
pub fn validate_client_ip(config: &ProxyProtocolConfig, ip: IpAddr) -> Result<(), ClientIpRejection> {
// Collapse IPv4-mapped IPv6 first: the ban tables do the same, so leaving
// `::ffff:127.0.0.1` as v6 would bypass the loopback and trusted-network
// checks and then be normalized into a ban for `127.0.0.1`.
let ip = match ip {
IpAddr::V6(v6) => v6.to_ipv4_mapped().map_or(ip, IpAddr::V4),
IpAddr::V4(_) => ip,
};
if ip.is_unspecified() {
return Err(ClientIpRejection::Unspecified);
}
if ip.is_loopback() {
return Err(ClientIpRejection::Loopback);
}
let link_local = match ip {
IpAddr::V4(v4) => v4.is_link_local(),
IpAddr::V6(v6) => v6.is_unicast_link_local(),
};
if link_local {
return Err(ClientIpRejection::LinkLocal);
}
if ip.is_multicast() {
return Err(ClientIpRejection::Multicast);
}
if ip == IpAddr::V4(Ipv4Addr::BROADCAST) {
return Err(ClientIpRejection::Broadcast);
}
if config.trusted_cidrs.iter().any(|cidr| cidr.contains(ip)) {
return Err(ClientIpRejection::TrustedProxy);
}
Ok(())
}
/// Resolves the effective client address from an inbound PROXY v2 header.
///
/// Only peers inside `config.trusted_cidrs` may inject a header; anyone else
/// is rejected instead of being believed. The whole header must arrive within
/// `config.ingress_timeout_ms` and fit in `config.max_header_bytes`.
///
/// A header whose client address fails [`validate_client_ip`] is not fatal:
/// the transport peer becomes the client identity and the reason is logged once
/// per connection at debug level. Failing closed would drop every connection
/// behind a misbehaving proxy, while trusting the claimed address would hand
/// the ban path to the proxy.
///
/// # Errors
/// Fails when the peer is not trusted, on timeout and on any header parse error.
pub(super) async fn resolve_client_addr(
@ -25,12 +91,24 @@ pub(super) async fn resolve_client_addr(
if !config.trusted_cidrs.iter().any(|cidr| cidr.contains(peer_addr.ip())) {
anyhow::bail!("untrusted peer attempted inbound PROXY protocol");
}
read_v2_header(
let claimed = read_v2_header(
client,
Duration::from_millis(config.ingress_timeout_ms),
config.max_header_bytes,
)
.await
.await?;
match validate_client_ip(config, claimed.ip()) {
Ok(()) => Ok(claimed),
Err(reason) => {
tracing::debug!(
peer = %peer_addr,
claimed = %claimed,
reason = ?reason,
"ignoring PROXY header client address, using the transport peer"
);
Ok(peer_addr)
},
}
}
/// Encodes a PROXY protocol v2 TCP header for the backend.

View file

@ -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<Arc<AppState>>,
ConnectInfo(addr): ConnectInfo<SocketAddr>,
Extension(guard): Extension<Arc<RequestGuard>>,
headers: HeaderMap,
Json(req): Json<LoginRequest>,
) -> Result<Json<serde_json::Value>, (StatusCode, Json<serde_json::Value>)> {
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<IpAddr, (Instant, u32)>, 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<IpAddr, (Instant, u32)>, ip: IpAddr) {
limit::reset_attempts(limiter, ip);
}

View file

@ -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<BlacklistEntry>,
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<u64>,
pub offset: Option<u64>,
}
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")]

View file

@ -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<T> = Result<T, (StatusCode, Json<serde_json::Value>)>;
/// 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<usize> {
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<String>) = 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<String> = members
.into_iter()
.filter(|target| target.parse::<IpAddr>().is_ok())
.collect();
if !targets.is_empty() {
let existing: Vec<Option<String>> = 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);
}
}
}

View file

@ -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<std::net::IpAddr, (StatusCode, Json<serde_json::Value>)> {
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<IpAddr, (StatusCode, Json<serde_json::Value>)> {
let target = target.trim();
if let Ok(ip) = target.parse::<IpAddr>() {
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<serde_json::Value>)> {
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<serde_json::Value>) {

View file

@ -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<T> = Result<T, (StatusCode, Json<serde_json::Value>)>;
pub async fn list_blacklist(
State(state): State<Arc<AppState>>,
) -> Result<Json<BlacklistResponse>, (StatusCode, Json<serde_json::Value>)> {
Query(query): Query<ListQuery>,
) -> ApiResult<Json<BlacklistResponse>> {
let (offset, limit) = query.bounds();
let mut conn = state
.redis_client
.get_multiplexed_async_connection()
.await
.map_err(redis_unavailable)?;
let members: Vec<String> = redis::cmd("SMEMBERS")
let total: u64 = redis::cmd("SCARD")
.arg(BLACKLIST_KEY)
.query_async(&mut conn)
.await
.map_err(redis_error)?;
let metadata: HashMap<String, String> = 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::<std::net::IpAddr>() else {
continue;
};
let record = match metadata.get(&target) {
Some(encoded) => match serde_json::from_str::<BlacklistMetadata>(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<String> =
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<String> = 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<Vec<String>> {
let mut targets = Vec::new();
let mut cursor = 0_u64;
loop {
let (next, batch): (u64, Vec<String>) = 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<HashMap<String, Option<BlacklistMetadata>>> {
let mut metadata = HashMap::with_capacity(targets.len());
for chunk in targets.chunks(PAGE_SCAN_BATCH) {
let values: Vec<Option<String>> = 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<BlacklistMetadata>>, now: i64) -> Option<BlacklistEntry> {
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)),
})
}

View file

@ -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<Arc<AppState>>,
Json(req): Json<AddBlacklistRequest>,
) -> Result<Json<serde_json::Value>, (StatusCode, Json<serde_json::Value>)> {
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<Arc<AppState>>,
Json(req): Json<RemoveBlacklistRequest>,
) -> Result<Json<serde_json::Value>, (StatusCode, Json<serde_json::Value>)> {
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

View file

@ -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<IpAddr, (Instant, u32)>, 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<IpAddr, (Instant, u32)>, ip: IpAddr) {
limiter.remove(&ip);
}
/// Removes every counter whose window already elapsed.
pub fn evict_idle(limiter: &DashMap<IpAddr, (Instant, u32)>, 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<Arc<RequestGuard>>,
request: Request,
next: Next,
) -> Result<Response, (StatusCode, Json<serde_json::Value>)> {
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)
}

View file

@ -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<IpAddr, (Instant, u32)>,
}
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<Self> {
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::<ConnectInfo<SocketAddr>>()
.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<RequestGuard>, mut shutdown: watch::Receiver<bool>) {
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<RequestGuard>, shutdown: watch::Receiver<bool>) -> JoinHandle<()> {
tokio::spawn(run_eviction(state, guard, shutdown))
}

View file

@ -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<IpNet>,
}
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<Self> {
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> {
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::<IpAddr>() {
Ok(ip) if !self.is_trusted(ip) => return ip,
Ok(ip) => resolved = ip,
Err(_) => break,
}
}
resolved
}
}

View file

@ -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<RequestGuard>, cors: Option<CorsLayer>) -> 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
}

View file

@ -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<Vec<String>> {
use futures::StreamExt;
use redis::AsyncCommands;
let opts = redis::ScanOptions::default()
.with_pattern(pattern)
.with_count(READ_BATCH);
let mut iter = conn.scan_options::<String>(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<Option<String>> = 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<T: serde::de::DeserializeOwned>(values: &[String]) -> Vec<T> {
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<serde_json::Value>) {
tracing::error!("inventory Redis read failed: {error}");
(
axum::http::StatusCode::SERVICE_UNAVAILABLE,
axum::Json(serde_json::json!({"error": "redis unavailable"})),
)
}

View file

@ -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<NodeInfo>,
}
/// 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<Arc<AppState>>) -> Json<NodesResponse> {
let mut conn = match state.redis_client.get_multiplexed_async_connection().await {
Ok(c) => c,
Err(_) => return Json(NodesResponse { nodes: vec![] }),
};
let keys: Vec<String> = 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<String> = conn.get(key).await.unwrap_or(None);
if let Some(json) = raw
&& let Ok(node) = serde_json::from_str::<NodeInfo>(&json)
{
nodes.push(node);
}
}
Json(NodesResponse { nodes })
pub async fn list_nodes(
State(state): State<Arc<AppState>>,
) -> Result<Json<NodesResponse>, (StatusCode, Json<serde_json::Value>)> {
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),
}))
}

View file

@ -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<ServerEntry>,
}
/// 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<Arc<AppState>>) -> Json<ServersResponse> {
let mut conn = match state.redis_client.get_multiplexed_async_connection().await {
Ok(c) => c,
Err(_) => return Json(ServersResponse { servers: vec![] }),
};
let keys: Vec<String> = 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<String> = conn.get(key).await.unwrap_or(None);
if let Some(json) = raw
&& let Ok(server) = serde_json::from_str::<ServerEntry>(&json)
{
servers.push(server);
}
}
Json(ServersResponse { servers })
pub async fn list_servers(
State(state): State<Arc<AppState>>,
) -> Result<Json<ServersResponse>, (StatusCode, Json<serde_json::Value>)> {
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),
}))
}

View file

@ -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;

View file

@ -66,38 +66,3 @@ pub async fn auth_middleware(
Ok(next.run(request).await)
}
#[cfg(test)]
mod tests {
use super::*;
fn valid_secret() -> String {
"this-is-a-test-secret-32-bytes-long!".to_string()
}
#[test]
fn create_verify_roundtrip_passes() {
let secret = valid_secret();
let token = create_token(&secret, 3600, "rampart").expect("token creation should succeed");
let claims = verify_token(&token, &secret, "rampart").expect("verification should succeed");
assert_eq!(claims.sub, "rampart-admin");
assert_eq!(claims.aud, "rampart");
assert_eq!(claims.role, "admin");
assert!(claims.exp > claims.iat);
}
#[test]
fn verify_rejects_wrong_audience() {
let secret = valid_secret();
let token = create_token(&secret, 3600, "rampart").expect("token creation should succeed");
assert!(verify_token(&token, &secret, "other").is_err());
}
#[test]
fn verify_rejects_wrong_secret() {
let secret = valid_secret();
let other_secret = "another-test-secret-also-32-bytes-long!".to_string();
let token = create_token(&secret, 3600, "rampart").expect("token creation should succeed");
assert!(verify_token(&token, &other_secret, "rampart").is_err());
}
}

View file

@ -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<CorsLayer> {
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<Self> {
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::<u8>()
.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)
}

View file

@ -13,12 +13,12 @@ use tokio::time::{Duration, interval};
/// SCAN pattern for node records (blocking KEYS is forbidden under load).
#[cfg(feature = "store-redis")]
const NODES_KEY_PATTERN: &str = "rampart:nodes:*";
pub const NODES_KEY_PATTERN: &str = "rampart:nodes:*";
/// SCAN COUNT hint per round.
#[cfg(feature = "store-redis")]
const SCAN_BATCH: usize = 100;
/// Node is offline when the last heartbeat is older than this.
#[cfg(any(feature = "store-redis", test))]
#[cfg(feature = "store-redis")]
const NODE_TTL_SECS: i64 = 60;
#[cfg(feature = "store-redis")]
@ -68,8 +68,8 @@ async fn collect_node_keys(conn: &mut redis::aio::MultiplexedConnection) -> anyh
/// the RFC3339 `last_heartbeat` is older than `NODE_TTL_SECS` (a missing or
/// unparseable timestamp counts as expired, matching the previous behavior);
/// `None` when the node is fresh, unparsable, or not a JSON object.
#[cfg(any(feature = "store-redis", test))]
fn offline_update(raw: &str, now: i64) -> Option<String> {
#[cfg(feature = "store-redis")]
pub fn offline_update(raw: &str, now: i64) -> Option<String> {
let mut node = serde_json::from_str::<serde_json::Value>(raw).ok()?;
let hb = node["last_heartbeat"]
.as_str()
@ -83,54 +83,3 @@ fn offline_update(raw: &str, now: i64) -> Option<String> {
.insert("status".to_string(), serde_json::Value::String("offline".to_string()));
serde_json::to_string(&node).ok()
}
#[cfg(test)]
mod tests {
use super::*;
fn rfc3339(ts: i64) -> String {
chrono::DateTime::from_timestamp(ts, 0)
.expect("in-range timestamp")
.to_rfc3339()
}
#[test]
fn expired_heartbeat_is_marked_offline() {
let now = 2_000_000_i64;
let raw = format!(
r#"{{"name":"edge1","last_heartbeat":"{}","status":"online"}}"#,
rfc3339(now - 120)
);
let updated = offline_update(&raw, now).expect("expired node should be marked offline");
assert!(updated.contains("offline"));
assert!(updated.contains("edge1"));
}
#[test]
fn fresh_heartbeat_is_left_untouched() {
let now = 2_000_000_i64;
let raw = format!(r#"{{"last_heartbeat":"{}","status":"online"}}"#, rfc3339(now - 5));
assert!(offline_update(&raw, now).is_none());
}
#[test]
fn missing_or_broken_timestamp_counts_as_expired() {
let now = 2_000_000_i64;
let updated = offline_update(r#"{"status":"online"}"#, now).expect("missing heartbeat counts as expired");
assert!(updated.contains("offline"));
let updated = offline_update(r#"{"last_heartbeat":"garbage","status":"online"}"#, now)
.expect("unparseable heartbeat counts as expired");
assert!(updated.contains("offline"));
}
#[test]
fn invalid_json_is_ignored() {
assert!(offline_update("not json", 2_000_000).is_none());
}
#[cfg(feature = "store-redis")]
#[test]
fn node_key_pattern_targets_rampart_nodes() {
assert_eq!(NODES_KEY_PATTERN, "rampart:nodes:*");
}
}

View file

@ -8,7 +8,7 @@
//! The bytes already consumed for the head are forwarded to the upstream as the
//! initial tunnel payload, so the request is not lost.
mod parser;
pub mod parser;
use crate::config::HttpProtocolConfig;
use crate::protocol::{HandshakeResult, ProtocolHandler, Upstream};
@ -95,24 +95,3 @@ impl ProtocolHandler for HttpProtocolHandler {
})
}
}
#[cfg(test)]
mod tests {
use super::*;
#[tokio::test]
async fn zero_limit_fails_fast_without_io() {
let config = HttpProtocolConfig::default();
let mut broken = config.clone();
broken.max_header_bytes = 0;
let handler = HttpProtocolHandler::new(&broken, &[]);
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.expect("bind");
let client = tokio::net::TcpStream::connect(listener.local_addr().expect("addr"))
.await
.expect("connect");
let (mut server, _) = listener.accept().await.expect("accept");
drop(listener);
assert!(handler.read_head(&mut server).await.is_err());
drop(client);
}
}

View file

@ -103,95 +103,3 @@ fn reject(reason: &str) -> Verdict {
reason: reason.to_string(),
}
}
#[cfg(test)]
mod tests {
use super::*;
fn policy() -> Policy {
Policy {
max_header_bytes: 8192,
blocked_paths: Vec::new(),
require_user_agent: false,
}
}
#[test]
fn scan_finds_full_head_length() {
assert_eq!(scan_head(b"GET / HTTP/1.1\r\n\r\n"), Some(18));
assert_eq!(scan_head(b"GET / HTTP/1.1\r\n"), None);
}
#[test]
fn valid_request_is_allowed() {
let head = b"POST /api/items?limit=5 HTTP/1.1\r\nHost: example.com\r\n\r\n";
let verdict = evaluate(head, &policy());
assert_eq!(
verdict,
Verdict::Allow {
method: "POST".to_string(),
path: "/api/items".to_string(),
host: "example.com".to_string()
}
);
}
#[test]
fn unknown_method_is_rejected() {
let head = b"TRACE / HTTP/1.1\r\nHost: h\r\n\r\n";
assert!(matches!(evaluate(head, &policy()), Verdict::Reject { .. }));
}
#[test]
fn missing_host_is_rejected() {
let head = b"GET / HTTP/1.1\r\nUser-Agent: t\r\n\r\n";
assert!(matches!(evaluate(head, &policy()), Verdict::Reject { .. }));
}
#[test]
fn http2_version_is_rejected() {
let head = b"GET / HTTP/2.0\r\nHost: h\r\n\r\n";
assert!(matches!(evaluate(head, &policy()), Verdict::Reject { .. }));
}
#[test]
fn malformed_line_is_rejected() {
assert!(matches!(
evaluate(b"nonsense\r\n\r\n", &policy()),
Verdict::Reject { .. }
));
assert!(matches!(
evaluate(b"GET / HTTP/1.1\r\nbroken\r\n\r\n", &policy()),
Verdict::Reject { .. }
));
}
#[test]
fn non_utf8_head_is_rejected() {
assert!(matches!(evaluate(&[0xff, 0xfe], &policy()), Verdict::Reject { .. }));
}
#[test]
fn blocked_path_prefix_is_rejected() {
let mut custom = policy();
custom.blocked_paths = vec!["/admin".to_string()];
assert!(matches!(
evaluate(b"GET /admin/panel HTTP/1.1\r\nHost: h\r\n\r\n", &custom),
Verdict::Reject { .. }
));
assert!(matches!(
evaluate(b"GET /public HTTP/1.1\r\nHost: h\r\n\r\n", &custom),
Verdict::Allow { .. }
));
}
#[test]
fn required_user_agent_enforced() {
let mut custom = policy();
custom.require_user_agent = true;
let head = b"GET / HTTP/1.1\r\nHost: h\r\n\r\n";
assert!(matches!(evaluate(head, &custom), Verdict::Reject { .. }));
let head_with_ua = b"GET / HTTP/1.1\r\nHost: h\r\nUser-Agent: curl/8\r\n\r\n";
assert!(matches!(evaluate(head_with_ua, &custom), Verdict::Allow { .. }));
}
}

View file

@ -126,41 +126,3 @@ impl ProtocolRegistry {
Ok(handler.as_ref())
}
}
#[cfg(test)]
mod tests {
use super::*;
struct DummyHandler;
impl ProtocolHandler for DummyHandler {
fn name(&self) -> &'static str {
"dummy"
}
fn handshake<'a>(
&'a self,
_stream: &'a mut TcpStream,
) -> Pin<Box<dyn Future<Output = anyhow::Result<HandshakeResult>> + Send + 'a>> {
Box::pin(async { Ok(HandshakeResult::new(Upstream::new("127.0.0.1:9000"))) })
}
}
#[test]
fn empty_registry_fails_fast() {
let registry = ProtocolRegistry::new();
assert!(registry.is_empty());
assert!(registry.primary().is_err());
}
#[test]
fn registered_handler_is_resolvable() {
let mut registry = ProtocolRegistry::new();
registry.register(Box::new(DummyHandler));
assert_eq!(registry.len(), 1);
assert_eq!(registry.names(), vec!["dummy"]);
assert!(registry.primary().is_ok());
assert!(registry.get("dummy").is_some());
assert!(registry.get("missing").is_none());
}
}

View file

@ -100,127 +100,3 @@ impl TrafficHook {
tracing::warn!(%ip, reason, ttl_secs = self.ban_ttl_secs, "auto-ban issued by traffic intelligence");
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::net::{IpAddr, Ipv4Addr};
fn ip(octets: [u8; 4]) -> IpAddr {
IpAddr::V4(Ipv4Addr::from(octets))
}
fn hook(rep: &Arc<IpReputation>, bl: &Arc<Blacklist>) -> TrafficHook {
TrafficHook::new(
Arc::clone(rep),
Arc::clone(bl),
DetectAutobanConfig {
enabled: true,
reputation_threshold: -50,
},
60,
)
}
#[test]
fn test_cps_window_counts_and_resets() {
let rep = Arc::new(IpReputation::new());
let bl = Arc::new(Blacklist::new());
let hook = hook(&rep, &bl);
hook.on_accept();
hook.on_accept();
hook.on_accept();
assert_eq!(hook.take_cps(), 3);
assert_eq!(hook.take_cps(), 0);
}
#[test]
fn test_reputation_fall_triggers_autoban() {
let rep = Arc::new(IpReputation::new());
let bl = Arc::new(Blacklist::new());
let hook = hook(&rep, &bl);
let target = ip([10, 1, 0, 1]);
for _ in 0..6 {
rep.record_bad(target);
}
assert_eq!(rep.score(target), -60);
assert!(!bl.is_blocked(target));
hook.on_connection_end(target);
assert!(bl.is_blocked(target));
}
#[test]
fn test_no_autoban_above_threshold() {
let rep = Arc::new(IpReputation::new());
let bl = Arc::new(Blacklist::new());
let hook = hook(&rep, &bl);
let target = ip([10, 1, 0, 2]);
for _ in 0..4 {
rep.record_bad(target);
}
assert_eq!(rep.score(target), -40);
hook.on_connection_end(target);
assert!(!bl.is_blocked(target));
}
#[test]
fn test_disabled_autoban_never_bans() {
let rep = Arc::new(IpReputation::new());
let bl = Arc::new(Blacklist::new());
let hook = TrafficHook::new(
Arc::clone(&rep),
Arc::clone(&bl),
DetectAutobanConfig {
enabled: false,
reputation_threshold: -50,
},
60,
);
let target = ip([10, 1, 0, 3]);
for _ in 0..20 {
rep.record_bad(target);
}
hook.on_connection_end(target);
assert!(hook.ban_offenders() == 0);
assert!(!bl.is_blocked(target));
}
#[test]
fn test_ban_offenders_bans_only_below_threshold() {
let rep = Arc::new(IpReputation::new());
let bl = Arc::new(Blacklist::new());
let hook = hook(&rep, &bl);
let bad = ip([10, 2, 0, 1]);
let ok = ip([10, 2, 0, 2]);
for _ in 0..8 {
rep.record_bad(bad);
}
rep.record_good(ok);
assert_eq!(hook.ban_offenders(), 1);
assert!(bl.is_blocked(bad));
assert!(!bl.is_blocked(ok));
assert_eq!(hook.ban_offenders(), 0);
}
#[test]
fn test_autoban_ttl_expires() {
let rep = Arc::new(IpReputation::new());
let bl = Arc::new(Blacklist::new());
let hook = TrafficHook::new(
Arc::clone(&rep),
Arc::clone(&bl),
DetectAutobanConfig {
enabled: true,
reputation_threshold: -50,
},
// Zero TTL as a time mock: the ban must be dead on arrival.
0,
);
let target = ip([10, 3, 0, 1]);
for _ in 0..20 {
rep.record_bad(target);
}
hook.on_connection_end(target);
assert!(!bl.is_blocked(target), "zero TTL must not produce an active ban");
}
}

View file

@ -9,30 +9,41 @@ pub struct PrefixStatsVal {
pub syn_count: u64,
pub pkt_count: u64,
pub last_seen_ns: u64,
/// 64-bit bitmap of hashed source addresses; popcount estimates the number
/// of distinct sources in the window.
pub source_bits: u64,
}
impl PrefixStatsVal {
/// Parses the raw 24-byte map value.
/// Parses the raw 32-byte map value.
#[must_use]
pub fn from_bytes(bytes: [u8; 24]) -> Self {
pub fn from_bytes(bytes: [u8; 32]) -> Self {
let read_u64 =
|range: std::ops::Range<usize>| u64::from_le_bytes(bytes[range].try_into().expect("8-byte field"));
Self {
syn_count: read_u64(0..8),
pkt_count: read_u64(8..16),
last_seen_ns: read_u64(16..24),
source_bits: read_u64(24..32),
}
}
/// Serialises the value into the raw 24-byte map layout.
/// Serialises the value into the raw 32-byte map layout.
#[must_use]
pub fn to_bytes(self) -> [u8; 24] {
let mut out = [0u8; 24];
pub fn to_bytes(self) -> [u8; 32] {
let mut out = [0u8; 32];
out[0..8].copy_from_slice(&self.syn_count.to_le_bytes());
out[8..16].copy_from_slice(&self.pkt_count.to_le_bytes());
out[16..24].copy_from_slice(&self.last_seen_ns.to_le_bytes());
out[24..32].copy_from_slice(&self.source_bits.to_le_bytes());
out
}
/// Estimated number of distinct sources seen in this window.
#[must_use]
pub fn unique_sources(&self) -> u64 {
u64::from(self.source_bits.count_ones())
}
}
/// Aggregated counters for one prefix over a detection window.
@ -178,26 +189,10 @@ impl PrefixStatsSource for XdpPrefixStats {
syn_count: val.syn_count,
pkt_count: val.pkt_count,
last_seen_ns: val.last_seen_ns,
unique_sources: 0,
unique_sources: val.unique_sources(),
},
))
})
.collect())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn stats_val_roundtrip() {
let val = PrefixStatsVal {
syn_count: 42,
pkt_count: 100,
last_seen_ns: 1_234_567_890,
};
assert_eq!(PrefixStatsVal::from_bytes(val.to_bytes()), val);
assert_eq!(size_of::<PrefixStatsVal>(), 24);
}
}

View file

@ -115,60 +115,3 @@ pub async fn send_webhook(url: String, alert: Alert) {
tracing::warn!("webhook delivery failed: {e}");
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_alert_display_with_ip() {
let alert = Alert::new(
AlertLevel::Critical,
"possible attack".into(),
Some(Ipv4Addr::new(192, 168, 1, 1)),
100500.0,
);
let s = alert.to_string();
assert!(s.contains("CRITICAL"));
assert!(s.contains("192.168.1.1"));
}
#[test]
fn test_alert_display_without_ip() {
let alert = Alert::new(AlertLevel::Info, "traffic spike".into(), None, 5000.0);
let s = alert.to_string();
assert!(s.contains("INFO"));
assert!(s.contains("traffic spike"));
}
#[test]
fn test_dispatcher_two_transitions_two_alerts() {
let dispatcher = AlertDispatcher::new();
assert_eq!(dispatcher.on_status(AttackStatus::Normal), None);
assert_eq!(dispatcher.on_status(AttackStatus::Suspicious), None);
let started = dispatcher.on_status(AttackStatus::UnderAttack);
assert_eq!(dispatcher.on_status(AttackStatus::UnderAttack), None);
assert_eq!(dispatcher.on_status(AttackStatus::UnderAttack), None);
let ended = dispatcher.on_status(AttackStatus::Normal);
assert_eq!(dispatcher.on_status(AttackStatus::Normal), None);
assert!(started.is_some());
assert!(ended.is_some());
assert!(
started.expect("started alert").message.contains("attack started")
&& ended.expect("ended alert").message.contains("attack ended")
);
}
#[test]
fn test_dispatcher_suspicious_does_not_flap_alerts() {
let dispatcher = AlertDispatcher::new();
for status in [
AttackStatus::Normal,
AttackStatus::Suspicious,
AttackStatus::Normal,
AttackStatus::Suspicious,
] {
assert_eq!(dispatcher.on_status(status), None);
}
}
}

View file

@ -43,43 +43,3 @@ impl TrafficProfiler {
(pps / base).min(10.0)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_profiler_record_and_baseline() {
let mut p = TrafficProfiler::new();
p.record(1000.0);
p.record(1100.0);
let base = p.baseline();
assert!(base > 0.0);
}
#[test]
fn test_anomaly_score_normal() {
let mut p = TrafficProfiler::new();
for _ in 0..10 {
p.record(100.0);
}
let score = p.anomaly_score(100.0);
assert!(score < 2.0);
}
#[test]
fn test_anomaly_score_capped() {
let mut p = TrafficProfiler::new();
for _ in 0..10 {
p.record(1.0);
}
let score = p.anomaly_score(1_000_000.0);
assert!((score - 10.0).abs() < 0.001);
}
#[test]
fn test_anomaly_score_zero_baseline() {
let p = TrafficProfiler::new();
assert_eq!(p.anomaly_score(100.0), 0.0);
}
}

View file

@ -190,52 +190,3 @@ fn parse_value(value: &str) -> Option<f64> {
v => v.parse::<f64>().ok(),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_simple_and_labeled_lines() {
let set = parse("up 1\nxdp_total{iface=\"eth0\"} 42\n");
assert_eq!(set.sum("up"), 1.0);
assert_eq!(set.labeled("xdp_total", "iface", "eth0"), Some(42.0));
}
#[test]
fn skips_comments_help_type_and_empty_lines() {
let input = "# HELP rampart_xdp_total Total\n# TYPE rampart_xdp_total gauge\n\nrampart_xdp_total 7\n";
let set = parse(input);
assert_eq!(set.samples().len(), 1);
assert_eq!(set.sum("rampart_xdp_total"), 7.0);
}
#[test]
fn ignores_timestamp_and_special_values() {
let set = parse("m1 10 1700000000000\nm2 +Inf\nm3 NaN\nbroken_line_no_value\nbad{} \nm4 -2.5e3\n");
assert_eq!(set.sum("m1"), 10.0);
assert_eq!(set.sum("m2"), f64::INFINITY);
assert!(set.labeled("m3", "x", "y").is_none());
assert_eq!(set.sum("m4"), -2500.0);
}
#[test]
fn sums_series_with_same_name() {
let input = "bans{reason=\"cps\"} 3\nbans{reason=\"syn\"} 4\nbans 5\n";
assert_eq!(parse(input).sum("bans"), 12.0);
}
#[test]
fn handles_spaces_in_label_values() {
let set = parse("m{k=\"a b\", j=\"v w\"} 1\n");
assert_eq!(set.labeled("m", "k", "a b"), Some(1.0));
assert_eq!(set.labeled("m", "j", "v w"), Some(1.0));
}
#[test]
fn handles_escaped_quotes_and_backslashes_in_labels() {
let set = parse("m{q=\"a\\\"b\", s=\"c\\\\d\"} 1\n");
assert_eq!(set.labeled("m", "q", "a\"b"), Some(1.0));
assert_eq!(set.labeled("m", "s", "c\\d"), Some(1.0));
}
}

View file

@ -96,7 +96,12 @@ impl XdpFilter {
})
}
/// Reads the `prefix_stats` map (aggregates per /24 and /64 prefix).
/// Reads and resets the `prefix_stats` map (aggregates per /24 and /64).
///
/// The counters are per-window by contract: the detector compares them
/// against fixed thresholds, so leaving them cumulative would eventually
/// flag every prefix. Packets that arrive between the read and the reset
/// are lost, which is acceptable for statistics.
///
/// # Errors
/// XDP is not loaded, the map is missing from the object, or a BPF read fails.
@ -110,10 +115,13 @@ impl XdpFilter {
let Some(val) = map.lookup(&kb, MapFlags::ANY).context("prefix_stats lookup failed")? else {
continue;
};
let Ok(vb) = <[u8; 24]>::try_from(val.as_slice()) else {
let Ok(vb) = <[u8; 32]>::try_from(val.as_slice()) else {
continue;
};
out.push((PrefixKey::from_bytes(kb), PrefixStatsVal::from_bytes(vb)));
if let Err(e) = map.update(&kb, &[0u8; 32], MapFlags::ANY) {
tracing::debug!(prefix = ?PrefixKey::from_bytes(kb), error = %e, "prefix_stats reset failed");
}
}
Ok(out)
}

View file

@ -238,6 +238,30 @@ fn rejects_rate_limit_burst_below_one() {
}
}
#[test]
fn relay_idle_timeout_defaults_to_300_and_accepts_the_full_range() {
let config = Config::parse_str("").expect("empty config must parse");
assert_eq!(config.limits.relay_idle_timeout_secs, 300);
for secs in [1u64, 60, 300, 86_400] {
let toml = format!("[limits]\nrelay_idle_timeout_secs = {secs}\n");
let config = Config::parse_str(&toml).expect("in-range idle timeout must parse");
assert_eq!(config.limits.relay_idle_timeout_secs, secs);
}
}
#[test]
fn rejects_out_of_range_relay_idle_timeout() {
for secs in [0u64, 86_401] {
let toml = format!("[limits]\nrelay_idle_timeout_secs = {secs}\n");
let err = Config::parse_str(&toml).expect_err("idle timeout outside 1..=86400 must be rejected");
assert!(
err.to_string().contains("limits.relay_idle_timeout_secs"),
"idle timeout '{secs}' must be rejected"
);
}
}
#[test]
fn rejects_out_of_range_ban_duration() {
let err = Config::parse_str("[ban]\nban_duration_secs = 0\n").expect_err("zero ban duration must be rejected");

View file

@ -3,7 +3,7 @@
use rampart::config::Config;
use rampart::engine::challenge::DifficultyAdjuster;
use rampart::engine::listener::AcceptBackoff;
use rampart::engine::listener::{AcceptBackoff, build_listener, parse_listen_addr};
use rampart::engine::tunnel::Gateway;
use rampart::filter::blacklist::Blacklist;
use rampart::filter::rate_limit::RateLimiter;
@ -11,7 +11,7 @@ use rampart::protocol::ProtocolRegistry;
use rampart::traffic::reputation::IpReputation;
use std::collections::HashSet;
use std::io;
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
use std::sync::Arc;
use std::sync::Mutex;
use std::sync::atomic::AtomicU64;
@ -263,6 +263,45 @@ async fn accept_backoff_sleeps_instead_of_spinning() {
);
}
/// The listen address is parsed as an IP literal and the socket domain follows
/// the address family, so IPv6 loopback binds instead of forcing IPv4.
#[tokio::test]
async fn binds_ipv4_and_ipv6_loopback() {
let v4 = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
let listener = build_listener(v4).expect("bind IPv4 loopback");
assert!(listener.local_addr().expect("local addr").is_ipv4());
let v6 = SocketAddr::new(IpAddr::V6(Ipv6Addr::LOCALHOST), 0);
let listener = build_listener(v6).expect("bind IPv6 loopback");
assert!(listener.local_addr().expect("local addr").is_ipv6());
}
/// `::` must parse as a wildcard IPv6 listen address instead of being
/// concatenated into the invalid `":::port"` form.
#[test]
fn parses_ipv6_wildcard_listen_address() {
let addr = parse_listen_addr("::", 25565).expect("IPv6 wildcard must parse");
assert_eq!(addr, SocketAddr::new(IpAddr::V6(Ipv6Addr::UNSPECIFIED), 25565));
assert!(addr.is_ipv6());
}
/// The relay idle budget is configurable through `limits` instead of being a
/// hardcoded constant.
#[test]
fn relay_idle_timeout_comes_from_limits_config() {
let mut config = Config::default();
config.limits.relay_idle_timeout_secs = 1;
let gateway = test_gateway(config, HashSet::new());
assert_eq!(gateway.relay_idle_timeout(), Duration::from_secs(1));
let default_gateway = test_gateway(Config::default(), HashSet::new());
assert_eq!(
default_gateway.relay_idle_timeout(),
Duration::from_secs(300),
"the default idle budget is 300s"
);
}
/// A silent pair is closed by the relay idle timeout instead of pinning two
/// descriptors forever.
#[tokio::test]

282
tests/manager_api.rs Normal file
View file

@ -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<AppState> {
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<Body> {
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<Body>) -> Request<Body> {
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<Body>) -> 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)
);
}

34
tests/manager_auth.rs Normal file
View file

@ -0,0 +1,34 @@
//! Manager JWT authentication: token round-trip and rejection of tokens signed
//! for a different audience or with a different secret.
use rampart::manager::auth::{create_token, verify_token};
fn valid_secret() -> String {
"this-is-a-test-secret-32-bytes-long!".to_string()
}
#[test]
fn create_verify_roundtrip_passes() {
let secret = valid_secret();
let token = create_token(&secret, 3600, "rampart").expect("token creation should succeed");
let claims = verify_token(&token, &secret, "rampart").expect("verification should succeed");
assert_eq!(claims.sub, "rampart-admin");
assert_eq!(claims.aud, "rampart");
assert_eq!(claims.role, "admin");
assert!(claims.exp > claims.iat);
}
#[test]
fn verify_rejects_wrong_audience() {
let secret = valid_secret();
let token = create_token(&secret, 3600, "rampart").expect("token creation should succeed");
assert!(verify_token(&token, &secret, "other").is_err());
}
#[test]
fn verify_rejects_wrong_secret() {
let secret = valid_secret();
let other_secret = "another-test-secret-also-32-bytes-long!".to_string();
let token = create_token(&secret, 3600, "rampart").expect("token creation should succeed");
assert!(verify_token(&token, &other_secret, "rampart").is_err());
}

View file

@ -0,0 +1,50 @@
//! Node heartbeat expiry: a stale, missing or unparsable `last_heartbeat`
//! marks the node offline, while a fresh heartbeat leaves the record untouched.
#![cfg(feature = "store-redis")]
use rampart::manager::sync::heartbeat::{NODES_KEY_PATTERN, offline_update};
fn rfc3339(ts: i64) -> String {
chrono::DateTime::from_timestamp(ts, 0)
.expect("in-range timestamp")
.to_rfc3339()
}
#[test]
fn expired_heartbeat_is_marked_offline() {
let now = 2_000_000_i64;
let raw = format!(
r#"{{"name":"edge1","last_heartbeat":"{}","status":"online"}}"#,
rfc3339(now - 120)
);
let updated = offline_update(&raw, now).expect("expired node should be marked offline");
assert!(updated.contains("offline"));
assert!(updated.contains("edge1"));
}
#[test]
fn fresh_heartbeat_is_left_untouched() {
let now = 2_000_000_i64;
let raw = format!(r#"{{"last_heartbeat":"{}","status":"online"}}"#, rfc3339(now - 5));
assert!(offline_update(&raw, now).is_none());
}
#[test]
fn missing_or_broken_timestamp_counts_as_expired() {
let now = 2_000_000_i64;
let updated = offline_update(r#"{"status":"online"}"#, now).expect("missing heartbeat counts as expired");
assert!(updated.contains("offline"));
let updated = offline_update(r#"{"last_heartbeat":"garbage","status":"online"}"#, now)
.expect("unparseable heartbeat counts as expired");
assert!(updated.contains("offline"));
}
#[test]
fn invalid_json_is_ignored() {
assert!(offline_update("not json", 2_000_000).is_none());
}
#[test]
fn node_key_pattern_targets_rampart_nodes() {
assert_eq!(NODES_KEY_PATTERN, "rampart:nodes:*");
}

View file

@ -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::<IpAddr>().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::<IpAddr>().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::<IpAddr>().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::<IpAddr>().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());
}

View file

@ -0,0 +1,23 @@
//! HTTP protocol handler: a zero `max_header_bytes` fails on the public
//! handshake path before any socket I/O happens.
#![cfg(feature = "protocol-http")]
use rampart::config::HttpProtocolConfig;
use rampart::protocol::ProtocolHandler;
use rampart::protocol::http::HttpProtocolHandler;
#[tokio::test]
async fn zero_limit_fails_fast_without_io() {
let config = HttpProtocolConfig::default();
let mut broken = config.clone();
broken.max_header_bytes = 0;
let handler = HttpProtocolHandler::new(&broken, &[]);
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.expect("bind");
let client = tokio::net::TcpStream::connect(listener.local_addr().expect("addr"))
.await
.expect("connect");
let (mut server, _) = listener.accept().await.expect("accept");
drop(listener);
assert!(handler.handshake(&mut server).await.is_err());
drop(client);
}

View file

@ -0,0 +1,92 @@
//! Pure HTTP/1.x request-head parser: head scanning, method/host/version
//! validation, path blocklist and the user-agent requirement.
#![cfg(feature = "protocol-http")]
use rampart::protocol::http::parser::{Policy, Verdict, evaluate, scan_head};
fn policy() -> Policy {
Policy {
max_header_bytes: 8192,
blocked_paths: Vec::new(),
require_user_agent: false,
}
}
#[test]
fn scan_finds_full_head_length() {
assert_eq!(scan_head(b"GET / HTTP/1.1\r\n\r\n"), Some(18));
assert_eq!(scan_head(b"GET / HTTP/1.1\r\n"), None);
}
#[test]
fn valid_request_is_allowed() {
let head = b"POST /api/items?limit=5 HTTP/1.1\r\nHost: example.com\r\n\r\n";
let verdict = evaluate(head, &policy());
assert_eq!(
verdict,
Verdict::Allow {
method: "POST".to_string(),
path: "/api/items".to_string(),
host: "example.com".to_string()
}
);
}
#[test]
fn unknown_method_is_rejected() {
let head = b"TRACE / HTTP/1.1\r\nHost: h\r\n\r\n";
assert!(matches!(evaluate(head, &policy()), Verdict::Reject { .. }));
}
#[test]
fn missing_host_is_rejected() {
let head = b"GET / HTTP/1.1\r\nUser-Agent: t\r\n\r\n";
assert!(matches!(evaluate(head, &policy()), Verdict::Reject { .. }));
}
#[test]
fn http2_version_is_rejected() {
let head = b"GET / HTTP/2.0\r\nHost: h\r\n\r\n";
assert!(matches!(evaluate(head, &policy()), Verdict::Reject { .. }));
}
#[test]
fn malformed_line_is_rejected() {
assert!(matches!(
evaluate(b"nonsense\r\n\r\n", &policy()),
Verdict::Reject { .. }
));
assert!(matches!(
evaluate(b"GET / HTTP/1.1\r\nbroken\r\n\r\n", &policy()),
Verdict::Reject { .. }
));
}
#[test]
fn non_utf8_head_is_rejected() {
assert!(matches!(evaluate(&[0xff, 0xfe], &policy()), Verdict::Reject { .. }));
}
#[test]
fn blocked_path_prefix_is_rejected() {
let mut custom = policy();
custom.blocked_paths = vec!["/admin".to_string()];
assert!(matches!(
evaluate(b"GET /admin/panel HTTP/1.1\r\nHost: h\r\n\r\n", &custom),
Verdict::Reject { .. }
));
assert!(matches!(
evaluate(b"GET /public HTTP/1.1\r\nHost: h\r\n\r\n", &custom),
Verdict::Allow { .. }
));
}
#[test]
fn required_user_agent_enforced() {
let mut custom = policy();
custom.require_user_agent = true;
let head = b"GET / HTTP/1.1\r\nHost: h\r\n\r\n";
assert!(matches!(evaluate(head, &custom), Verdict::Reject { .. }));
let head_with_ua = b"GET / HTTP/1.1\r\nHost: h\r\nUser-Agent: curl/8\r\n\r\n";
assert!(matches!(evaluate(head_with_ua, &custom), Verdict::Allow { .. }));
}

View file

@ -0,0 +1,41 @@
//! Protocol registry contract: an empty registry fails fast at startup and a
//! registered handler resolves by name.
use std::future::Future;
use std::pin::Pin;
use rampart::protocol::{HandshakeResult, ProtocolHandler, ProtocolRegistry, Upstream};
use tokio::net::TcpStream;
struct DummyHandler;
impl ProtocolHandler for DummyHandler {
fn name(&self) -> &'static str {
"dummy"
}
fn handshake<'a>(
&'a self,
_stream: &'a mut TcpStream,
) -> Pin<Box<dyn Future<Output = anyhow::Result<HandshakeResult>> + Send + 'a>> {
Box::pin(async { Ok(HandshakeResult::new(Upstream::new("127.0.0.1:9000"))) })
}
}
#[test]
fn empty_registry_fails_fast() {
let registry = ProtocolRegistry::new();
assert!(registry.is_empty());
assert!(registry.primary().is_err());
}
#[test]
fn registered_handler_is_resolvable() {
let mut registry = ProtocolRegistry::new();
registry.register(Box::new(DummyHandler));
assert_eq!(registry.len(), 1);
assert_eq!(registry.names(), vec!["dummy"]);
assert!(registry.primary().is_ok());
assert!(registry.get("dummy").is_some());
assert!(registry.get("missing").is_none());
}

239
tests/proxy_identity.rs Normal file
View file

@ -0,0 +1,239 @@
//! Client identity behind a trusted PROXY protocol proxy: header address
//! validation, fallback to the transport peer and suppression of bans for
//! addresses inside `proxy_protocol.trusted_cidrs`.
#![cfg(feature = "protocol-minecraft")]
use rampart::config::{Config, ProxyProtocolConfig, TrustedProxyCidr};
use rampart::engine::challenge::DifficultyAdjuster;
use rampart::engine::tunnel::{ClientIpRejection, Gateway, GatewayOutcome, validate_client_ip};
use rampart::filter::blacklist::Blacklist;
use rampart::filter::rate_limit::RateLimiter;
use rampart::protocol::ProtocolRegistry;
use rampart::traffic::reputation::IpReputation;
use std::collections::HashSet;
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use std::sync::Arc;
use std::sync::Mutex;
use std::sync::atomic::AtomicU64;
use tokio::io::AsyncWriteExt;
use tokio::net::{TcpListener, TcpStream};
/// Builds a gateway with no XDP/ClickHouse writers and an empty protocol
/// registry, so every connection stops at the admission filters.
fn test_gateway(config: Config, whitelist: HashSet<IpAddr>) -> Arc<Gateway> {
Arc::new(Gateway::new(
Arc::new(config.clone()),
Arc::new(RateLimiter::new(
config.limits.rate_limit_pps,
config.limits.rate_limit_burst,
)),
Arc::new(Blacklist::new()),
Arc::new(Mutex::new(DifficultyAdjuster::default())),
Arc::new(whitelist),
Arc::new(IpReputation::new()),
None,
None,
Arc::new(AtomicU64::new(0)),
Arc::new(ProtocolRegistry::new()),
None,
))
}
/// Encodes a PROXY protocol v2 TCP-over-IPv4 header.
fn proxy_v2_header(source: Ipv4Addr, destination: Ipv4Addr) -> Vec<u8> {
const SIGNATURE: [u8; 12] = *b"\r\n\r\n\0\r\nQUIT\n";
let mut header = Vec::with_capacity(28);
header.extend_from_slice(&SIGNATURE);
header.push(0x21);
header.push(0x11);
header.extend_from_slice(&12u16.to_be_bytes());
header.extend_from_slice(&source.octets());
header.extend_from_slice(&destination.octets());
header.extend_from_slice(&40_000u16.to_be_bytes());
header.extend_from_slice(&25565u16.to_be_bytes());
header
}
/// Runs one connection through the gateway after sending a PROXY v2 header that
/// claims `claimed` as the client address. The transport peer passed to the
/// gateway is `peer`, which lets the test model a trusted proxy explicitly.
async fn handle_with_header(gateway: &Gateway, peer: SocketAddr, claimed: Ipv4Addr) -> GatewayOutcome {
let listener = TcpListener::bind("127.0.0.1:0").await.expect("bind loopback");
let local = listener.local_addr().expect("local addr");
let (client, accepted) = tokio::join!(TcpStream::connect(local), listener.accept());
let mut client = client.expect("connect");
let server = accepted.expect("accept").0;
let destination = match local.ip() {
IpAddr::V4(ip) => ip,
IpAddr::V6(_) => Ipv4Addr::LOCALHOST,
};
client
.write_all(&proxy_v2_header(claimed, destination))
.await
.expect("write PROXY header");
let outcome = gateway.handle(server, peer).await;
drop(client);
outcome
}
/// Runs one connection without a PROXY header.
async fn handle_plain(gateway: &Gateway, peer: SocketAddr) -> GatewayOutcome {
let listener = TcpListener::bind("127.0.0.1:0").await.expect("bind loopback");
let local = listener.local_addr().expect("local addr");
let (_client, server) = tokio::join!(TcpStream::connect(local), listener.accept());
gateway.handle(server.expect("accept").0, peer).await
}
/// Parses a trusted proxy network for the test config.
fn cidr(value: &str) -> TrustedProxyCidr {
value.parse().expect("valid trusted proxy CIDR")
}
/// A trusted proxy may state a public client address, and that address is the
/// one used for admission decisions and bans.
#[tokio::test]
async fn trusted_proxy_header_ip_is_used_for_identity_and_bans() {
let mut config = Config::default();
config.limits.rate_limit_pps = 0.0;
config.limits.rate_limit_burst = 0.0;
config.proxy_protocol.ingress_enabled = true;
config.proxy_protocol.trusted_cidrs = vec![cidr("127.0.0.1/32")];
let gateway = test_gateway(config, HashSet::new());
let claimed = Ipv4Addr::new(198, 51, 100, 7);
let peer = SocketAddr::from((Ipv4Addr::LOCALHOST, 51_100));
for _ in 0..5 {
let outcome = handle_with_header(&gateway, peer, claimed).await;
assert!(outcome.result.is_ok(), "a rate-limited connection is dropped silently");
assert_eq!(
outcome.client_ip,
Some(IpAddr::V4(claimed)),
"the header IP, not the proxy IP, is the client identity"
);
}
assert!(
gateway.blacklist.is_blocked(IpAddr::V4(claimed)),
"repeated rate-limit hits must ban the header IP"
);
assert!(
!gateway.blacklist.is_blocked(peer.ip()),
"the trusted proxy itself must stay unbanned"
);
}
/// Header addresses that cannot be a real client are rejected and the
/// transport peer becomes the identity.
#[test]
fn rejects_header_addresses_that_cannot_be_a_client() {
let config = ProxyProtocolConfig {
trusted_cidrs: vec![cidr("10.0.0.0/8")],
..ProxyProtocolConfig::default()
};
let cases = [
("0.0.0.0", ClientIpRejection::Unspecified),
("::", ClientIpRejection::Unspecified),
("127.0.0.1", ClientIpRejection::Loopback),
("::1", ClientIpRejection::Loopback),
("169.254.10.1", ClientIpRejection::LinkLocal),
("fe80::1", ClientIpRejection::LinkLocal),
("224.0.0.1", ClientIpRejection::Multicast),
("ff02::1", ClientIpRejection::Multicast),
("255.255.255.255", ClientIpRejection::Broadcast),
("::ffff:127.0.0.1", ClientIpRejection::Loopback),
("::ffff:169.254.10.1", ClientIpRejection::LinkLocal),
];
for (address, expected) in cases {
let ip = address.parse().expect("valid test address");
assert_eq!(validate_client_ip(&config, ip), Err(expected), "address {address}");
}
}
/// A proxy must not be able to claim an address of the proxy network itself.
#[test]
fn rejects_header_address_inside_trusted_cidrs() {
let config = ProxyProtocolConfig {
trusted_cidrs: vec![cidr("198.51.100.0/24"), cidr("2001:db8:2::/48")],
..ProxyProtocolConfig::default()
};
assert_eq!(
validate_client_ip(&config, "198.51.100.7".parse().expect("ipv4")),
Err(ClientIpRejection::TrustedProxy)
);
assert_eq!(
validate_client_ip(&config, "2001:db8:2::7".parse().expect("ipv6")),
Err(ClientIpRejection::TrustedProxy)
);
assert_eq!(
validate_client_ip(&config, "::ffff:198.51.100.7".parse().expect("mapped ipv4")),
Err(ClientIpRejection::TrustedProxy),
"an IPv4-mapped address must match the IPv4 proxy network"
);
assert!(
validate_client_ip(&config, "203.0.113.7".parse().expect("ipv4")).is_ok(),
"an address outside the proxy networks is a valid client identity"
);
}
/// An invalid header address falls back to the transport peer, and the peer
/// (itself a trusted proxy) is never banned.
#[tokio::test]
async fn invalid_header_ip_falls_back_to_peer_and_suppresses_bans() {
let mut config = Config::default();
config.limits.rate_limit_pps = 0.0;
config.limits.rate_limit_burst = 0.0;
config.proxy_protocol.ingress_enabled = true;
config.proxy_protocol.trusted_cidrs = vec![cidr("127.0.0.1/32")];
let gateway = test_gateway(config, HashSet::new());
let peer = SocketAddr::from((Ipv4Addr::LOCALHOST, 51_101));
for _ in 0..8 {
let outcome = handle_with_header(&gateway, peer, Ipv4Addr::LOCALHOST).await;
assert!(outcome.result.is_ok());
assert_eq!(
outcome.client_ip,
Some(peer.ip()),
"a rejected header IP must fall back to the transport peer"
);
}
assert!(
gateway.blacklist.is_empty(),
"a trusted proxy address must never be banned"
);
}
/// A header claiming an address inside `trusted_cidrs` is rejected, and the
/// fallback peer (also a trusted proxy) is not banned either.
#[tokio::test]
async fn header_inside_trusted_cidrs_is_rejected_and_never_banned() {
let mut config = Config::default();
config.limits.rate_limit_pps = 0.0;
config.limits.rate_limit_burst = 0.0;
config.proxy_protocol.ingress_enabled = true;
config.proxy_protocol.trusted_cidrs = vec![cidr("127.0.0.1/32"), cidr("198.51.100.0/24")];
let gateway = test_gateway(config, HashSet::new());
let claimed = Ipv4Addr::new(198, 51, 100, 7);
let peer = SocketAddr::from((Ipv4Addr::LOCALHOST, 51_102));
for _ in 0..5 {
let outcome = handle_with_header(&gateway, peer, claimed).await;
assert_eq!(
outcome.client_ip,
Some(peer.ip()),
"a proxy must not claim another proxy address as the client"
);
}
assert!(
gateway.blacklist.is_empty(),
"neither the claimed proxy address nor the fallback peer may be banned"
);
}
/// Plain traffic without PROXY protocol keeps using the transport peer.
#[tokio::test]
async fn plain_connection_uses_the_transport_peer() {
let gateway = test_gateway(Config::default(), HashSet::new());
let peer = SocketAddr::from(([198, 51, 100, 20], 51_103));
let outcome = handle_plain(&gateway, peer).await;
assert_eq!(outcome.client_ip, Some(peer.ip()));
}

View file

@ -152,7 +152,7 @@ fn mapped_ipv6_treated_as_ipv4() {
#[test]
fn prefix_key_roundtrip_and_layout() {
assert_eq!(size_of::<PrefixKey>(), 24);
assert_eq!(size_of::<PrefixStatsVal>(), 24);
assert_eq!(size_of::<PrefixStatsVal>(), 32);
let key = PrefixKey::new(v4([10, 1, 2, 3]));
assert_eq!(key.family, rampart::traffic::prefix::PREFIX_FAMILY_V4);
assert_eq!(key.to_prefix(), Some(v4([10, 1, 2, 0])));

127
tests/traffic_hook.rs Normal file
View file

@ -0,0 +1,127 @@
//! Traffic hook on the hot path: the cps window, reputation-driven auto-ban,
//! the attack-detector escalation and the ban TTL.
use rampart::config::DetectAutobanConfig;
use rampart::filter::blacklist::Blacklist;
use rampart::traffic::hook::TrafficHook;
use rampart::traffic::reputation::IpReputation;
use std::net::{IpAddr, Ipv4Addr};
use std::sync::Arc;
fn ip(octets: [u8; 4]) -> IpAddr {
IpAddr::V4(Ipv4Addr::from(octets))
}
fn hook(rep: &Arc<IpReputation>, bl: &Arc<Blacklist>) -> TrafficHook {
TrafficHook::new(
Arc::clone(rep),
Arc::clone(bl),
DetectAutobanConfig {
enabled: true,
reputation_threshold: -50,
},
60,
)
}
#[test]
fn test_cps_window_counts_and_resets() {
let rep = Arc::new(IpReputation::new());
let bl = Arc::new(Blacklist::new());
let hook = hook(&rep, &bl);
hook.on_accept();
hook.on_accept();
hook.on_accept();
assert_eq!(hook.take_cps(), 3);
assert_eq!(hook.take_cps(), 0);
}
#[test]
fn test_reputation_fall_triggers_autoban() {
let rep = Arc::new(IpReputation::new());
let bl = Arc::new(Blacklist::new());
let hook = hook(&rep, &bl);
let target = ip([10, 1, 0, 1]);
for _ in 0..6 {
rep.record_bad(target);
}
assert_eq!(rep.score(target), -60);
assert!(!bl.is_blocked(target));
hook.on_connection_end(target);
assert!(bl.is_blocked(target));
}
#[test]
fn test_no_autoban_above_threshold() {
let rep = Arc::new(IpReputation::new());
let bl = Arc::new(Blacklist::new());
let hook = hook(&rep, &bl);
let target = ip([10, 1, 0, 2]);
for _ in 0..4 {
rep.record_bad(target);
}
assert_eq!(rep.score(target), -40);
hook.on_connection_end(target);
assert!(!bl.is_blocked(target));
}
#[test]
fn test_disabled_autoban_never_bans() {
let rep = Arc::new(IpReputation::new());
let bl = Arc::new(Blacklist::new());
let hook = TrafficHook::new(
Arc::clone(&rep),
Arc::clone(&bl),
DetectAutobanConfig {
enabled: false,
reputation_threshold: -50,
},
60,
);
let target = ip([10, 1, 0, 3]);
for _ in 0..20 {
rep.record_bad(target);
}
hook.on_connection_end(target);
assert!(hook.ban_offenders() == 0);
assert!(!bl.is_blocked(target));
}
#[test]
fn test_ban_offenders_bans_only_below_threshold() {
let rep = Arc::new(IpReputation::new());
let bl = Arc::new(Blacklist::new());
let hook = hook(&rep, &bl);
let bad = ip([10, 2, 0, 1]);
let ok = ip([10, 2, 0, 2]);
for _ in 0..8 {
rep.record_bad(bad);
}
rep.record_good(ok);
assert_eq!(hook.ban_offenders(), 1);
assert!(bl.is_blocked(bad));
assert!(!bl.is_blocked(ok));
assert_eq!(hook.ban_offenders(), 0);
}
#[test]
fn test_autoban_ttl_expires() {
let rep = Arc::new(IpReputation::new());
let bl = Arc::new(Blacklist::new());
let hook = TrafficHook::new(
Arc::clone(&rep),
Arc::clone(&bl),
DetectAutobanConfig {
enabled: true,
reputation_threshold: -50,
},
// Zero TTL as a time mock: the ban must be dead on arrival.
0,
);
let target = ip([10, 3, 0, 1]);
for _ in 0..20 {
rep.record_bad(target);
}
hook.on_connection_end(target);
assert!(!bl.is_blocked(target), "zero TTL must not produce an active ban");
}

View file

@ -0,0 +1,25 @@
//! Layout of the `prefix_stats` BPF map value: the 32-byte little-endian
//! encoding round-trips and the struct size matches the kernel side.
use rampart::traffic::prefix::PrefixStatsVal;
#[test]
fn stats_val_roundtrip() {
let val = PrefixStatsVal {
syn_count: 42,
pkt_count: 100,
last_seen_ns: 1_234_567_890,
source_bits: 0b1011,
};
assert_eq!(PrefixStatsVal::from_bytes(val.to_bytes()), val);
assert_eq!(size_of::<PrefixStatsVal>(), 32);
}
#[test]
fn unique_sources_counts_set_bits() {
let val = PrefixStatsVal {
source_bits: 0b1011,
..PrefixStatsVal::default()
};
assert_eq!(val.unique_sources(), 3);
}

View file

@ -0,0 +1,58 @@
//! Alert formatting and the deduplicating dispatcher: alerts fire only on the
//! detector's attack-boundary transitions, never on every tick.
use rampart::traffic::alert::{Alert, AlertDispatcher, AlertLevel};
use rampart::traffic::detector::AttackStatus;
use std::net::Ipv4Addr;
#[test]
fn test_alert_display_with_ip() {
let alert = Alert::new(
AlertLevel::Critical,
"possible attack".into(),
Some(Ipv4Addr::new(192, 168, 1, 1)),
100500.0,
);
let s = alert.to_string();
assert!(s.contains("CRITICAL"));
assert!(s.contains("192.168.1.1"));
}
#[test]
fn test_alert_display_without_ip() {
let alert = Alert::new(AlertLevel::Info, "traffic spike".into(), None, 5000.0);
let s = alert.to_string();
assert!(s.contains("INFO"));
assert!(s.contains("traffic spike"));
}
#[test]
fn test_dispatcher_two_transitions_two_alerts() {
let dispatcher = AlertDispatcher::new();
assert_eq!(dispatcher.on_status(AttackStatus::Normal), None);
assert_eq!(dispatcher.on_status(AttackStatus::Suspicious), None);
let started = dispatcher.on_status(AttackStatus::UnderAttack);
assert_eq!(dispatcher.on_status(AttackStatus::UnderAttack), None);
assert_eq!(dispatcher.on_status(AttackStatus::UnderAttack), None);
let ended = dispatcher.on_status(AttackStatus::Normal);
assert_eq!(dispatcher.on_status(AttackStatus::Normal), None);
assert!(started.is_some());
assert!(ended.is_some());
assert!(
started.expect("started alert").message.contains("attack started")
&& ended.expect("ended alert").message.contains("attack ended")
);
}
#[test]
fn test_dispatcher_suspicious_does_not_flap_alerts() {
let dispatcher = AlertDispatcher::new();
for status in [
AttackStatus::Normal,
AttackStatus::Suspicious,
AttackStatus::Normal,
AttackStatus::Suspicious,
] {
assert_eq!(dispatcher.on_status(status), None);
}
}

View file

@ -0,0 +1,38 @@
//! Hourly EWMA traffic profiler: baseline warming and the capped anomaly score.
use rampart::traffic::profiler::TrafficProfiler;
#[test]
fn test_profiler_record_and_baseline() {
let mut p = TrafficProfiler::new();
p.record(1000.0);
p.record(1100.0);
let base = p.baseline();
assert!(base > 0.0);
}
#[test]
fn test_anomaly_score_normal() {
let mut p = TrafficProfiler::new();
for _ in 0..10 {
p.record(100.0);
}
let score = p.anomaly_score(100.0);
assert!(score < 2.0);
}
#[test]
fn test_anomaly_score_capped() {
let mut p = TrafficProfiler::new();
for _ in 0..10 {
p.record(1.0);
}
let score = p.anomaly_score(1_000_000.0);
assert!((score - 10.0).abs() < 0.001);
}
#[test]
fn test_anomaly_score_zero_baseline() {
let p = TrafficProfiler::new();
assert_eq!(p.anomaly_score(100.0), 0.0);
}

48
tests/tui_prometheus.rs Normal file
View file

@ -0,0 +1,48 @@
//! Prometheus exposition parser: labeled series, comments, timestamps,
//! special float values and label values containing spaces or escapes.
use rampart::tui::prometheus::parse;
#[test]
fn parses_simple_and_labeled_lines() {
let set = parse("up 1\nxdp_total{iface=\"eth0\"} 42\n");
assert_eq!(set.sum("up"), 1.0);
assert_eq!(set.labeled("xdp_total", "iface", "eth0"), Some(42.0));
}
#[test]
fn skips_comments_help_type_and_empty_lines() {
let input = "# HELP rampart_xdp_total Total\n# TYPE rampart_xdp_total gauge\n\nrampart_xdp_total 7\n";
let set = parse(input);
assert_eq!(set.samples().len(), 1);
assert_eq!(set.sum("rampart_xdp_total"), 7.0);
}
#[test]
fn ignores_timestamp_and_special_values() {
let set = parse("m1 10 1700000000000\nm2 +Inf\nm3 NaN\nbroken_line_no_value\nbad{} \nm4 -2.5e3\n");
assert_eq!(set.sum("m1"), 10.0);
assert_eq!(set.sum("m2"), f64::INFINITY);
assert!(set.labeled("m3", "x", "y").is_none());
assert_eq!(set.sum("m4"), -2500.0);
}
#[test]
fn sums_series_with_same_name() {
let input = "bans{reason=\"cps\"} 3\nbans{reason=\"syn\"} 4\nbans 5\n";
assert_eq!(parse(input).sum("bans"), 12.0);
}
#[test]
fn handles_spaces_in_label_values() {
let set = parse("m{k=\"a b\", j=\"v w\"} 1\n");
assert_eq!(set.labeled("m", "k", "a b"), Some(1.0));
assert_eq!(set.labeled("m", "j", "v w"), Some(1.0));
}
#[test]
fn handles_escaped_quotes_and_backslashes_in_labels() {
let set = parse("m{q=\"a\\\"b\", s=\"c\\\\d\"} 1\n");
assert_eq!(set.labeled("m", "q", "a\"b"), Some(1.0));
assert_eq!(set.labeled("m", "s", "c\\d"), Some(1.0));
}

View file

@ -69,7 +69,7 @@ fn map_key_and_value_sizes_match_the_rust_encoding() {
("blacklist6_map", 20, 8),
("whitelist_map", 8, 1),
("whitelist6_map", 20, 1),
("prefix_stats", 24, 24),
("prefix_stats", 24, 32),
("stats_map", 4, 8),
];
for (name, key_size, value_size) in expected {

View file

@ -34,6 +34,7 @@ struct prefix_stats_val {
__u64 syn_count;
__u64 pkt_count;
__u64 last_seen_ns; // bpf_ktime_get_ns()
__u64 source_bits; // 64-bit bitmap of hashed source addresses
};
/**
@ -87,6 +88,24 @@ static __always_inline void prefix_key_from_v6(struct prefix_key *key,
__builtin_memcpy(key->addr, src_addr, 8);
}
/**
* Maps a 32-bit source identifier to one bit of a 64-bit bitmap.
*
* The subnet detector needs an estimate of distinct sources ("spoof gate":
* a /24 flooded from one IP is not a botnet). Exact counting in XDP would
* need an unbounded map, so we set a bit of a multiplicative hash. Collisions
* can only over-count, and with min_unique_sources=16 the 64-bit space makes
* that unlikely for a real botnet while a single source still sets one bit.
*
* @param src_id identifier that differs per source address
* @return a single-bit mask
*/
static __always_inline __u64 source_bit(__u32 src_id)
{
__u32 hash = src_id * 2654435761u;
return 1ULL << (hash >> 26);
}
/**
* Increment the counters for one prefix.
*
@ -97,17 +116,21 @@ static __always_inline void prefix_key_from_v6(struct prefix_key *key,
* @param key prefix key, already built
* @param is_syn 1 counts a SYN, 0 counts any other packet
* @param now current bpf_ktime_get_ns() timestamp
* @param src_id 32-bit identifier of the full source address
*/
static __always_inline void update_prefix_stats(struct prefix_key *key,
__u8 is_syn, __u64 now)
__u8 is_syn, __u64 now,
__u32 src_id)
{
__u64 bit = source_bit(src_id);
struct prefix_stats_val *val = bpf_map_lookup_elem(&prefix_stats, key);
if (!val) {
struct prefix_stats_val init = {
.syn_count = is_syn ? 1 : 0,
.pkt_count = is_syn ? 0 : 1,
.syn_count = is_syn ? 1 : 0,
.pkt_count = is_syn ? 0 : 1,
.last_seen_ns = now,
.source_bits = bit,
};
bpf_map_update_elem(&prefix_stats, key, &init, BPF_ANY);
return;
@ -117,6 +140,7 @@ static __always_inline void update_prefix_stats(struct prefix_key *key,
__sync_fetch_and_add(&val->syn_count, 1);
else
__sync_fetch_and_add(&val->pkt_count, 1);
__sync_fetch_and_or(&val->source_bits, bit);
val->last_seen_ns = now;
}

View file

@ -425,7 +425,9 @@ int rampart_universal_filter(struct xdp_md *ctx)
struct prefix_key pkey6;
prefix_key_from_v6(&pkey6, src6);
struct tcphdr *tcp6 = (struct tcphdr *)l4;
update_prefix_stats(&pkey6, (tcp6->syn && !tcp6->ack) ? 1 : 0, now);
__u32 v6_id;
__builtin_memcpy(&v6_id, src6 + 12, 4); // interface ID differs per host
update_prefix_stats(&pkey6, (tcp6->syn && !tcp6->ack) ? 1 : 0, now, v6_id);
inc_pass();
return XDP_PASS;
}
@ -560,7 +562,7 @@ int rampart_universal_filter(struct xdp_md *ctx)
}
// Count SYN only after throttle passed (don't count throttled SYNs)
update_prefix_stats(&pkey, 1, now);
update_prefix_stats(&pkey, 1, now, src_ip);
// Create conntrack entry for new connection. A SYN may carry data
// (TCP Fast Open), which is acknowledged as part of the handshake;
@ -584,7 +586,7 @@ int rampart_universal_filter(struct xdp_md *ctx)
// Connection tracking lookup.
// pkt_count: all non-SYN TCP that survived blacklist/bypass/throttle
update_prefix_stats(&pkey, 0, now);
update_prefix_stats(&pkey, 0, now, src_ip);
// RST challenge proof: match a pending challenge before conntrack,
// because the RST answers a flow that was never tracked.