🤖 AI Agent Playbook & Safety Protocol (KSP Steel)

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

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

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

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

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

Сначала Read-Only диагностика: Перед изменением или перезапуском любого сервиса проверьте его текущее состояние и статус:
```
systemctl status <service>
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
journalctl -u <service> -n 50 --no-pager
```
Обязательная валидация синтаксиса до перезапуска:
- Nginx: nginx -t
- Docker Compose: docker compose config
- Python: python3 -m py_compile <script.py>
- Ansible: ansible-playbook --syntax-check <playbook.yaml>
Безопасность учетных данных (Zero Plaintext Secrets):
- СТРОГО ЗАПРЕЩЕНО коммитить в Git реальные пароли, SSH-ключи, токены Telegram или базы данных.
- Реальные пароли хранятся ТОЛЬКО в HashiCorp Vault (http://172.16.8.8:8200).
- В Git коммитятся только обезличенные шаблоны (.env.example, config.example.json).

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

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

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

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
ssh root@172.16.8.151   # Почтовый архив MailGuard

Шаг 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. 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-агента

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

Исследование (Research):
- Определите, к какому проекту относится задача.
- Прочитайте локальный README.md соответствующего репозитория.
- Не делайте предположений о путях и портах — проверяйте их через системные конфиги.
Создание плана (Plan):
- Если задача затрагивает боевые сервисы, составьте план изменений.
- Убедитесь, что откат (rollback) возможен в один клик.
Бэкап и внесение изменений (Execute):
- Создайте бэкап затронутых файлов.
- Внесите точечные изменения без переписывания несвязанного функционала.
- Сохраняйте существующие комментарии и структуру кода.
Проверка работоспособности (Verify):
- Проверьте синтаксис конфигов (nginx -t, docker compose config).
- Проверьте статус сервисов (systemctl is-active, docker ps).
- Убедитесь в отсутствии ошибок в логах (journalctl -n 20, docker compose logs --tail=20).
Фиксация в Git (Commit & Push):
- Проверьте git status и git diff.
- Напишите информативное сообщение коммита в формате Conventional Commits (feat(...), fix(...), docs(...)).
- Отправьте коммит в корпоративный Gitea.

11 KiB Raw Blame History