From 459b2babd1953a175eeb823142ca5a931df5899e Mon Sep 17 00:00:00 2001 From: PTah Date: Fri, 5 Jun 2026 14:38:53 +1000 Subject: [PATCH] docs: split README (RU) and README_en (EN) for GitHub Co-authored-by: Cursor --- README.md | 84 +++++++++++++++++++++++++------------------------ README_en.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 132 insertions(+), 40 deletions(-) create mode 100644 README_en.md diff --git a/README.md b/README.md index d398b85..2327f8b 100644 --- a/README.md +++ b/README.md @@ -2,79 +2,83 @@ Центральная платформа сбора, хранения и отображения событий безопасности с Linux- и Windows-хостов. -**Агенты (отдельные репозитории):** +**English:** [README_en.md](README_en.md) + +## Агенты (отдельные репозитории) | Репозиторий | Назначение | |-------------|------------| -| [ssh-monitor](https://git.kalinamall.ru/PapaTramp/ssh-monitor) | Linux: SSH, sudo, logind, брутфорс, баны | -| [RDP-login-monitor](https://git.kalinamall.ru/PapaTramp/RDP-login-monitor) | Windows: RDP/RDS, RD Gateway, WinRM/PS Remoting, admin share C$/ADMIN$ | +| [ssh-monitor](https://git.kalinamall.ru/PapaTramp/ssh-monitor) | Linux: SSH, sudo, logind, брутфорс, баны IP | +| [RDP-login-monitor](https://git.kalinamall.ru/PapaTramp/RDP-login-monitor) | Windows: RDP/RDS, RD Gateway, WinRM, admin share C$/ADMIN$ | | **security-alert-center** (этот репозиторий) | Ubuntu 24.04: API, БД, UI, оповещения | -## Статус проекта +## Статус -**Prod:** `https://sac.kalinamall.ru` — ingest, UI, JWT, уведомления, RBAC. -**Версия SAC:** `0.7.4`. -**Деплой:** `sudo /opt/sac-deploy.sh` (см. `deploy/sac-deploy.sh`). +**Версия:** `0.8.2` +**Стек:** FastAPI, PostgreSQL, Vue 3, JWT, SSE +**Деплой:** `sudo /opt/sac-deploy.sh` (см. `deploy/sac-deploy.sh`) ## Скриншоты UI -Обзор, журнал событий и проблемы: - | Обзор | События | Проблемы | |-------|---------|----------| | ![Обзор SAC](docs/screenshots/ui-overview.png) | ![События SAC](docs/screenshots/ui-events.png) | ![Проблемы SAC](docs/screenshots/ui-problems.png) | -### Highlights — что мониторится и попадает в SAC +## Что мониторится События приходят от агентов по [контракту ingest](docs/agent-integration.md) (`type`, `severity`, `details`): -- **Linux — [ssh-monitor](https://git.kalinamall.ru/PapaTramp/ssh-monitor):** SSH (успех/неудача), **sudo**, **systemd-logind** (сессии), брутфорс и баны IP (ipset), пороги без бана, ежедневный отчёт, heartbeat. +- **Linux — [ssh-monitor](https://git.kalinamall.ru/PapaTramp/ssh-monitor):** SSH (успех/неудача), **sudo**, **systemd-logind**, брутфорс и баны IP (ipset), пороги без бана, ежедневный отчёт, heartbeat. - **Windows — [RDP-login-monitor](https://git.kalinamall.ru/PapaTramp/RDP-login-monitor):** - - **RDP/RDS** (4624/4625; на РС — только LogonType 10, на сервере — 2/3/10); + - **RDP/RDS** (4624/4625); - **RD Gateway** (302/303), **WinRM / PowerShell Remoting** (Enter-PSSession, ID 91); - - **админ-шары `C$` / `ADMIN$`** (Security **5140**, `smb.admin_share.access` — workstation + server); - - **RDS Shadow Control** (RCM 20506/20507/20510), блокировка учётки **4740** (на заданном КД), ежедневный отчёт, heartbeat. -- **В SAC:** problems (корреляция), Telegram/email/webhook, лимит входа в UI, SSE-дашборд, статус агентов по heartbeat. + - **админ-шары `C$` / `ADMIN$`** (Security **5140**, `smb.admin_share.access`); + - **RDS Shadow Control** (RCM 20506/20507/20510), блокировка учётки **4740**, ежедневный отчёт, heartbeat, **инвентаризация железа** (`agent.inventory`). +- **В SAC:** problems (корреляция), Telegram/email/webhook, лимит входа в UI, SSE-дашборд и live-обновление хостов, статус агентов по heartbeat, карточка хоста с железом. -**Примеры типов:** `ssh.login.*`, `privilege.sudo.command`, `session.logind.*`, `rdp.login.*`, `winrm.session.started`, `smb.admin_share.access`, `rdp.shadow.control.*`, `rdg.connection.*`, `auth.account.locked`, `agent.heartbeat`, `report.daily.*` — [полная таблица §3](docs/agent-integration.md#3-маппинг-уведомлений--типы-событий). +**Примеры типов:** `ssh.login.*`, `privilege.sudo.command`, `rdp.login.*`, `winrm.session.started`, `smb.admin_share.access`, `agent.heartbeat`, `agent.inventory`, `report.daily.*` — [полная таблица](docs/agent-integration.md#3-маппинг-уведомлений--типы-событий). -### Текущее состояние (июнь 2026) +## Возможности платформы -- Реализованы роли `admin`/`monitor`, управление пользователями в UI, проверка активности пользователя по JWT в БД. -- Реализованы события/хосты/problems/dashboard/reports + live SSE на обзорном экране. -- Security hardening (`0.7.2`): защита SPA fallback от path traversal, `DELETE /hosts` только для admin, login rate limit (3 попытки / 15 мин) + Telegram alert, DOMPurify для `report_html`. -- Custom error pages (`0.7.3`): отдельные страницы `401`/`403`/`404`/`429` в UI. - -### Состояние агентов (смежные репозитории) - -| Компонент | Текущее состояние | -|-----------|-------------------| -| `RDP-login-monitor` | `2.0.19-SAC` — RDP/RDS, RD Gateway, WinRM, **5140 C$/ADMIN$**, Shadow Control, 4740; см. Highlights | -| `ssh-monitor` | интеграция через контракт `docs/agent-integration.md` (режимы `off/exclusive/dual/fallback`) | - -**Подготовка сервера Ubuntu:** [docs/install-ubuntu-24.04-native.md](docs/install-ubuntu-24.04-native.md) +- Роли `admin` / `monitor`, управление пользователями в UI, JWT с проверкой активности в БД +- События, хосты, problems, dashboard, отчёты, live SSE +- Оповещения: Telegram, email, webhook; правила problems и cooldown +- Защита SPA, `DELETE /hosts` только для admin, login rate limit, DOMPurify для `report_html` +- Страницы ошибок `401` / `403` / `404` / `429` +- Статистика системы в sidebar (CPU, RAM, диск, latency БД) ## Документация | Документ | Описание | |----------|----------| -| [docs/TZ.md](docs/TZ.md) | Техническое задание (основной документ) | -| [docs/architecture.md](docs/architecture.md) | Архитектура и компоненты | -| [docs/event-schema-v1.json](docs/event-schema-v1.json) | JSON Schema событий v1 | +| [docs/TZ.md](docs/TZ.md) | Техническое задание | +| [docs/architecture.md](docs/architecture.md) | Архитектура | | [docs/agent-integration.md](docs/agent-integration.md) | Интеграция агентов, режим `UseSAC` | -| [docs/work-plan.md](docs/work-plan.md) | План работ (этапы разработки) | -| [docs/roadmap.md](docs/roadmap.md) | Дорожная карта продуктовых фаз | +| [docs/event-schema-v1.json](docs/event-schema-v1.json) | JSON Schema событий v1 | | [docs/install-ubuntu-24.04-native.md](docs/install-ubuntu-24.04-native.md) | **Ubuntu 24.04 — native (основной)** | -| [docs/install-ubuntu-24.04-docker.md](docs/install-ubuntu-24.04-docker.md) | Ubuntu 24.04 — Docker (альтернатива) | -| [docs/ssl-certificate.md](docs/ssl-certificate.md) | Wildcard TLS: куда копировать сертификат | +| [docs/install-ubuntu-24.04-docker.md](docs/install-ubuntu-24.04-docker.md) | Ubuntu 24.04 — Docker | | [docs/deployment.md](docs/deployment.md) | Развёртывание и эксплуатация | -| [docs/workspace-three-repos.md](docs/workspace-three-repos.md) | Multi-root workspace для трёх репо | +| [docs/ssl-certificate.md](docs/ssl-certificate.md) | TLS-сертификат | +| [docs/runbook-ops.md](docs/runbook-ops.md) | Runbook эксплуатации | + +## Быстрый старт (native) + +```bash +git clone https://git.kalinamall.ru/PapaTramp/security-alert-center.git /opt/security-alert-center +# deploy/env.native.example -> config/sac-api.env +cd /opt/security-alert-center/backend +python3 -m venv .venv && .venv/bin/pip install -r requirements.txt +.venv/bin/alembic upgrade head +``` + +Полная инструкция: [docs/install-ubuntu-24.04-native.md](docs/install-ubuntu-24.04-native.md) ## Целевая платформа - **Сервер SAC:** Ubuntu 24.04 LTS -- **Агенты:** существующие скрипты на Linux и Windows (изменения — отдельными задачами в их репозиториях) +- **Агенты:** ssh-monitor (Linux), RDP-login-monitor (Windows) ## Лицензия -Уточняется (TBD). +MIT — см. [LICENSE](LICENSE). +Copyright (c) 2026 Andrey «PapaTramp» Lutsenko. diff --git a/README_en.md b/README_en.md new file mode 100644 index 0000000..62797f6 --- /dev/null +++ b/README_en.md @@ -0,0 +1,88 @@ +# Security Alert Center (SAC) + +Self-hosted hub for collecting, storing, and displaying security events from Linux and Windows hosts. + +**Русский:** [README.md](README.md) + +## Agents (separate repositories) + +| Repository | Role | +|------------|------| +| [ssh-monitor](https://github.com/PTah/ssh-monitor) | Linux: SSH, sudo, logind, brute-force, IP ban | +| [RDP-login-monitor](https://github.com/PTah/RDP-login-monitor) | Windows: RDP/RDS, RD Gateway, WinRM, admin share C$/ADMIN$ | +| **security-alert-center** (this repo) | Ubuntu 24.04: API, database, UI, notifications | + +## Status + +**Version:** `0.8.2` +**Stack:** FastAPI, PostgreSQL, Vue 3, JWT, SSE +**Deploy:** `sudo /opt/sac-deploy.sh` (see `deploy/sac-deploy.sh`) + +## UI screenshots + +| Overview | Events | Problems | +|----------|--------|----------| +| ![SAC dashboard](docs/screenshots/ui-overview.png) | ![SAC events](docs/screenshots/ui-events.png) | ![SAC problems](docs/screenshots/ui-problems.png) | + +## What is monitored + +Agents send events via the [ingest contract](docs/agent-integration.md) (`type`, `severity`, `details`): + +- **Linux — [ssh-monitor](https://github.com/PTah/ssh-monitor):** SSH success/failure, **sudo**, **systemd-logind**, brute-force and IP ban (ipset), thresholds without ban, daily report, heartbeat. +- **Windows — [RDP-login-monitor](https://github.com/PTah/RDP-login-monitor):** + - **RDP/RDS** (4624/4625); + - **RD Gateway** (302/303), **WinRM / PowerShell Remoting** (Enter-PSSession, event ID 91); + - **admin shares `C$` / `ADMIN$`** (Security **5140**, `smb.admin_share.access`); + - **RDS Shadow Control** (RCM 20506/20507/20510), account lockout **4740**, daily report, heartbeat, **hardware inventory** (`agent.inventory`). +- **SAC platform:** problems (correlation), Telegram/email/webhook, UI login rate limit, SSE dashboard and live host updates, agent online/stale by heartbeat, host detail with hardware snapshot. + +**Event type examples:** `ssh.login.*`, `privilege.sudo.command`, `rdp.login.*`, `winrm.session.started`, `smb.admin_share.access`, `agent.heartbeat`, `agent.inventory`, `report.daily.*` — [full mapping](docs/agent-integration.md#3-маппинг-уведомлений--типы-событий). + +## Platform features + +- Roles `admin` / `monitor`, user management in UI, JWT validated against DB +- Events, hosts, problems, dashboard, reports, live SSE +- Notifications: Telegram, email, webhook; problem rules and cooldowns +- SPA hardening, admin-only `DELETE /hosts`, login rate limit, DOMPurify for `report_html` +- Custom error pages: `401` / `403` / `404` / `429` +- Sidebar system stats (CPU, RAM, disk, DB latency) + +## Documentation + +| Document | Description | +|----------|-------------| +| [docs/TZ.md](docs/TZ.md) | Technical specification (Russian) | +| [docs/architecture.md](docs/architecture.md) | Architecture | +| [docs/agent-integration.md](docs/agent-integration.md) | Agent integration (`UseSAC` modes) | +| [docs/event-schema-v1.json](docs/event-schema-v1.json) | Event JSON Schema v1 | +| [docs/install-ubuntu-24.04-native.md](docs/install-ubuntu-24.04-native.md) | **Ubuntu 24.04 native install** | +| [docs/install-ubuntu-24.04-docker.md](docs/install-ubuntu-24.04-docker.md) | Docker alternative | +| [docs/deployment.md](docs/deployment.md) | Deployment and operations | +| [docs/ssl-certificate.md](docs/ssl-certificate.md) | TLS certificate setup | +| [docs/runbook-ops.md](docs/runbook-ops.md) | Operations runbook | + +## Quick start (native) + +```bash +git clone https://github.com/PTah/security-alert-center.git /opt/security-alert-center +# deploy/env.native.example -> config/sac-api.env +cd /opt/security-alert-center/backend +python3 -m venv .venv && .venv/bin/pip install -r requirements.txt +.venv/bin/alembic upgrade head +``` + +Full guide: [docs/install-ubuntu-24.04-native.md](docs/install-ubuntu-24.04-native.md) + +## Target platform + +- **SAC server:** Ubuntu 24.04 LTS +- **Agents:** ssh-monitor (Linux), RDP-login-monitor (Windows) + +## GitHub topics + +`security-monitoring`, `siem`, `incident-response`, `fastapi`, `vue`, `postgresql`, `telegram-bot`, `webhook`, `jwt`, `rbac`, `self-hosted` + +## License + +MIT — see [LICENSE](LICENSE). +Copyright (c) 2026 Andrey "PapaTramp" Lutsenko.