guard/docs/testing.md
loki5512344 280284667f
docs: per-task roadmap, architecture and changelog
- Split TODO into a thin status index plus docs/roadmap/ with one file per
  task (v0.4 reliability, v0.5 product, v0.6 research, icebox).
- Add docs/architecture.md (current processes, packet/data path, layers,
  storage, metrics) and docs/development.md (rules, gates, DoD).
- Add CHANGELOG.md reconstructed from history; move round details out of
  TODO.
- Align docs with the code: config defaults and missing [detect]/
  [protocol.http] sections, XDP metric names, ClickHouse table and TTL,
  Redis RDB restore, multiarch clang include, CLI binary name.
- Add scripts/check_docs_links.sh and run it in CI.
- release profile: thin LTO + one codegen unit. Binary 12.3 MB -> 9.7 MB,
  http parser bench 314 ns -> 278 ns; panic=abort stays off for
  catch_unwind in the Redis subscriber.
- Drop the unused JWT role claim; fix 'rampart doctor' hints in the CLI.
2026-11-16 14:51:50 +01:00

194 lines
7.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Testing - Rampart
> Как тестировать: unit, integration, нагрузочное, DDoS simulation.
---
## 1. Unit и integration тесты (Rust)
```bash
cargo test # все тесты
cargo test --test config_parse
cargo test -- --nocapture # с выводом
```
Существующие наборы (39 файлов в `tests/`):
| Группа | Тесты |
|--------|-------|
| Конфиг и запуск | `config_parse`, `app_shutdown` |
| Фильтры и лимиты | `filter_logic`, `connection_limits`, `proxy_identity` |
| Протоколы | `protocol_registry`, `protocol_registry_contract`, `http_protocol`, `protocol_http_parser`, `protocol_http_handler`, `proxy_v2_parser` |
| PoW и challenge | `pow_roundtrip`, `pow_difficulty` |
| Детекция | `subnet_detection`, `traffic_hook`, `traffic_intel`, `traffic_prefix_stats`, `traffic_profile_alert`, `traffic_profile_profiler` |
| Manager API | `manager_api`, `manager_auth`, `manager_heartbeat`, `manager_security` |
| Хранилища | `redis_backoff`, `clickhouse_writer` |
| TUI | `tui_metrics`, `tui_prometheus` |
| XDP | `xdp_attach_smoke`, `xdp_ban_clock`, `xdp_ban_keys`, `xdp_ban_v6`, `xdp_diagnostics`, `xdp_events`, `xdp_globals`, `xdp_loader`, `xdp_object_maps`, `xdp_services`, `xdp_whitelist_keys` |
| End-to-end | `edge_e2e` |
---
## 2. Статический анализ
```bash
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo deny check
```
E2E-сценарии живут в `tests/edge_e2e.rs`: реальный TCP-клиент через продакшн-accept-loop и
pipeline до upstream на loopback (обычный HTTP, PoW с решённым и неверным nonce, rate-limit,
blacklist). Root и внешняя сеть не нужны, каждый тест укладывается в 5 с:
```bash
cargo test --all-features --test edge_e2e
```
XDP: smoke-check компиляции BPF-программы:
```bash
mkdir -p target/xdp
clang -O2 -g -target bpf -I"/usr/include/$(gcc -print-multiarch)" \
-c xdp/core/universal_filter.c -o target/xdp/universal_filter.o
```
Функциональные проверки на реальном ядре (нужен root: CAP_BPF + CAP_NET_ADMIN,
`bpftool`, `clang`, `python3`):
```bash
sudo bash scripts/xdp_ipv6_smoke.sh
```
Поднимает netns + veth, грузит программу через verifier и проверяет: бан IPv6 и IPv4
(включая короткие UDP-датаграммы), снятие бана, whitelist поверх активного бана, истечение
TTL по монотонным часам и `udp_policy = "rate-limit"` для IPv6 (политика патчится в
`.rodata` до загрузки).
```bash
sudo bash scripts/xdp_pkt_test.sh
```
Проверяет то, что veth-смок поймать не может по построению: Ethernet-паддинг (длина
TCP-payload по `ip->tot_len`), VLAN/QinQ-теги и фрагменты — забаненный источник не должен
проходить ни тегированным, ни фрагментированным.
`scripts/xdp_netns_smoke.sh` дополнительно гоняет реальный бинарь `rampart` end-to-end
(требует `hping3`).
Единая точка входа для CI появится в v0.4 (`scripts/xdp_ci.sh`, см.
[roadmap/v0.4-xdp-ci-harness.md](roadmap/v0.4-xdp-ci-harness.md)); до этого
скрипты выше запускаются вручную.
---
## 3. Fuzzing
Внешние парсеры (HTTP request-head и PROXY protocol v2) фаззятся через `cargo-fuzz`.
Нужен nightly-тулчейн и установленный `cargo-fuzz`:
```bash
rustup toolchain install nightly
cargo install cargo-fuzz
# короткий прогон (60 с на цель), как в CI-смоуке
make fuzz
# длительная кампания локально
cargo +nightly fuzz run http_head fuzz/seeds/http_head -- -max_total_time=600
cargo +nightly fuzz run proxy_v2 -- -max_total_time=600
```
Найденный краш сохраняется в `fuzz/artifacts/<target>/`; воспроизведение —
`cargo +nightly fuzz run <target> fuzz/artifacts/<target>/<file>`. Цели лежат в
`fuzz/fuzz_targets/`, сиды — в `fuzz/seeds/` (каталоги `corpus/`, `artifacts/`
в git не попадают).
Инварианты, которые проверяют цели: парсер не паникует на произвольных байтах,
`scan_head` не выходит за буфер, `parse_v2_header` не потребляет больше
переданного и не принимает заголовок выше лимита, семейство адреса совпадает с
байтом family.
---
## 4. Бенчмарки горячего пути
Микробенчмарки (criterion) для того, что выполняется на каждое соединение:
```bash
cargo bench --all-features --bench hot_paths
# HTML-отчёт: target/criterion/report/index.html
```
Замеряются: `RateLimiter::check`, exact/CIDR/miss lookup в `Blacklist`, `SubnetDetector::evaluate`
на окне из 256 префиксов и разбор HTTP request-head. Сравнивай медианы до/после изменения на
одной машине; абсолютные числа зависят от CPU. Порядок величин на dev-машине (2 vCPU,
релизный профиль с `lto = "thin"`):
| Бенчмарк | Медиана |
|----------|---------|
| `rate_limiter/check` | ~120 ns |
| `blacklist/is_blocked_exact` | ~80 ns |
| `blacklist/is_blocked_cidr` | ~230 ns |
| `blacklist/is_blocked_miss` | ~230 ns |
| `subnet_detector/evaluate_256` | ~2.8 µs |
| `http_parser/evaluate` | ~280 ns |
Для сравнения с сохранённым прогоном: `cargo bench --all-features --bench hot_paths --
--save-baseline before` до изменения, затем `--baseline before` после; criterion покажет
дельту и её значимость.
---
## 5. Локальный integration-стенд (Docker)
```bash
bash deploy/test/run_test.sh
```
Поднимает backend-stub (TCP echo), edge (`rampart` с config.test.toml) и
attacker-контейнер. Сценарии — в [deploy/test/README.md](../deploy/test/README.md).
---
## 6. Нагрузочное тестирование
### Много-IP TCP flood на VDS (edge-only)
`deploy/test/stress/` — полный цикл без Redis/ClickHouse: edge-контейнер с
stub-бэкендом (socat echo) + attacker-контейнер со 100 source IP.
`flood.py` шлёт чистые TCP-соединения (connect / slowloris / keepalive),
во время флуда параллельно подключаются generic TCP-клиенты (`legit.py`),
замеряющие RTT.
```bash
git clone https://github.com/loki5512344ss/guard.git && cd guard
cargo build --release --bin rampart
cd deploy/test/stress && bash run-stress.sh
```
Фазы: A — сырая пропускная способность (лимиты сняты), B — защита (per-IP rate
limit + reputation bans), C — SYN flood hping3, D — активные соединения.
### tcpkali / hping3
```bash
tcpkali --connections 1000 --connect-rate 5000 --duration 60s EDGE_IP:25565
hping3 -S --flood -p 25565 --rand-source EDGE_IP # только на свои серверы!
```
---
## 7. Метрики для проверки во время теста
```bash
curl -s http://localhost:9090/metrics | grep rampart_
# rampart_connections_total{result="allowed|blocked"}
# rampart_rate_limit_hits
# rampart_pow_challenges_total{result=...}
# rampart_attack_status
```
---
*Версия: 3.0 | Ноябрь 2026*