BSDM-Proxy

High-performance HTTP/HTTPS Forward Proxy & Secure Web Gateway written in Rust.

Features • Architecture • Quick Start • Production • Project Status • Docs

BSDM-Proxy combines a Rust proxy data plane with selective TLS inspection, tiered caching, access policy, authentication and asynchronous security analytics. It can run in a lightweight local mode with SQLite or as a broader analytics stack with Kafka and ClickHouse.

Why BSDM

Rust data plane for HTTP forwarding, CONNECT tunnelling and selective TLS inspection.
Tiered caching with in-memory L1, disk spillover and optional Redis L2.
Policy and identity through ACLs and Basic auth; LDAP/AD, NTLM and Kerberos are beta, while reverse-proxy OIDC is frozen.
Analytics outside the core proxy flow through asynchronous event export to Kafka/ClickHouse; Lite Mode uses SQLite and does not require those services.
Operational surface included: metrics, Admin Console, deployment manifests and documented feature maturity.

Quick start

The smallest documented stack is Lite Mode (изолированный lab/CI: API без токенов, proxy без auth; порты доступны на всех интерфейсах хоста):

git clone https://github.com/onixus/bsdm-proxy.git
cd bsdm-proxy

./scripts/gen-ca.sh
docker compose -f deploy/compose/docker-compose.lite.yml up -d --build

curl http://127.0.0.1:9090/health
curl --cacert certs/ca.crt -x http://127.0.0.1:3128 https://httpbin.org/get

See Lite Mode for the full walkthrough.

Performance / reproducible benchmarks

This README intentionally does not publish headline throughput or latency numbers without a reproducible benchmark report. Performance results should include the exact commit, hardware, OS/kernel, proxy configuration, TLS mode, cache state, load-generator settings, concurrency, throughput, p50/p95/p99 latency, CPU and memory usage.

The benchmark harness and reports can then be compared across architectural changes without turning an unqualified number into a product claim.

Important

Feature maturity varies by component. Before deployment, check the project status matrix. Presence of code or UI does not automatically mean production-ready.

Warning

TLS interception has legal and operational requirements. Use MITM inspection only in controlled environments with appropriate user notice, protected CA private keys and compliance with applicable law.

✨ Основные возможности

Область	Описание возможностей
Proxy & Data Plane	HTTP/HTTPS forward proxy, `CONNECT`-туннелирование, выборочная MITM TLS-инспекция, HTTP/2 upstream, исключения для Certificate Pinning, туннелирование AmneziaWG (AWG).
Многоуровневый кеш	Высокоскоростной sharded L1 (in-memory lock-free), mmap spillover на диск, L2 Redis, условная ревалидация (304), потоковое сжатие (Gzip/Brotli/Zstd), иерархия кешей (ICP / HTCP).
Аутентификация & ACL	Поддержка Basic, LDAP / Active Directory, NTLM, Kerberos (SPNEGO), OIDC. Гранулярные правила ACL (по IP, подсетям, времени, категориям), rate limiting, встроенный DLP-сканер.
Аналитика & Телеметрия	Асинхронный экспорт событий через Apache Kafka, индексация в ClickHouse / SQLite (`cache-indexer`), Search API, Prometheus-метрики, дашборды Grafana.
Безопасность & ML	Микросервис `alert-worker` с дедупликацией инцидентов и SIEM-вебхуками; `ml-worker` для скоринга угроз (UEBA, фишинг, DGA/beacon-детекция) с обратной связью (threat-score write-back).
Threat Intelligence	Мониторинг угроз в режиме Shadow (enforcement реализован как beta, требует явного включения): модуль `threat-intel` периодически собирает и нормализует индикаторы компрометации (OpenPhish, PhishStats, Phishing.Database, URLhaus), ведёт IOC-хранилище и скоринг. Блокировка по фидам по умолчанию выключена — `TI_ENFORCEMENT_MODE=shadow` (ADR 0008).
Расширения & Сайдкары	DNS Sinkhole (UDP RPZ-lite, DoH/DoT проксирование), Semantic Cache для LLM/AI-запросов, WASM-плагины через Wasmtime SDK, антивирусная проверка ICAP (ClamAV).
Клиент & Split Routing	Standalone Rust-клиент `bsdm-connect`, локальное разделение маршрутов по доменам (`Direct`/`Proxy`/`Tunnel`/`Block`), генератор PAC-файлов с защитой от JS-инъекций, защищенный веб-интерфейс на `:8765`, скаффолды для macOS и Android.
Администрирование	Единая веб-панель управления (Admin Console) по адресу `/admin/`, REST и gRPC Control Plane API, Helm-чарты, systemd-пакеты.

