# 🤖 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`).

---

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

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

```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)"]
    
    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["Гипервизоры KVM (172.16.15.1)"]
    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
ssh root@172.16.8.151   # Почтовый архив MailGuard
```

### Шаг 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. 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'])"

# 4. Серверы баз данных 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()`, который транслирует внутренние адреса леса домена (`@network.bkv-pvl.kz`) в реальные внешние ящики (`@ksp-steel.kz`), отображая визуально правильный email сотрудника.

### 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>` автоматически подставляет email в поле поиска, раскрывает буквенную ветку сотрудника в алфавитном дереве и открывает досье переписки справа.

### 3. `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 (`ad_security_and_health.yaml`), создания учетных записей (`ad_exim_user_onboarding.yaml`), сброса паролей (`ad_user_password_reset.yaml`), мониторинга гипервизора (`vm-host01_health_check.yaml`), дампов MySQL (`mysql_audit_and_dump.yaml`).
  - Все учетные данные подтягиваются на лету из Vault через lookup-плагин:
    `{{ lookup('community.hashi_vault.hashi_vault', 'secret=servers/data/...:password') }}`

### 4. `KSP-Steel/hashicorp-vault` (Хранилище секретов)
- **Сервер**: `172.16.8.8` (папка `/opt/infra`)
- **Стек**: HashiCorp Vault (`hashicorp/vault:latest`), 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):
    - `servers/data/vm-host01` — пароль гипервизора
    - `servers/data/mysql-main` — пароли основных MySQL
    - `servers/data/mysql-special` — пароли спец-серверов MySQL

---

## 📋 Пошаговый алгоритм выполнения задач для 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.