docs(readme): conventional section order, nav buttons, compact TOC
This commit is contained in:
parent
918e561a61
commit
246d42ddfa
2 changed files with 85 additions and 59 deletions
135
README.md
135
README.md
|
|
@ -10,12 +10,18 @@
|
||||||

|

|
||||||

|

|
||||||
|
|
||||||
|
[](docs/README.md)
|
||||||
|
[](#быстрый-старт)
|
||||||
|
[](docs/configuration.md)
|
||||||
|
[](docs/api.md)
|
||||||
|
[](LICENSE)
|
||||||
|
|
||||||
[Русский](#русский) · [English](#english)
|
[Русский](#русский) · [English](#english)
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
> [!WARNING]
|
> [!WARNING]
|
||||||
> Проект в активной разработке. Числа производительности и API могут меняться.
|
> Проект в активной разработке: API и числа производительности могут меняться.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -23,28 +29,19 @@
|
||||||
|
|
||||||
## Русский
|
## Русский
|
||||||
|
|
||||||
### Содержание
|
[Обзор](#обзор) · [Возможности](#возможности) · [Требования](#требования) · [Установка](#установка) · [Быстрый старт](#быстрый-старт) · [Конфигурация](#конфигурация) · [Плагины](#протокол-плагины) · [Производительность](#производительность) · [Документация](#документация) · [Разработка](#разработка) · [Лицензия](#лицензия)
|
||||||
|
|
||||||
- [Что это](#что-это)
|
### Обзор
|
||||||
- [Как это работает](#как-это-работает)
|
|
||||||
- [Возможности](#возможности)
|
|
||||||
- [Требования](#требования)
|
|
||||||
- [Быстрый старт](#быстрый-старт)
|
|
||||||
- [Конфигурация](#конфигурация)
|
|
||||||
- [Протокол-плагины](#протокол-плагины)
|
|
||||||
- [Производительность](#производительность)
|
|
||||||
- [Документация](#документация)
|
|
||||||
- [Разработка](#разработка)
|
|
||||||
- [Лицензия](#лицензия)
|
|
||||||
|
|
||||||
### Что это
|
|
||||||
|
|
||||||
Rampart отбрасывает атакующий трафик до того, как он дойдёт до вашего сервиса.
|
Rampart отбрасывает атакующий трафик до того, как он дойдёт до вашего сервиса.
|
||||||
Фильтрация идёт в три уровня: XDP/eBPF в ядре, PoW-challenge в userspace и
|
Фильтрация идёт в три уровня: XDP/eBPF в ядре, PoW-challenge в userspace и
|
||||||
L7-анализ протокола. Логика конкретного протокола вынесена в плагины, поэтому
|
L7-анализ протокола. Логика конкретного протокола вынесена в плагины, поэтому
|
||||||
одна и та же платформа защищает и веб-сервис, и игровой сервер.
|
одна платформа защищает и веб-сервис, и игровой сервер.
|
||||||
|
|
||||||
### Как это работает
|
Подходит, если нужен свой edge-фильтр на VDS: без покупки «коробки», с
|
||||||
|
конфигом в TOML и метриками в Prometheus.
|
||||||
|
|
||||||
|
**Как это работает**
|
||||||
|
|
||||||
```
|
```
|
||||||
Атакующий → [XDP/eBPF] → [PoW] → [Userspace Core] → [Плагин] → Ваш сервис
|
Атакующий → [XDP/eBPF] → [PoW] → [Userspace Core] → [Плагин] → Ваш сервис
|
||||||
|
|
@ -80,28 +77,34 @@ L7-анализ протокола. Логика конкретного прот
|
||||||
| XDP | Linux 5.10+, `clang` с `-target bpf`, `libbpf`/`libelf` |
|
| XDP | Linux 5.10+, `clang` с `-target bpf`, `libbpf`/`libelf` |
|
||||||
| Опционально | Redis (синхронизация блэклиста), ClickHouse (события), GeoIP-база |
|
| Опционально | Redis (синхронизация блэклиста), ClickHouse (события), GeoIP-база |
|
||||||
|
|
||||||
### Быстрый старт
|
### Установка
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. Сборка edge-ноды с HTTP-обработчиком
|
# Сборка edge-ноды с HTTP-обработчиком
|
||||||
cargo build --release --features protocol-http
|
cargo build --release --features protocol-http
|
||||||
|
|
||||||
# 2. Конфиг (путь по умолчанию /etc/rampart/config.toml, переопределяется $RAMPART_CONFIG)
|
# Конфиг: путь по умолчанию /etc/rampart/config.toml,
|
||||||
|
# переопределяется переменной $RAMPART_CONFIG
|
||||||
sudo mkdir -p /etc/rampart
|
sudo mkdir -p /etc/rampart
|
||||||
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml
|
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml
|
||||||
|
|
||||||
# 3. Запуск
|
|
||||||
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
|
|
||||||
```
|
```
|
||||||
|
|
||||||
С XDP (нужен root либо `CAP_BPF` + `CAP_NET_ADMIN`):
|
С XDP-фильтром (нужен root либо `CAP_BPF` + `CAP_NET_ADMIN`):
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cargo build --release --features protocol-http,xdp
|
cargo build --release --features protocol-http,xdp
|
||||||
# в конфиге: [xdp] enabled = true, interface = "eth0"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Проверить, что всё собрано и работает:
|
### Быстрый старт
|
||||||
|
|
||||||
|
```bash
|
||||||
|
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
|
||||||
|
```
|
||||||
|
|
||||||
|
В конфиге для XDP: `[xdp] enabled = true`, `interface = "eth0"`. Метрики —
|
||||||
|
`http://127.0.0.1:9090/metrics`.
|
||||||
|
|
||||||
|
Проверить чекаут перед изменениями:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cargo fmt --all --check
|
cargo fmt --all --check
|
||||||
|
|
@ -111,8 +114,21 @@ cargo test --all-features
|
||||||
|
|
||||||
### Конфигурация
|
### Конфигурация
|
||||||
|
|
||||||
Полный справочник — [docs/configuration.md](docs/configuration.md). Минимальный конфиг:
|
```toml
|
||||||
bind-адрес и порт, список upstream'ов, `[limits]`, опционально `[store]` и `[xdp]`.
|
[bind]
|
||||||
|
address = "0.0.0.0"
|
||||||
|
port = 25565
|
||||||
|
|
||||||
|
[backend]
|
||||||
|
upstreams = ["127.0.0.1:25566"]
|
||||||
|
|
||||||
|
[xdp]
|
||||||
|
enabled = false # требует сборки с feature `xdp`
|
||||||
|
interface = "eth0"
|
||||||
|
udp_policy = "pass" # pass | drop | rate-limit
|
||||||
|
```
|
||||||
|
|
||||||
|
Все поля и значения по умолчанию — [docs/configuration.md](docs/configuration.md).
|
||||||
|
|
||||||
### Протокол-плагины
|
### Протокол-плагины
|
||||||
|
|
||||||
|
|
@ -173,28 +189,19 @@ GNU General Public License v3.0 — [LICENSE](LICENSE).
|
||||||
|
|
||||||
## English
|
## English
|
||||||
|
|
||||||
### Contents
|
[Overview](#overview) · [Features](#features) · [Requirements](#requirements) · [Installation](#installation) · [Quick start](#quick-start) · [Configuration](#configuration) · [Plugins](#protocol-plugins) · [Performance](#performance) · [Documentation](#documentation) · [Development](#development) · [License](#license)
|
||||||
|
|
||||||
- [What it is](#what-it-is)
|
### Overview
|
||||||
- [How it works](#how-it-works)
|
|
||||||
- [Features](#features)
|
|
||||||
- [Requirements](#requirements)
|
|
||||||
- [Quick start](#quick-start)
|
|
||||||
- [Configuration](#configuration)
|
|
||||||
- [Protocol plugins](#protocol-plugins)
|
|
||||||
- [Performance](#performance)
|
|
||||||
- [Documentation](#documentation)
|
|
||||||
- [Development](#development)
|
|
||||||
- [License](#license)
|
|
||||||
|
|
||||||
### What it is
|
|
||||||
|
|
||||||
Rampart drops malicious traffic before it reaches your service. Filtering happens
|
Rampart drops malicious traffic before it reaches your service. Filtering happens
|
||||||
at three levels: XDP/eBPF in the kernel, a proof-of-work challenge in userspace,
|
at three levels: XDP/eBPF in the kernel, a proof-of-work challenge in userspace,
|
||||||
and L7 protocol analysis. Protocol-specific logic lives in plugins, so the same
|
and L7 protocol analysis. Protocol-specific logic lives in plugins, so the same
|
||||||
platform protects a web service and a game server alike.
|
platform protects a web service and a game server alike.
|
||||||
|
|
||||||
### How it works
|
It fits teams that need their own edge filter on a VDS: no appliance to buy, a
|
||||||
|
TOML config, and Prometheus metrics out of the box.
|
||||||
|
|
||||||
|
**How it works**
|
||||||
|
|
||||||
```
|
```
|
||||||
Attacker → [XDP/eBPF] → [PoW] → [Userspace Core] → [Plugin] → Your service
|
Attacker → [XDP/eBPF] → [PoW] → [Userspace Core] → [Plugin] → Your service
|
||||||
|
|
@ -231,28 +238,34 @@ Attacker → [XDP/eBPF] → [PoW] → [Userspace Core] → [Plugin] → Your ser
|
||||||
| XDP | Linux 5.10+, `clang` with `-target bpf`, `libbpf`/`libelf` |
|
| XDP | Linux 5.10+, `clang` with `-target bpf`, `libbpf`/`libelf` |
|
||||||
| Optional | Redis (blacklist sync), ClickHouse (events), GeoIP database |
|
| Optional | Redis (blacklist sync), ClickHouse (events), GeoIP database |
|
||||||
|
|
||||||
### Quick start
|
### Installation
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. Build the edge node with the HTTP handler
|
# Build the edge node with the HTTP handler
|
||||||
cargo build --release --features protocol-http
|
cargo build --release --features protocol-http
|
||||||
|
|
||||||
# 2. Install the config (default is /etc/rampart/config.toml, override with $RAMPART_CONFIG)
|
# Config: default path is /etc/rampart/config.toml,
|
||||||
|
# override it with $RAMPART_CONFIG
|
||||||
sudo mkdir -p /etc/rampart
|
sudo mkdir -p /etc/rampart
|
||||||
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml
|
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml
|
||||||
|
|
||||||
# 3. Run
|
|
||||||
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
|
|
||||||
```
|
```
|
||||||
|
|
||||||
With XDP (root or `CAP_BPF` + `CAP_NET_ADMIN`):
|
With the XDP filter (root or `CAP_BPF` + `CAP_NET_ADMIN`):
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cargo build --release --features protocol-http,xdp
|
cargo build --release --features protocol-http,xdp
|
||||||
# config: [xdp] enabled = true, interface = "eth0"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Verify the checkout:
|
### Quick start
|
||||||
|
|
||||||
|
```bash
|
||||||
|
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
|
||||||
|
```
|
||||||
|
|
||||||
|
For XDP set `[xdp] enabled = true` and `interface = "eth0"`. Metrics are served
|
||||||
|
at `http://127.0.0.1:9090/metrics`.
|
||||||
|
|
||||||
|
Verify the checkout before making changes:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cargo fmt --all --check
|
cargo fmt --all --check
|
||||||
|
|
@ -262,9 +275,21 @@ cargo test --all-features
|
||||||
|
|
||||||
### Configuration
|
### Configuration
|
||||||
|
|
||||||
Full reference: [docs/configuration.md](docs/configuration.md). The minimal config
|
```toml
|
||||||
needs a bind address and port, upstreams, and `[limits]`; `[store]` and `[xdp]`
|
[bind]
|
||||||
are optional.
|
address = "0.0.0.0"
|
||||||
|
port = 25565
|
||||||
|
|
||||||
|
[backend]
|
||||||
|
upstreams = ["127.0.0.1:25566"]
|
||||||
|
|
||||||
|
[xdp]
|
||||||
|
enabled = false # requires the `xdp` feature
|
||||||
|
interface = "eth0"
|
||||||
|
udp_policy = "pass" # pass | drop | rate-limit
|
||||||
|
```
|
||||||
|
|
||||||
|
Every field and its default: [docs/configuration.md](docs/configuration.md).
|
||||||
|
|
||||||
### Protocol plugins
|
### Protocol plugins
|
||||||
|
|
||||||
|
|
|
||||||
9
TODO.md
9
TODO.md
|
|
@ -152,10 +152,11 @@ guard/
|
||||||
- [x] `docs/README.md` — единый индекс документации (начало работы, how-to, reference,
|
- [x] `docs/README.md` — единый индекс документации (начало работы, how-to, reference,
|
||||||
протоколы, теория/research) + правила ведения: русский язык, один документ = одна
|
протоколы, теория/research) + правила ведения: русский язык, один документ = одна
|
||||||
задача, reference правится в том же PR, что и код, плоская структура, kebab-case.
|
задача, reference правится в том же PR, что и код, плоская структура, kebab-case.
|
||||||
- [x] `README.md` — двуязычный: русская часть сверху, английская снизу, общий шапка/бейджи/
|
- [x] `README.md` — двуязычный: русская часть сверху, английская снизу, общая шапка/бейджи/
|
||||||
переключатель языка; структура по практике (что это → как работает → возможности →
|
переключатель языка, ряд кнопок-навигации (docs, quick start, config, API, license);
|
||||||
требования → quick start → конфиг → плагины → производительность → документация →
|
секции по конвенции (обзор → возможности → требования → установка → быстрый старт →
|
||||||
разработка → лицензия); TOC, копируемые команды, ссылки на docs/README.md.
|
конфигурация → плагины → производительность → документация → разработка → лицензия),
|
||||||
|
компактный TOC строкой, копируемые команды, ссылки на docs/README.md.
|
||||||
- [x] `docs/configuration.md` — полная таблица `[xdp]` (включая `udp_policy`) и покрытие IPv4/IPv6;
|
- [x] `docs/configuration.md` — полная таблица `[xdp]` (включая `udp_policy`) и покрытие IPv4/IPv6;
|
||||||
`docs/testing.md` — реальные XDP-smoke'и, а не только clang-проверка.
|
`docs/testing.md` — реальные XDP-smoke'и, а не только clang-проверка.
|
||||||
- [x] TUI (ratatui): live-метрики из Prometheus endpoint — готово (src/tui/, 564613b).
|
- [x] TUI (ratatui): live-метрики из Prometheus endpoint — готово (src/tui/, 564613b).
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue