From 246d42ddfa9c7bcc41eef2cf3510476f97d6655b Mon Sep 17 00:00:00 2001 From: loki5512344 Date: Sun, 15 Nov 2026 23:49:40 +0100 Subject: [PATCH] docs(readme): conventional section order, nav buttons, compact TOC --- README.md | 135 ++++++++++++++++++++++++++++++++---------------------- TODO.md | 9 ++-- 2 files changed, 85 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 8ff98ee..3659629 100644 --- a/README.md +++ b/README.md @@ -10,12 +10,18 @@ ![Version](https://img.shields.io/badge/version-0.3.0--dev-green?style=flat-square) ![Status](https://img.shields.io/badge/status-development-yellow?style=flat-square) +[![Docs](https://img.shields.io/badge/docs-index-blue?style=for-the-badge&logo=readthedocs&logoColor=white)](docs/README.md) +[![Quick start](https://img.shields.io/badge/quick%20start-2%20minutes-success?style=for-the-badge)](#быстрый-старт) +[![Configuration](https://img.shields.io/badge/configuration-config.toml-yellow?style=for-the-badge)](docs/configuration.md) +[![API](https://img.shields.io/badge/API-manager-purple?style=for-the-badge&logo=openapiinitiative&logoColor=white)](docs/api.md) +[![License](https://img.shields.io/badge/license-GPLv3-lightgrey?style=for-the-badge&logo=gnu&logoColor=white)](LICENSE) + [Русский](#русский) · [English](#english) > [!WARNING] -> Проект в активной разработке. Числа производительности и API могут меняться. +> Проект в активной разработке: API и числа производительности могут меняться. --- @@ -23,28 +29,19 @@ ## Русский -### Содержание +[Обзор](#обзор) · [Возможности](#возможности) · [Требования](#требования) · [Установка](#установка) · [Быстрый старт](#быстрый-старт) · [Конфигурация](#конфигурация) · [Плагины](#протокол-плагины) · [Производительность](#производительность) · [Документация](#документация) · [Разработка](#разработка) · [Лицензия](#лицензия) -- [Что это](#что-это) -- [Как это работает](#как-это-работает) -- [Возможности](#возможности) -- [Требования](#требования) -- [Быстрый старт](#быстрый-старт) -- [Конфигурация](#конфигурация) -- [Протокол-плагины](#протокол-плагины) -- [Производительность](#производительность) -- [Документация](#документация) -- [Разработка](#разработка) -- [Лицензия](#лицензия) - -### Что это +### Обзор Rampart отбрасывает атакующий трафик до того, как он дойдёт до вашего сервиса. Фильтрация идёт в три уровня: XDP/eBPF в ядре, PoW-challenge в userspace и L7-анализ протокола. Логика конкретного протокола вынесена в плагины, поэтому -одна и та же платформа защищает и веб-сервис, и игровой сервер. +одна платформа защищает и веб-сервис, и игровой сервер. -### Как это работает +Подходит, если нужен свой edge-фильтр на VDS: без покупки «коробки», с +конфигом в TOML и метриками в Prometheus. + +**Как это работает** ``` Атакующий → [XDP/eBPF] → [PoW] → [Userspace Core] → [Плагин] → Ваш сервис @@ -80,28 +77,34 @@ L7-анализ протокола. Логика конкретного прот | XDP | Linux 5.10+, `clang` с `-target bpf`, `libbpf`/`libelf` | | Опционально | Redis (синхронизация блэклиста), ClickHouse (события), GeoIP-база | -### Быстрый старт +### Установка ```bash -# 1. Сборка edge-ноды с HTTP-обработчиком +# Сборка edge-ноды с 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 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 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 cargo fmt --all --check @@ -111,8 +114,21 @@ cargo test --all-features ### Конфигурация -Полный справочник — [docs/configuration.md](docs/configuration.md). Минимальный конфиг: -bind-адрес и порт, список upstream'ов, `[limits]`, опционально `[store]` и `[xdp]`. +```toml +[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 -### 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) -- [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 +### Overview 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, and L7 protocol analysis. Protocol-specific logic lives in plugins, so the same 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 @@ -231,28 +238,34 @@ Attacker → [XDP/eBPF] → [PoW] → [Userspace Core] → [Plugin] → Your ser | XDP | Linux 5.10+, `clang` with `-target bpf`, `libbpf`/`libelf` | | Optional | Redis (blacklist sync), ClickHouse (events), GeoIP database | -### Quick start +### Installation ```bash -# 1. Build the edge node with the HTTP handler +# Build the edge node with the HTTP handler 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 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 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 cargo fmt --all --check @@ -262,9 +275,21 @@ cargo test --all-features ### Configuration -Full reference: [docs/configuration.md](docs/configuration.md). The minimal config -needs a bind address and port, upstreams, and `[limits]`; `[store]` and `[xdp]` -are optional. +```toml +[bind] +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 diff --git a/TODO.md b/TODO.md index 2fef2a1..bd0d12f 100644 --- a/TODO.md +++ b/TODO.md @@ -152,10 +152,11 @@ guard/ - [x] `docs/README.md` — единый индекс документации (начало работы, how-to, reference, протоколы, теория/research) + правила ведения: русский язык, один документ = одна задача, reference правится в том же PR, что и код, плоская структура, kebab-case. -- [x] `README.md` — двуязычный: русская часть сверху, английская снизу, общий шапка/бейджи/ - переключатель языка; структура по практике (что это → как работает → возможности → - требования → quick start → конфиг → плагины → производительность → документация → - разработка → лицензия); TOC, копируемые команды, ссылки на docs/README.md. +- [x] `README.md` — двуязычный: русская часть сверху, английская снизу, общая шапка/бейджи/ + переключатель языка, ряд кнопок-навигации (docs, quick start, config, API, license); + секции по конвенции (обзор → возможности → требования → установка → быстрый старт → + конфигурация → плагины → производительность → документация → разработка → лицензия), + компактный TOC строкой, копируемые команды, ссылки на docs/README.md. - [x] `docs/configuration.md` — полная таблица `[xdp]` (включая `udp_policy`) и покрытие IPv4/IPv6; `docs/testing.md` — реальные XDP-smoke'и, а не только clang-проверка. - [x] TUI (ratatui): live-метрики из Prometheus endpoint — готово (src/tui/, 564613b).