🏛 Архитектура

flowchart TB
    subgraph Clients["Клиентский сегмент"]
        Browser["Браузер / Агент"]
        DNSClient["DNS Клиент"]
    end

    subgraph DataPlane["Data Plane (Трафик)"]
        Proxy["BSDM-Proxy (:3128)\n• MITM TLS Engine\n• L1 Memory Cache\n• ACL & Categorization\n• Admin Console (:9090/admin/)"]
        DNSSink["dns-sinkhole (:5353)\nDNS Sinkhole / DoH / DoT"]
        Redis[("Redis (L2 Cache)")]
    end

    subgraph UpstreamNet["Внешняя сеть"]
        Internet["Интернет / Upstream Серверы"]
    end

    subgraph EventStream["Event & Analytics Pipeline"]
        Kafka["Apache Kafka (:9092)"]
        Indexer["cache-indexer (:8080)"]
        ClickHouse[("ClickHouse (:8123/:9000)")]
        SQLite[("SQLite (в Lite-режиме)")]
    end

    subgraph SecurityPlane["Security & Intelligence Plane"]
        Alerts["alert-worker (:8090)\nSIEM / Webhooks"]
        ML["ml-worker (:8091)\nUEBA / Phishing / Beacon"]
        ThreatIntel["threat-intel (:8093)\nFeed Collector"]
    end

    subgraph Observability["Мониторинг"]
        Prometheus["Prometheus (:9091)"]
        Grafana["Grafana (:3000)"]
    end

    Browser -->|HTTP / CONNECT / TLS| Proxy
    DNSClient -->|DNS UDP| DNSSink
    Proxy -->|Кеш L2| Redis
    Proxy -->|Forward| Internet
    Proxy -.->|Cache Events| Kafka
    Kafka --> Indexer
    Indexer --> ClickHouse
    Proxy -.->|HTTP event sink| Indexer
    Indexer --> SQLite

    ClickHouse --> Alerts
    ClickHouse --> ML
    ThreatIntel -.-> Proxy

    Proxy --> PromMetrics["/metrics (:9090)"]
    PromMetrics --> Prometheus
    Prometheus --> Grafana
    ClickHouse --> Grafana

Сетевые порты

Компонент	Порт	Протокол	Назначение
proxy (data)	`3128`	TCP	HTTP Forward Proxy / CONNECT
proxy (control)	`9090`	TCP	`/health`, `/ready`, `/metrics`, REST API, `/admin/`
cache-indexer	`8080`	TCP	`/health`, `/metrics`, `/api/search`
alert-worker	`8090`	TCP	`/health`, `/metrics` (обработка инцидентов)
ml-worker	`8091`	TCP	`/health`, `/metrics` (ML-скоринг трафика)
dns-sinkhole	`8092` / `5353`	TCP / UDP	Управление (`8092`) и DNS RPZ-lite резолвер (`5353/udp`)
threat-intel	`8093`	TCP	`/health`, `/metrics`, SOAR/ML API. В Compose не публикуется на хост (`expose`); мутации SOAR требуют `TI_API_TOKEN`
ICP	`3130`	UDP	Иерархический кеш (ICP, opt-in)
Kafka	`9092`	TCP	Брокер событий кеширования и трафика
ClickHouse	`8123` / `9000`	TCP	HTTP interface / Native binary protocol
Prometheus	`9091`	TCP	Сбор и хранение метрик
Grafana	`3000`	TCP	Дашборды аналитики и мониторинга

Подробное описание: Архитектурный обзор и Структура репозитория.

📦 Структура репозитория

bsdm-proxy/
├── proxy/               # Ядро прокси: Forward Proxy, MITM, L1/L2 кеш, ACL, Auth, Admin UI
├── cache-indexer/       # Индексатор событий Kafka → SQLite / ClickHouse, Search API
├── alert-worker/        # Обработка инцидентов безопасности, дедупликация, вебхуки в SIEM
├── ml-worker/           # ML-скоринг трафика: фишинг, C2/beacon детекция, аномалии UEBA
├── dns-sinkhole/        # Sidecar DNS sinkhole / DoH / DoT фильтрация (5353/udp)
├── threat-intel/        # Фоновый коллектор фидов угроз (OpenPhish, PhishStats, URLhaus)
├── bsdm-events/         # Общая библиотека моделей событий (CacheEvent)
├── bsdm-wasm-sdk/       # SDK для создания пользовательских WASM-плагинов
├── admin-console/       # React/TS веб-интерфейс оператора (/admin/)
├── e2e/                 # End-to-End тестовый фреймворк с mock-серверами
├── deploy/              # Конфигурации развёртывания (Compose, systemd, overrides)
├── charts/              # Helm-чарты для развёртывания в Kubernetes
├── grafana/             # Готовые дашборды и алерты Grafana
└── docs/                # Полная каноническая документация проекта

