DevSecOps Guardian Agent

Реализована интеллектуальная мульти-агентная система для автоматизации процессов разработки (DevOps), аудита безопасности (SecOps) и управления данными (Data Engineering). Решение построено на базе стека Cloud.ru Evolution, протокола MCP (Model Context Protocol) и оркестратора LangGraph.

1. Как запускать

Для работы требуется установленный Docker и Docker Compose. Проект запускается в полностью изолированной контейнерной среде.

Предварительная настройка

1. Клонирование репозитория: Убедитесь, что все файлы проекта, включая Dockerfile и docker-compose.yml, находятся в корневой директории.

2. Настройка переменных окружения: Создайте файл .env в корне проекта на основе шаблона .env.example. Необходимо заполнить следующие поля:

   • CLOUD_RU_API_KEY — ключ API для доступа к модели (Secret Key).
   • GITHUB_TOKEN — токен (Classic или Fine-grained) для доступа к GitHub API.
   • KAFKA_BOOTSTRAP_SERVERS — адрес брокера Kafka. Для Docker-среды укажите: kafka:9092.
   • TRIVY_PATH — путь к сканеру. Для Docker-среды оставьте значение по умолчанию: trivy.

Запуск системы

Выполните команду сборки и запуска контейнеров:

docker-compose up --build

Процесс инициализации:

1. Сборка образа agent: установка Python 3.11, системных утилит и сканера безопасности Trivy.
2. Запуск инфраструктуры: старт контейнеров Zookeeper и Kafka.
3. Запуск приложения: старт сервера FastAPI внутри контейнера.

Система готова к работе, когда в логах появится сообщение: Uvicorn running on http://0.0.0.0:8000.

Особенности архитектуры

1. Модульный монолит

Проект спроектирован по принципам SOLID с четким разделением слоев ответственности:

• Core Logic (src/core/logic): Слой чистой бизнес-логики. Содержит клиенты для GitHub, Kafka и Security-утилит. Этот слой не зависит от фреймворков агентов или MCP.
• MCP Server (src/mcp_server): Слой адаптации. Оборачивает функции бизнес-логики в инструменты, совместимые со стандартом Model Context Protocol. Это позволяет подключать инструменты к внешним экосистемам (Cloud.ru, Claude Desktop).
• Intelligent Agent (src/agent): Слой оркестрации. Реализует логику принятия решений на базе LangGraph, управляет состоянием диалога и вызывает инструменты.

2. Гибридная интеграция Trivy

Для реализации сканирования контейнеров используется утилита Trivy. Ввиду отсутствия у Trivy публичного API, реализован архитектурный паттерн "CLI-as-API":

• MCP-сервер выступает в роли API-шлюза.
• При вызове инструмента sec_scan_image, сервер запускает процесс Trivy в изолированном окружении контейнера.
• Результат выполнения (STDOUT) перехватывается, парсится и возвращается агенту в виде строго типизированного JSON-объекта.

3. Верификация MCP протокола

Корректность реализации сервера подтверждена тестами.

• В корне проекта находится скрипт test_mcp_protocol.py, эмулирующий подключение клиента по протоколу JSON-RPC.
• Скрипт проверяет процедуру рукопожатия (handshake) и корректность листинга инструментов.
• Сгенерирован файл mcp_tools.json для интеграции с каталогом инструментов Cloud.ru.

2. Техническая реализация

Стек технологий:

• LLM: Cloud.ru Evolution (openai/gpt-oss-120b).
• Оркестрация: LangGraph 1.0 (StateGraph) с поддержкой памяти.
• Протокол: FastMCP.
• API: FastAPI (асинхронный).
• Инфраструктура: Docker, Apache Kafka, Trivy.

Механизм Dynamic Middleware: Внедрена система динамической адаптации системного промпта. Middleware перехватывает запрос пользователя перед передачей в LLM, анализирует переданную роль (developer, security_auditor или data_engineer) и модифицирует инструкции модели. Это позволяет агенту менять стиль общения и строгость проверок в зависимости от контекста задачи.

