# 🤖 AI Agent Playbook & Safety Protocol (KSP Steel)

> **ВНИМАНИЕ ДЛЯ AI-АГЕНТОВ (LLM / Copilot / Autonomous Agents):**  
> Вы работаете с критической производственной и информационной инфраструктурой промышленного металлургического предприятия ТОО «KSP Steel».  
> Любое некорректное действие может повлиять на мониторинг безопасности завода, работу почты и контроллеров домена.  
> **Ознакомьтесь с этим документом перед выполнением любых задач.**

---

## 🛑 Правило №1: «НЕ СЛОМАЙ НИЧЕГО» (Safety First)

Любые изменения должны подчиняться четырем железным принципам:

1. **Обязательный бэкап перед изменением любого файла**:
   ```bash
   # Перед редактированием ВСЕГДА делайте копию с таймстемпом:
   cp filename filename.bak_$(date +%Y%m%d_%H%M%S)
   ```
2. **Сначала Read-Only диагностика**:
   Перед изменением или перезапуском любого сервиса проверьте его текущее состояние и статус:
   ```bash
   systemctl status <service>
   docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
   journalctl -u <service> -n 50 --no-pager
   ```
3. **Обязательная валидация синтаксиса до перезапуска**:
   - Nginx: `nginx -t`
   - Docker Compose: `docker compose config`
   - Python: `python3 -m py_compile <script.py>`
   - Ansible: `ansible-playbook --syntax-check <playbook.yaml>`
4. **Безопасность учетных данных (Zero Plaintext Secrets)**:
   - **СТРОГО ЗАПРЕЩЕНО** коммитить в Git реальные пароли, SSH-ключи, токены Telegram или базы данных.
   - Реальные пароли хранятся **ТОЛЬКО** в HashiCorp Vault (`http://172.16.8.8:8200`).
   - В Git коммитятся только обезличенные шаблоны (`.env.example`, `config.example.json`).
5. **Регламент работы с критическими серверами (Human-in-the-Loop)**:
   - Контроллеры домена (`DC1`, `DC2`), пограничные маршрутизаторы (`Router`, `IdecoGW`), системы весовых (`VES`, `bptp-srv3`) и гипервизоры являются **критическими узлами жизнеобеспечения завода**.
   - Пароли к этим серверам намеренно **НЕ хранятся в Vault** и не передаются агентам.
   - Если пользователь просит агента помочь с критическими серверами — агент **НЕ выполняет команды напрямую**, а только формулирует безопасные команды и инструкции в чате. **Администратор сам лично копирует и выполняет команды в терминале.**

---

## 🗺️ Архитектурная карта и взаимосвязи проектов

Инфраструктура состоит из взаимосвязанных блоков:

```mermaid
graph TD
    User["Пользователь / Администратор"] --> Web["Инфосистема 2.0 (172.16.8.75:8090)"]
    Web -->|"Интеграция ящиков (?mailbox=)"| MG["MailGuard SOC (172.16.8.151)"]
    Web -->|"Телеметрия & AD"| DC["Active Directory (172.16.8.9 / 19)"]
    
    Mon["Сервер Мониторинга (172.16.8.150)"] -->|"Zabbix / Prometheus"| Web
    Mon -->|"Телеметрия"| MG
    Mon -->|"Метрики узлов"| KVM["Гипервизоры KVM (172.16.15.1/3/4)"]
    Mon -->|"Алерты Webhook"| Syno["Synology NFS (172.16.11.133)"]

    TG["Telegram Чат (KSP INFO)"] --> Bot["ChatOps Bot (172.16.8.8)"]
    Bot -->|"Триггер шаблонов"| Sem["Ansible Semaphore (172.16.8.8:3000)"]
    Sem -->|"Запуск плейбуков"| Playbooks["Ansible Core (172.16.8.8)"]
    
    Playbooks -->|"Динамический запрос паролей"| Vault["HashiCorp Vault (172.16.8.8:8200)"]
    Playbooks -->|"Аудит & Бэкапы"| KVM
    Playbooks -->|"Дампы mysqldump"| DB["Кластер MySQL (192.168.220.x)"]
    Playbooks -->|"Аудит безопасности"| DC
```

---

## 🔑 Как AI-агенту получить доступ к серверам через Vault

Все root-пароли, учетные записи и мастер-ключи хранятся в защищенном виде в **HashiCorp Vault** (`http://172.16.8.8:8200`).

### Шаг 1: Авторизация в Vault
```bash
export VAULT_ADDR="http://172.16.8.8:8200"
export VAULT_TOKEN="<ВАШ_РООТ_ТОКЕН_VAULT>"
```

### Шаг 2: Извлечение мастер-ключа SSH (Рекомендуется для беспарольного доступа)
В Vault хранится закрытый ключ Ed25519, публичная часть которого прописана в `/root/.ssh/authorized_keys` на всех серверах:
```bash
# Получить закрытый ключ SSH и настроить окружение:
mkdir -p ~/.ssh && chmod 700 ~/.ssh
curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/master-ssh-key" \
  | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['private_key'])" > ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519

# Подключение к серверам по SSH без запроса пароля:
ssh root@172.16.8.8     # Сервер автоматизации, Gitea, Vault
ssh root@172.16.8.151   # Почтовый архив MailGuard
ssh root@172.16.8.150   # Сервер мониторинга (Zabbix/Grafana/Prometheus)
```

