Instruction/AI_AGENT_PLAYBOOK.md

🤖 AI Agent Playbook & Safety Protocol (KSP Steel)

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

---

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

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

1. Обязательный бэкап перед изменением любого файла:

   # Перед редактированием ВСЕГДА делайте копию с таймстемпом:
   cp filename filename.bak_$(date +%Y%m%d_%H%M%S)
   

2. Сначала Read-Only диагностика: Перед изменением или перезапуском любого сервиса проверьте его текущее состояние и статус:

   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).

---

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

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

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

export VAULT_ADDR="http://172.16.8.8:8200"
export VAULT_TOKEN="<ВАШ_РООТ_ТОКЕН_VAULT>"

Шаг 2: Извлечение мастер-ключа SSH (Рекомендуется для беспарольного доступа)

В Vault хранится закрытый ключ Ed25519, публичная часть которого прописана в /root/.ssh/authorized_keys на всех серверах:

# Получить закрытый ключ 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):

# 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.