3. Функциональные возможности

Агент предоставляет 30 инструментов, распределенных по трем доменам.

Домен 1: DevOps Operations (Git)

• Получение сводки по репозиторию (звезды, описание, форки).
• Диагностика CI/CD пайплайнов (GitHub Actions).
• Чтение исходного кода и конфигурационных файлов.
• Анализ истории изменений (Git Blame, Diff).
• Управление задачами (создание Issue, работа с Pull Requests).

Домен 2: Security Operations (SecOps)

• Сканирование Docker-образов на уязвимости (CVE).
• Поиск секретов (API ключи, приватные ключи) в тексте.
• Проверка SSL/TLS сертификатов.
• Сетевая диагностика портов.
• Поиск информации в базе NVD по ID уязвимости.

Домен 3: Data Engineering (Kafka)

• Администрирование топиков (создание, удаление, просмотр метаданных).
• Публикация сообщений в топики.
• Чтение сообщений (Consumer).
• Анализ групп потребителей и состояния кластера.

4. Примеры выполнения

Взаимодействие с агентом осуществляется через HTTP POST запросы к эндпоинту /chat.

Сценарий 1: Расследование инцидента (DevOps)

 curl -X POST "http://localhost:8001/chat" \
 -H "Content-Type: application/json" \
 -d '{
       "query": "Investigate repo tiangolo/typer. 1. Get summary. 2. Check pipeline status. 3. Read pyproject.toml. 4. Run git blame on pyproject.toml to see who touched it last.",
       "role": "devops_lead",
       "mode": "run"
     }'
{"response":"**Repository Summary (tiangolo/typer)**  \n- Stars: 31 k  \n- Forks: 2.5 k  \n- Open issues: 140  \n- 
Description: “Typer, build great CLIs. Easy to code, intuitive to use, and automatically generated documentation.”  
\n\n**Pipeline Status**  \n- No CI/CD runs detected (the repository does not expose a public GitHub Actions workflow list via the current API endpoint).  
\n\n**File `pyproject.toml`**  \n- The file is not present in the default branch of the repository (the project uses `setup.cfg`/`pyproject.toml` is absent).  
\n\n**Git Blame for `pyproject.toml`**  \n- No blame information available because the file does not exist in the repository.  
","meta":{"role":"developer","tools_executed":["t_git_summary","t_git_check_pipeline","t_git_read","t_git_blame","t_git_list_branches","t_git_read","t_git_read","t_git_blame","t_git_summary","t_git_read","t_git_read","t_git_read","t_git_read","t_git_summary","t_git_summary","t_git_check_pipeline","t_git_read","t_git_blame","t_git_list_branches","t_git_summary"]}}%  

Сценарий 2: Аудит безопасности (SecOps)

curl -X POST "http://localhost:8001/chat" \
 -H "Content-Type: application/json" \
 -d '{
       "query": "Scan image alpine:3.12 (it is small). If you find any vulnerabilities, pick the first CVE ID and perform a lookup details for it.",
       "role": "security_auditor",
       "mode": "run"
     }'
{"response":"The scan of **alpine:3.12** reported one vulnerability:
\n\n- **CVE‑2022‑37434** – package **zlib**, severity **CRITICAL**
\n\nA lookup for this CVE returned no additional details from the available database.
","meta":{"role":"developer","tools_executed":["t_sec_scan","t_sec_cve","t_sec_cve"]}}%  

Сценарий 3: Управление данными (Kafka)

 curl -X POST "http://localhost:8001/chat" \
 -H "Content-Type: application/json" \
 -d '{
       "query": "Create a topic named \"test-logs\" and send message \"Hello World\" to it",
       "role": "data_engineer",
       "mode": "run"
     }'
{"response":"The topic **test-logs** has been created and the message **“Hello World”** has been sent successfully.
","meta":{"role":"developer","tools_executed":["t_kf_create","t_kf_send"]}}%