### Шаг 3: Получение root-паролей серверов из Vault
Если требуется прямой пароль root (например, для локального терминала или Web-консоли Proxmox):
```bash
# 1. Сервер 172.16.8.8 (Gitea / Vault / Semaphore):
curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/server-8-8" \
  | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['password'])"

# 2. Сервер 172.16.8.151 (MailGuard):
curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/server-151" \
  | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['password'])"

# 3. Сервер 172.16.8.150 (Zabbix, Grafana, Prometheus, Portainer):
curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/server-150" \
  | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['password'])"

# 4. KVM гипервизор vm-host01 (172.16.15.1):
curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/vm-host01" \
  | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['password'])"

# 5. Серверы баз данных MySQL:
curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/mysql-main" \
  | python3 -c "import sys, json; d=json.load(sys.stdin)['data']['data']; print('SSH:', d['ssh_password'], 'DB:', d['db_password'])"
```

---

## 📂 Справочник проектов и расположение на серверах

### 1. `KSP-Steel/Infosystem` (Портал предприятия)
- **Сервер**: `172.16.8.75` (Proxmox LXC, папка `/opt/infosystem`)
- **Стек**: Vue 3 (Composition API, TypeScript, Tailwind CSS, Pinia, Lucide icons), FastAPI (Python 3.11), MySQL (порт 3307), Nginx.
- **Особенности**:
  - `v2/frontend`: Современный SPA-интерфейс предприятия.
  - Поддержка быстрого перехода в почтовый архив MailGuard: вызов `resolveMailboxEmail()`.

### 2. `KSP-Steel/mailguard` (Почтовый архив ИБ)
- **Сервер**: `172.16.8.151` (папка `/opt/mailguard`)
- **Стек**: Python 3 worker/ingestion, Meilisearch (полнотекстовый поиск), PostgreSQL, Nginx, Docker.
- **Особенности**:
  - Индексирует 700 000+ входящих и исходящих писем завода.
  - Deep-link механизм: переход по `#mailboxes?mailbox=<email>` автоматически фильтрует дерево и открывает переписку.

### 3. `KSP-Steel/monitoring` (Центральный мониторинг и телеметрия)
- **Сервер**: `172.16.8.150` (репозиторий в `/opt/monitoring-repo`, боевые папки `/opt/zabbix-docker`, `/opt/monitor`, `/opt/loki`)
- **Стек**: Zabbix 7.0 (PostgreSQL 16), Prometheus, Grafana, Grafana Loki, Portainer CE, Alert Bridge.
- **Особенности**:
  - Zabbix Web на порту 80, Grafana на 3000, Prometheus на 9090, Portainer на 8000/9443.
  - Микросервис `grafana-alert-bridge` (порт 9095) принимает алерты от Grafana по вебхуку и складывает журнал в Synology NAS (`/mnt/synology_infosec/log/01_grafana_errors/server-errors.log`).
  - Автоматический скрипт резервного копирования: `/opt/monitoring-repo/scripts/backup_monitoring.sh` (в cron каждую ночь в 03:30).

### 4. `KSP-Steel/ansible` (Автоматизация и ChatOps)
- **Сервер**: `172.16.8.8` (папка `/opt/ansible/playbooks`)
- **Стек**: Ansible Core 2.15+, Semaphore UI (порт 3000), Python Telegram Bot (`semaphore-bot.service`).
- **Особенности**:
  - Плейбуки для аудита безопасности AD, онбординга сотрудников, сброса паролей, мониторинга гипервизоров, дампов MySQL.
  - Все секреты запрашиваются динамически из Vault через `community.hashi_vault.hashi_vault`.

### 5. `KSP-Steel/hashicorp-vault` (Хранилище секретов)
- **Сервер**: `172.16.8.8` (папка `/opt/infra`)
- **Стек**: HashiCorp Vault, Gitea, PostgreSQL, Docker Compose.
- **Особенности**:
  - Точка входа: `http://172.16.8.8:8200`
  - Распечатка (Unseal): `/opt/infra/scripts/unseal_vault.sh`
  - Резервное копирование: `/opt/infra/scripts/backup_vault.sh`
  - Движок `servers/` (KV v2): `server-8-8`, `server-151`, `server-150`, `vm-host01`, `mysql-main`, `mysql-special`, `master-ssh-key`.

---

## 📋 Пошаговый алгоритм выполнения задач для AI-агента

При получении задачи действуйте строго по этапам:

1. **Исследование (Research)**:
   - Определите, к какому проекту относится задача.
   - Прочитайте локальный `README.md` соответствующего репозитория.
   - Не делайте предположений о путях и портах — проверяйте их через системные конфиги.

2. **Создание плана (Plan)**:
   - Если задача затрагивает боевые сервисы, составьте план изменений.
   - Убедитесь, что откат (rollback) возможен в один клик.

3. **Бэкап и внесение изменений (Execute)**:
   - Создайте бэкап затронутых файлов.
   - Внесите точечные изменения без переписывания несвязанного функционала.
   - Сохраняйте существующие комментарии и структуру кода.

4. **Проверка работоспособности (Verify)**:
   - Проверьте синтаксис конфигов (`nginx -t`, `docker compose config`).
   - Проверьте статус сервисов (`systemctl is-active`, `docker ps`).
   - Убедитесь в отсутствии ошибок в логах (`journalctl -n 20`, `docker compose logs --tail=20`).

5. **Фиксация в Git (Commit & Push)**:
   - Проверьте `git status` и `git diff`.
   - Напишите информативное сообщение коммита в формате Conventional Commits (`feat(...)`, `fix(...)`, `docs(...)`).
   - Отправьте коммит в корпоративный Gitea.