**Структура репозитория:**```
home_SOC_suite/
├── Analysts/           — PowerShell analyst scripts
├── Collectors/         — PowerShell collector scripts
├── Dashboard/          — Flask single-page SOC dashboard (Phase 8)
│   ├── app.py              — Flask server, all routes, process detection, DB reads
│   ├── Launch_Dashboard.ps1 — Launcher: checks if Flask running, starts it, opens browser
│   ├── templates/
│   │   └── index.html      — Single-page dashboard layout
│   └── static/
│       ├── style.css       — Dark terminal aesthetic, severity colours, bar graph tiers
│       └── dashboard.js    — All polling, Start Day / End Day sequence, session alert counter
├── Engine/             — Python correlation engine
│   ├── engine.py           — Main loop and orchestration
│   ├── log_parser.py       — Collector log ingestion
│   ├── normalizer.py       — Event normalisation to canonical schema
│   ├── correlator.py       — Correlation rules engine
│   ├── alert_manager.py    — Alert deduplication, flood detection, log writing
│   ├── db.py               — SQLite operations (batch ingest, query, retention)
│   ├── health_db.py        — Heartbeat SQLite store (collector_status, heartbeats tables)
│   ├── config.py           — All thresholds and time windows in one place
│   ├── test_parser.py      — Log parser test suite (7 tests)
│   ├── test_normalizer.py  — Normaliser test suite (32 tests)
│   └── test_correlator.py  — Correlator test suite (135 tests)
└── Documentation/      — Research documents, red team analysis, and dashboard screenshots

---

## Поддерживаемые языки ОС

Steward автоматически определяет правильный путь счетчика производительности ЦП для
следующих языков ОС:

| Язык | Путь счетчика |
|---|---|
| Английский | \Process(*)\% Processor Time |
| Немецкий | \Prozess(*)\Prozessorzeit (%) |
| Французский | \Processus(*)\% temps processeur |
| Испанский | \Proceso(*)\% de tiempo de procesador |
| Итальянский | \Processo(*)\% Tempo processore |
| Португальский | \Processo(*)\% de Tempo do Processador |
| Русский | \Процесс(*)\% загруженности процессора |
| Китайский (упрощ.) | \Process(*)\% Processor Time (обычно английский) |

Чтобы добавить поддержку другого языка, добавьте локализованный путь счетчика в
массив `$PathsToTry` в функции `Get-WorkingCounterPath` в файле `Steward.ps1`.

---

## Документация и исследования

Папка `Documentation/` содержит полную запись исследований и планирования, которая
определила дизайн этого набора. Набор разрабатывался враждебным образом — каждый
уровень планировался против модели угроз до его создания и подвергался стресс-тестированию
в рамках анализа красной команды перед началом следующего уровня.

| Документ | Назначение |
|---|---|
| `home_soc_pre_coding_architecture_guide.pdf` | Структура принятия решений до написания кода. Каноническая модель данных, модель доверия, жизненный цикл базовой линии, стратегия тестирования и возможности межколлекторной проверки. Написан до первой строки кода. |
| `Home_Soc_Architecture_And_Engine_Design.pdf` | Спецификация целевой архитектуры. Проектирование трёхпрограммного движка на Python, схема SQLite, гибридная модель обнаружения (детерминированные правила + оценка рисков), логика повышения уровня оповещений. |
| `HomSOC_Implementation_Guide.pdf` | Поэтапный план сборки. Каркасный код для всех коллекторов, еженедельный график работы, шаблонные шаблоны PowerShell. Руководство по сборке слоя PowerShell. |
| `RedTeam_Analysis_HomSOC_Final.pdf` | Основной справочник красной команды. 11 раундов атаки (Claude + Gemini + симуляции реальных атак), все 26 правил корреляции с полной логикой обнаружения, результаты обхода и смягчения, применённые при сборке. |
| `Home_SOC_Red_Team_Analysis_Pro.pdf` | Архитектурная красная команда. 11 сценариев атак, нацеленных на структурные слабости: отравление базовой линии, обход корреляции, зашумление, подавление коллектора, подделка архивов, инъекция журналов, атаки повторного воспроизведения и злоупотребление идентификацией. |
| `Home_SOC_Red_Team_Whitepaper.pdf` | Краткий обзор. Полная таблица сценариев атак, сравнение систем (базовая vs укреплённая), ключевые архитектурные улучшения и обзор модели обнаружения. |

---

## Ключевые особенности

- **Проектирование через атаку** — 48 правил корреляции, определённых в ходе многораундового
  анализа красной команды до создания движка Python. Логика обнаружения основана на реальных
  цепочках атак, а не на гипотетических сценариях
- **Сбор поведенческой базовой линии** — все коллекторы со временем строят базовые линии,
  что позволяет обнаруживать аномалии относительно наблюдаемой нормы, а не статических правил
- **Мониторинг геолокации** — исходящие соединения, входящие соединения,
  IP-адреса источников аутентификации и DoH-соединения отслеживаются по странам с
  оповещением TELEMETRY_GAP при сбоях геолокации
- **Снятие отпечатков процессов** — каждое сетевое, портовое, процессное и аутентификационное
  событие регистрируется с полным путём процесса, что обнаруживает маскировку и атаки LOLBin
- **Самозащита набора** — Warden отслеживает все сценарии и конфигурации через
  SHA256 FIM с трёхуровневой цепочкой защиты: целостность манифеста, внешняя
  запланированная задача и мониторинг задачи CityGuard
- **Вайтлистинг по принципу нулевого доверия** — все белые списки изначально пусты. 30-дневный
  сбор базовой линии предшествует любым исключениям
- **Логирование с тегом серьёзности** — структурированные записи журнала, разработанные для
  совместимости с парсером Python и будущей интеграции с SIEM
- **7-дневная ротация журналов** — автоматическое архивирование с проверкой SHA256 и
  проверкой целостности цепочки хэшей архива на утренних/вечерних границах через Auditor.ps1
- **Многоязыковая совместимость с Windows** — пути счётчиков производительности
  автоматически определяются для 8 языков ОС при запуске
- **Одностраничная панель SOC** — визуализация в реальном времени на основе Flask, заменяющая
  все отдельные окна PowerShell. Включает лаунчер набора (Start Day / End Day),
  монитор ресурсов Steward в реальном времени, ленту подключений Sentinel, трёхсостоятельные
  точки пульса (зелёный активно / жёлтый не запущен / красный не работает — считываются напрямую
  из JSON-файлов здоровья коллекторов, независимо от состояния движка), карточки событий
  SUSPICIOUS/CRITICAL, прокручиваемую ленту оповещений движка, счётчик оповещений сеанса
  и генерацию еженедельного отчёта одним щелчком. End Day останавливает все коллекторы и
  запускает вечернюю границу Auditor — затем появляется кнопка Shutdown Dashboard для
  корректного завершения процесса Flask. Вкладку браузера необходимо закрыть вручную
  (браузеры не предоставляют API закрытия внешним процессам)

---

## Текущее состояние — Фаза 8 завершена

Движок корреляции на Python создан и работает в реальном времени со всеми 12 коллекторами,
включая SysmonWatcher (события уровня ядра Sysmon).

**Конвейер движка:**

`log_parser.py` → `normalizer.py` → `correlator.py` → `alert_manager.py`

Все этапы приёма, нормализации и корреляции используют пакетные транзакции SQLite.
174 теста в трёх наборах тестов — все проходят.

**Реализованные правила:** 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 16, 17, 18, 21, 22, 41, 42,
43, 44, 45, 46, 47, 48 (Tier 1: однострочные события и Tier 2: оконная корреляция) и Правила 28–39
(события ядра Sysmon через SysmonWatcher). Правила 12, 14, 15, 20 отложены до Tier 4 (требуют
30-дневных данных базовой линии). Правила 23, 24, 25 заблокированы в ожидании специализированных коллекторов.

**Модель обнаружения:** Гибридная — детерминированные правила для чётких цепочек атак,
оценка риска для накопления слабых сигналов, оповещения о видимости для молчания коллектора
и ухудшения качества приёма.

**Следующие фазы:**

| Фаза | Программа | Статус |
|---|---|---|
| 8 | SOC Dashboard — одностраничная визуализация Flask | Завершена |
| 9 | Forensic Engine — расследование после инцидента, хранилище доказательств с защитой от изменений | Запланирована |
| 9 | Forensic Dashboard — сводка результатов, генерация отчётов, навигация по доказательствам | Запланирована |

См. [`roadmap.md`](https://github.com/nate-ryan-7690/home_soc_suite/blob/main/roadmap.md) для полного графика разработки.

---

## Известные шумные оповещения — до настройки

На свежей установке несколько типов оповещений будут срабатывать регулярно, пока не будет
применена машинно-специфичная настройка. Это ожидаемо и не является реальными обнаружениями.

| Коллектор | Оповещение | Причина |
|---|---|---|
| Sentinel | CRITICAL environmental violation | Любое стороннее ПО, установленное вне путей зоны доверия по умолчанию (Windows, Program Files) — облачные клиенты синхронизации, коммуникационные приложения и служебные утилиты, которые устанавливаются в AppData, являются частыми источниками |
| Sentinel | SUSPICIOUS TELEMETRY_GAP | IPv6-петля и локальные адреса ссылки не удаётся геолоцировать — исправлено в текущей сборке |
| SysmonWatcher | SUSPICIOUS/CRITICAL по Правилам 31, 33, 34 | Антивирусное и конечное защитное ПО регулярно выполняет чтения LSASS, чтения сырых дисков и загружает DLL из путей, доступных для записи пользователем, в рамках нормальной работы |
| SysmonWatcher | SUSPICIOUS по Правилу 28 | Инструменты разработки, которые подключаются к процессам браузера для отладки, вызовут срабатывание правила отладчика браузера |
| Bulwark | SUSPICIOUS сбои GeoIP | Соединения в частных и зарезервированных IP-диапазонах не могут быть геолоцированы — вызывают TELEMETRY_GAP до внесения в белый список |
| Bloodhound | SUSPICIOUS обнаружение DGA | Короткоживущие запросы DNS или запросы с малым количеством образцов вызывают проверки энтропии до стабилизации скользящей базовой линии |
| Warden | SUSPICIOUS MANIFEST_MISSING | Манифест FIM отсутствует при первом запуске — создайте с помощью `.\Warden.ps1 -BuildManifest` после начальной настройки |
| Warden | SUSPICIOUS COLLECTOR_DOWN | Коллекторы, ещё не развёрнутые, не имеют файла пульса — ожидается, пока не будет запущен полный набор |
| DoH_Detector | CRITICAL для браузерного DoH | Браузеры, настроенные на использование DNS-over-HTTPS, будут срабатывать, пока не будут добавлены в список разрешённых процессов |

Машинно-специфичная настройка (списки доверенных процессов, белые списки путей, записи о известных безопасных элементах)
применяется локально и не включена в этот репозиторий.

---

## Примечания

- Установите `$RootPath` в каждом скрипте на папку, куда вы установили набор SOC.
  По умолчанию `Desktop\SOC`
- Для скриптов требуется установка политики выполнения PowerShell в Bypass
- Скрипты коллектора требуют прав администратора для полной видимости системы
- Скрипты аналитика запускаются от обычного пользователя
- Геолокация предоставляется бесплатным уровнем ip-api.com
- Журнал событий DNS Client должен быть включён до запуска Bloodhound.ps1:
  `wevtutil sl "Microsoft-Windows-DNS-Client/Operational" /e:true`

---

## Контекст обучения

Создано во время переобучения по специальности Fachinformatiker Anwendungsentwicklung, Германия 2026.
Нацелено на карьеру в киберзащите и анализе угроз.
Создано с помощью ИИ как учебный инструмент. Каждое проектное решение,
сессия отладки и архитектурный выбор были выполнены разработчиком
с полным пониманием лежащих в основе концепций.