🚀 Быстрый старт

1. Интерактивный установщик

Для автоматической настройки и развёртывания на Linux-системах:

./install.sh

2. Lite Mode (Proxy + SQLite)

Рекомендуется для локальной разработки, быстрого тестирования MITM и отладки без внешних зависимостей (Kafka/ClickHouse не требуются):

# 1. Генерация тестового MITM CA сертификата
./scripts/gen-ca.sh

# 2. Запуск легковесного стека
docker compose -f deploy/compose/docker-compose.lite.yml up -d --build

# 3. Проверка работоспособности
curl http://127.0.0.1:9090/health

# 4. Проверка HTTPS-проксирования через сгенерированный CA
curl --cacert certs/ca.crt -x http://127.0.0.1:3128 https://httpbin.org/get

# 5. Проверка SQLite Search API
curl 'http://127.0.0.1:8080/api/search?limit=5'

Подробнее: Руководство по Lite-режиму.

3. Full Analytics Stack

Развёртывание полного стека с аналитикой, Kafka, ClickHouse и мониторингом:

# 0. Обязательные секреты (стек fail-closed и не стартует без них)
export GRAFANA_ADMIN_PASSWORD='...'
export CONTROL_API_TOKEN="$(openssl rand -hex 32)"
export SEARCH_API_TOKEN="$(openssl rand -hex 32)"
# AUTH_ENABLED=true по умолчанию: подставьте свой файл пользователей
# (scripts/gen-basic-auth-user.sh), иначе смонтируется пример с публичными хешами.
export BASIC_AUTH_USERS_HOST=./config/basic-auth-users.json
# Создайте этот файл с реальными Argon2id-хешами и правами 0600:
# docs/getting-started/pilot-auth.md (раздел Create users file).

# 1. Генерация CA сертификатов
./scripts/gen-ca.sh

# 2. Запуск основного аналитического стека из готовых образов ghcr.io
#    (`up -d --build` вместо pull пересобирает из исходников)
docker compose pull
docker compose up -d

# 3. Просмотр статуса сервисов
docker compose ps

Подключение опциональных профилей:

# Threat Intelligence коллектор
docker compose --profile threat-intel pull && docker compose --profile threat-intel up -d

# Детекция алертов и ML-скоринг
docker compose --profile alerts --profile ml pull && docker compose --profile alerts --profile ml up -d

# DNS Sinkhole входит в базовый стек и запускается обычным up -d

# ICAP антивирусная проверка (ClamAV)
docker compose --profile icap up -d

Подробнее: Руководство по развёртыванию.

4. Пилотный профиль на 100 пользователей (Hybrid Day-1)

Референсный стек Day-1 для пилотной эксплуатации (срок хранения 5 суток, Hybrid Policy DNS → SNI → Selective MITM, без экспериментальных модулей):

Включено в Day-1: Forward Proxy, Selective MITM, DNS Sinkhole, ACL/Auth, Admin Console, ClickHouse (5d TTL), Prometheus/Grafana, MITM Circuit Breaker.
Исключено из Day-1 (Lab / Post-pilot): Agent fleet, AmneziaWG, Threat-Intel block mode (только shadow mode), ML block mode, ICAP/WASM.
Ресурсы (один хост): 12 vCPU, 24 GiB RAM, 200 GB NVMe, 1 Gbit/s.

Готовая конфигурация Compose: deploy/compose/docker-compose.pilot.yml.
Чек-лист оператора и критерии приёмки: Pilot Deployment Guide.

🏭 Production

Промышленная эксплуатация v1.0 ограничена GA-скоупом: forward proxy и CONNECT, Hybrid Policy (selective-mitm / sni) с MITM circuit breaker, L1-кэш, ACL/categorization, Basic auth, control plane + Admin Console (fail-closed), dns-sinkhole, cache-indexer/Search API и метрики. Beta-модули включаются только после отдельной приёмки; lab/frozen-модули (TI enforcement, eBPF/XDP, AmneziaWG, agent fleet, WASM, ICAP, DLP) в prod-профиле выключены — см. матрицу статуса.

