From 46e79ceab1f834b46b391979c2a651c90adaddd7 Mon Sep 17 00:00:00 2001 From: Marker689 Date: Sun, 10 May 2026 04:48:38 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20LLM-=D0=B0=D0=BD=D0=B0=D0=BB=D0=B8=D0=B7=20?= =?UTF-8?q?=D0=B2=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Возможности: новый пункт про LLM - Архитектура: LLM API на диаграмме - Переменные: все 8 новых env-переменных в таблице - Новый раздел LLM-анализ: описание, примеры конфигурации (OpenAI, Groq, Ollama), формат ответа - API: добавить /findings/{id}/analyze, /export endpoints - Структура: constants.py, queries.py, llm.py --- README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 65 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 75f96fe..6702c56 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ - **Поддержка нескольких экосистем** — PyPI, Gem, и другие форматы через Nexus - **REST API** для просмотра результатов сканирования, уязвимостей и статистики - **Веб-интерфейс** с дашбордом, таблицами сканирований и фильтрацией по уязвимостям +- **LLM-анализ** — автоматический разбор каждой уязвимости через OpenAI-совместимые API (опционально, настраивается) - **Дедупликация** по URL и SHA256 — один и тот же пакет сканируется один раз - **Структурированное логирование** в формате JSON с опциональной отправкой в syslog - **Docker Compose** для развёртывания приложения, Nexus и настройки в одном стеке @@ -18,8 +19,9 @@ Nexus ──(webhook)──> GuardDog Nexus ──(REST API)──> Веб-интерфейс │ ├──> GuardDog CLI (сканирование) + ├──> LLM API (анализ уязвимостей) ├──> SQLite (хранилище результатов) - └──> REST API (данные для UI) + └──> REST API (данные для UI + экспорт CSV) ``` ## Быстрый старт @@ -80,6 +82,15 @@ python -m guarddog_nexus.main | `WEBHOOK_SECRET` | _(пусто)_ | Секрет для HMAC-подписи вебхуков | | `SCAN_TIMEOUT_SECONDS` | `300` | Таймаут сканирования одного пакета | | `TEMP_DIR` | `/tmp/guarddog-nexus` | Временная директория для загрузки пакетов | +| `GUARDDOG_BINARY` | `guarddog` | Путь к бинарнику GuardDog | +| `NEXUS_DOWNLOAD_TIMEOUT_SECONDS` | `120` | Таймаут загрузки пакета из Nexus | +| `NEXUS_API_TIMEOUT_SECONDS` | `30` | Таймаут запросов к Nexus REST API | +| `LOG_SYSLOG_FACILITY` | `local0` | Syslog facility (local0–local7) | +| `LLM_ENABLED` | `0` | `1` — включить LLM-анализ уязвимостей | +| `LLM_API_KEY` | _(пусто)_ | API-ключ (OpenAI / Groq / Ollama / etc.) | +| `LLM_API_BASE` | `https://api.openai.com/v1` | Базовый URL OpenAI-совместимого API | +| `LLM_MODEL` | `gpt-4o-mini` | Название модели | +| `LLM_TIMEOUT_SECONDS` | `30` | Таймаут запроса к LLM | ## Настройка Nexus @@ -109,6 +120,7 @@ Nexus отправляет вебхуки при событиях `ASSET` и `CO | GET | `/api/v1/scans` | Список сканирований (пагинация, фильтр `flagged`) | | GET | `/api/v1/scans/stats` | Статистика: общее количество, уязвимые пакеты, топ правил | | GET | `/api/v1/scans/{id}` | Детали конкретного сканирования с результатами | +| GET | `/api/v1/scans/export` | Экспорт сканирований в CSV | ### Пакеты @@ -116,12 +128,14 @@ Nexus отправляет вебхуки при событиях `ASSET` и `CO |-------|------|----------| | GET | `/api/v1/packages` | Список уникальных пакетов (пагинация, фильтр по экосистеме) | | GET | `/api/v1/packages/{name}/{version}` | Все сканирования и уязвимости для пакета | +| GET | `/api/v1/packages/export` | Экспорт пакетов в CSV | ### Уязвимости | Метод | Путь | Описание | |-------|------|----------| | GET | `/api/v1/findings` | Список уязвимостей (фильтр по правилу, severity, scan_id) | +| POST | `/api/v1/findings/{id}/analyze` | Запустить LLM-анализ уязвимости | ### Здоровье @@ -157,10 +171,13 @@ guarddog-nexus/ │ │ ├── scans.py │ │ ├── packages.py │ │ └── findings.py -│ └── web/ # Веб-интерфейс -│ ├── routes.py -│ ├── templates/ # Jinja2-шаблоны -│ └── static/ # CSS, JS +│ ├── web/ # Веб-интерфейс +│ │ ├── routes.py +│ │ ├── templates/ # Jinja2-шаблоны +│ │ └── static/ # CSS, JS +│ ├── constants.py # Централизованные константы +│ ├── queries.py # Общие SQL-запросы +│ └── llm.py # LLM-клиент ├── tests/ # Тесты pytest ├── scripts/ # Вспомогательные скрипты ├── docker-compose.yml # Стек Docker Compose @@ -191,6 +208,49 @@ guarddog-nexus/ - Результаты сканирования хранятся в локальной SQLite-базе - Временные файлы пакетов удаляются после сканирования +## LLM-анализ + +GuardDog Nexus может автоматически анализировать каждую найденную уязвимость через LLM (языковую модель). При включении (`LLM_ENABLED=1`) каждый flagged скан получает AI-разбор: насколько угроза реальна, что делает подозрительный код, рекомендации. + +### Как работает + +1. **Автоматический режим:** после завершения скана с уязвимостями GuardDog Nexus отправляет каждую находку в LLM, сохраняет отчёт в БД и включает его в syslog-событие +2. **Ручной режим:** в веб-интерфейсе на странице сканирования у каждой уязвимости есть кнопка «Analyze with LLM» — нажатие отправляет запрос и показывает вердикт inline + +### Поддерживаемые провайдеры + +Любой OpenAI-совместимый API. Примеры конфигурации: + +```bash +# OpenAI +LLM_ENABLED=1 +LLM_API_KEY=sk-... +LLM_API_BASE=https://api.openai.com/v1 +LLM_MODEL=gpt-4o-mini + +# Groq (быстрее, бесплатный тир) +LLM_ENABLED=1 +LLM_API_KEY=gsk_... +LLM_API_BASE=https://api.groq.com/openai/v1 +LLM_MODEL=llama-3.3-70b-versatile + +# Локальный Ollama +LLM_ENABLED=1 +LLM_API_KEY=ollama +LLM_API_BASE=http://host.docker.internal:11434/v1 +LLM_MODEL=llama3.2 +``` + +### Формат ответа + +LLM возвращает JSON с полями: +- `verdict` — `safe` / `suspicious` / `malicious` +- `summary` — вердикт в одно предложение +- `analysis` — подробный разбор (2–3 абзаца) +- `severity_rating` — `low` / `medium` / `high` / `critical` + +Без LLM (`LLM_ENABLED=0`) весь остальной функционал работает как обычно. + ## Лицензия MIT