169 lines
11 KiB
Markdown
169 lines
11 KiB
Markdown
# 🤖 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.
|