Вариант	Артефакт
Docker Compose (один хост)	`deploy/compose/docker-compose.prod.yml` + `prod.env` + Compose `secrets:`
Kubernetes	`charts/bsdm/values-production.yaml` (PSS restricted, NetworkPolicy, PDB)
VM / bare metal	`scripts/install-release.sh` + захарденные юниты `packaging/systemd/`

Образы ghcr.io/onixus/bsdm-* публикуются с SBOM и подписью cosign — проверяйте подпись перед развёртыванием.

Документ	Назначение
Production deployment	Скоуп, сайзинг, CA, секреты, TLS control plane, мониторинг, бэкапы, обновление
Production readiness checklist	Go-live: требование → проверка → доказательство
Runbook	Инциденты: proxy down, breaker, компрометация CA, DNS, аналитика, откат
Upgrade guide 0.9.x → 1.0	Миграция с пилотных версий

🛠 Сборка и Feature Flags

Системные требования

Rust: 1.88+ (Edition 2021), для optional-feature lockfile используйте актуальный stable;
Node.js: 24+ для сборки Admin Console, установка зависимостей через npm ci;
Системные библиотеки (Debian/Ubuntu): libssl-dev, pkg-config, cmake, librdkafka-dev, libclang-dev.

Команды сборки

# Сборка всех компонентов в release-режиме
cargo build --release --workspace

# Сборка легковесного бинарника только с Basic-аутентификацией
cargo build --release -p bsdm-proxy --bin proxy --no-default-features --features auth-basic

Основные Feature Flags

Флаг	По умолчанию	Описание
`kafka`	✅	Асинхронный пайплайн событий в Kafka
`auth-basic`	✅	Basic-аутентификация пользователей
`auth-ldap`	❌	Интеграция с Active Directory / LDAP
`auth-ntlm`	❌	Поддержка NTLM handshake
`auth-kerberos`	❌	Аутентификация Kerberos / SPNEGO
`auth-all`	❌	Включение всех доступных auth-бэкендов
`grpc`	❌	gRPC Control Plane интерфейс
`wasm`	❌	Выполнение пользовательских WASM-плагинов
`acl`	❌	Compatibility feature; runtime ACL управляется `ACL_ENABLED` и доступен в default build
`categorization`	❌	Compatibility feature (включает `acl`); runtime — `CATEGORIZATION_ENABLED`

🧪 Тестирование и качество кода

В проекте настроены строгие требования к качеству и форматированию кода:

# Форматирование и статический анализ (clippy)
make lint
# или вручную:
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

# Запуск юнит- и интеграционных тестов
make test
# или вручную:
cargo test --workspace --all-targets

# Валидация всех локальных ссылок в документации
python3 scripts/check-doc-links.py

# Запуск Smoke и E2E тестов
./scripts/run-smoke-tests.sh
./scripts/run-e2e-tests.sh

# Тренировочные сценарии ротации CA и бэкапов
make rotate-ca-drill
make backup-drill

Подробнее: Руководство по разработке.

📚 Документация

Полный каталог документации доступен в docs/README.md и на GitHub Wiki.

Навигация по направлениям

┌─────────────────────────────────────────────────────────────────────────┐
│                          НАВИГАЦИЯ ПО РОЛЯМ                             │
├───────────────────┬─────────────────────────┬───────────────────────────┤
│    🛠 DevOps /    │      🛡 SecOps /        │      💻 Developer /       │
│     SysAdmin      │          SOC            │        Architect          │
├───────────────────┼─────────────────────────┼───────────────────────────┤
│ • Развёртывание   │ • Матрица статуса       │ • Архитектура             │
│ • Конфигурация    │ • Retro-Search CH       │ • Структура крейтов       │
│ • Мониторинг/Логи │ • Модуль алертов        │ • Разработка и тесты      │
│ • Жизненный цикл  │ • ML Security           │ • Архитектурные ADR       │
│   CA и ротация    │ • Threat Intel          │ • WASM SDK                │
└───────────────────┴─────────────────────────┴───────────────────────────┘

Раздел	Документ	Описание
Общее	Карта документации	Полный индекс всех статей и руководств
	Статус и зрелость функций	Текущий статус готовности компонентов и известные ограничения
	План развития (Roadmap)	Стратегия развития и ключевые этапы
Архитектура	Обзор архитектуры	Потоки данных, компоненты ядра и взаимодействие
	Иерархический кеш	Многоуровневый кеш L1/L2, протоколы ICP/HTCP
	Планирование ресурсов	Формулы расчёта нагрузки, RAM/CPU/диска и масштабирование
Эксплуатация	Production deployment	Промышленное развёртывание v1.0 (GA-скоуп)
	Runbook инцидентов	Действия дежурного при инцидентах и откате
	Параметры конфигурации	Переменные окружения и конфигурационные файлы
	Управление CA и ротация	Генерация, ротация, хранение и аварийный отзыв CA
	Безопасность Control Plane	Защита токенами, сетевая изоляция и биндинг портов
	Резервное копирование	Бэкап и восстановление ClickHouse и сертификатов CA
Функции	Аутентификация	Настройка Basic, LDAP, NTLM, Kerberos и OIDC
	Политики ACL	Синтаксис и правила фильтрации доступа
	DNS Sinkhole	Сайдкар DNS RPZ-lite, фильтрация DoH/DoT
	Threat Intel Collector	Сбор внешних фидов угроз (Shadow Mode, без блокировки)
Аналитика	ClickHouse Analytics	Схема БД, инжест событий и поисковый API
	Оповещения об угрозах	Правила корреляции инцидентов и SIEM-вебхуки
	ML-детекция угроз	Модели детекции фишинга, C2-маяков и UEBA-скоринг
Решения (ADR)	ADR 0005: Policy Agent	Архитектурное решение гибридного локального агента
	ADR 0006: Operator Console	Выбор единой консоли оператора
	ADR 0007: MITM Circuit Breaker	Безопасный selective MITM и bypass при pinning
	ADR 0008: TI Shadow Mode	Threat Intelligence по умолчанию только наблюдает

📄 Лицензия

Проект распространяется под свободной лицензией MIT.
Информация о лицензиях сторонних библиотек и компонентов: NOTICE и Лицензирование зависимостей.

Name		Name	Last commit message	Last commit date
.agents		.agents
.cargo		.cargo
.claude/agents		.claude/agents
.githooks		.githooks
.github		.github
admin-console		admin-console
alert-worker		alert-worker
alertmanager		alertmanager
apex-contract		apex-contract
bpf		bpf
bsdm-events		bsdm-events
bsdm-wasm-sdk		bsdm-wasm-sdk
cache-indexer		cache-indexer
charts/bsdm		charts/bsdm
ci/ebpf-lab		ci/ebpf-lab
config		config
deploy/compose		deploy/compose
dns-sinkhole		dns-sinkhole
docs		docs
e2e		e2e
examples		examples
grafana		grafana
ml-worker		ml-worker
packaging		packaging
prometheus		prometheus
proxy		proxy
scripts		scripts
tests/install		tests/install
threat-intel		threat-intel
.agentignore		.agentignore
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.gitleaksignore		.gitleaksignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
INSTALL.md		INSTALL.md
Jenkinsfile		Jenkinsfile
Jenkinsfile.local		Jenkinsfile.local
Jenkinsfile.publish		Jenkinsfile.publish
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
apex-deploy.json		apex-deploy.json
bsdm-proxy.env		bsdm-proxy.env
deny.toml		deny.toml
docker-compose.yml		docker-compose.yml
install.sh		install.sh
setup.ps1		setup.ps1

Navigation Menu

Repository navigation

About

Repository files navigation

BSDM-Proxy

Why BSDM

Quick start

Performance / reproducible benchmarks

📋 Содержание

✨ Основные возможности

🏛 Архитектура

Сетевые порты

📦 Структура репозитория

🚀 Быстрый старт

1. Интерактивный установщик

2. Lite Mode (Proxy + SQLite)

3. Full Analytics Stack

4. Пилотный профиль на 100 пользователей (Hybrid Day-1)

🏭 Production

🛠 Сборка и Feature Flags

Системные требования

Команды сборки

Основные Feature Flags

🧪 Тестирование и качество кода

📚 Документация

Навигация по направлениям

📄 Лицензия

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

BSDM-Proxy

Why BSDM

Quick start

Performance / reproducible benchmarks

📋 Содержание

✨ Основные возможности

🏛 Архитектура

Сетевые порты

📦 Структура репозитория

🚀 Быстрый старт

1. Интерактивный установщик

2. Lite Mode (Proxy + SQLite)

3. Full Analytics Stack

4. Пилотный профиль на 100 пользователей (Hybrid Day-1)

🏭 Production

🛠 Сборка и Feature Flags

Системные требования

Команды сборки

Основные Feature Flags

🧪 Тестирование и качество кода

📚 Документация

Навигация по направлениям

📄 Лицензия

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages