46e79ceab1
- Возможности: новый пункт про LLM
- Архитектура: LLM API на диаграмме
- Переменные: все 8 новых env-переменных в таблице
- Новый раздел LLM-анализ: описание, примеры конфигурации
(OpenAI, Groq, Ollama), формат ответа
- API: добавить /findings/{id}/analyze, /export endpoints
- Структура: constants.py, queries.py, llm.py
257 lines
13 KiB
Markdown
257 lines
13 KiB
Markdown
# GuardDog Nexus
|
||
|
||
Интеграция [GuardDog](https://github.com/DataDog GuardDog) (сканер уязвимостей пакетов PyPI) с [Sonatype Nexus Repository Manager]. Автоматически сканирует Python-пакеты, хранящиеся в Nexus, на наличие уязвимостей, вредоносного кода и подозрительных паттернов при каждом обновлении или добавлении пакета.
|
||
|
||
## Возможности
|
||
|
||
- **Автоматическое сканирование** по вебхукам Nexus при создании/обновлении пакетов
|
||
- **Поддержка нескольких экосистем** — PyPI, Gem, и другие форматы через Nexus
|
||
- **REST API** для просмотра результатов сканирования, уязвимостей и статистики
|
||
- **Веб-интерфейс** с дашбордом, таблицами сканирований и фильтрацией по уязвимостям
|
||
- **LLM-анализ** — автоматический разбор каждой уязвимости через OpenAI-совместимые API (опционально, настраивается)
|
||
- **Дедупликация** по URL и SHA256 — один и тот же пакет сканируется один раз
|
||
- **Структурированное логирование** в формате JSON с опциональной отправкой в syslog
|
||
- **Docker Compose** для развёртывания приложения, Nexus и настройки в одном стеке
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
Nexus ──(webhook)──> GuardDog Nexus ──(REST API)──> Веб-интерфейс
|
||
│
|
||
├──> GuardDog CLI (сканирование)
|
||
├──> LLM API (анализ уязвимостей)
|
||
├──> SQLite (хранилище результатов)
|
||
└──> REST API (данные для UI + экспорт CSV)
|
||
```
|
||
|
||
## Быстрый старт
|
||
|
||
### Требования
|
||
|
||
- Docker и Docker Compose
|
||
- Python 3.10+ (для локальной разработки)
|
||
|
||
### Развёртывание в Docker
|
||
|
||
```bash
|
||
# Скопируйте файл конфигурации
|
||
cp .env.example .env
|
||
|
||
# Отредактируйте .env при необходимости
|
||
# NEXUS_PASSWORD=<ваш_пароль_администратора_Nexus>
|
||
|
||
# Запустите стек
|
||
make docker-up
|
||
```
|
||
|
||
После запуска доступны:
|
||
|
||
| Сервис | URL | Порт |
|
||
|--------|-----|------|
|
||
| GuardDog Nexus | http://localhost:8080 | 8080 |
|
||
| Sonatype Nexus | http://localhost:8081 | 8081 |
|
||
|
||
### Локальная разработка
|
||
|
||
```bash
|
||
# Установите зависимости
|
||
make install dev
|
||
|
||
# Настройте переменные окружения
|
||
cp .env.example .env
|
||
export $(cat .env | xargs)
|
||
|
||
# Запустите приложение
|
||
python -m guarddog_nexus.main
|
||
```
|
||
|
||
## Переменные окружения
|
||
|
||
| Переменная | По умолчанию | Описание |
|
||
|------------|-------------|----------|
|
||
| `NEXUS_URL` | `http://localhost:8081` | URL Sonatype Nexus |
|
||
| `NEXUS_USERNAME` | `admin` | Имя пользователя Nexus |
|
||
| `NEXUS_PASSWORD` | _(обязательно)_ | Пароль пользователя Nexus |
|
||
| `NEXUS_REPOSITORIES` | _(пусто)_ | Список репозиториев через запятую |
|
||
| `DATABASE_PATH` | `data/guarddog.db` | Путь к SQLite-базе данных |
|
||
| `HOST` | `0.0.0.0` | Хост для прослушивания |
|
||
| `PORT` | `8080` | Порт для прослушивания |
|
||
| `LOG_LEVEL` | `INFO` | Уровень логирования |
|
||
| `LOG_SYSLOG_HOST` | _(пусто)_ | Хост syslog для отправки логов |
|
||
| `LOG_SYSLOG_PORT` | `514` | Порт syslog |
|
||
| `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
|
||
|
||
### Создание репозитория
|
||
|
||
1. Убедитесь, что в Nexus создан репозиторий `pypi-proxy` (прокси на `https://pypi.org`)
|
||
2. Настройте вебхук Nexus для отправки событий на `http://<guarddog-nexus>:8080/webhooks/nexus`
|
||
3. Используйте `scripts/setup-nexus.sh` для автоматической настройки (требует `curl`)
|
||
|
||
### Вебхуки
|
||
|
||
Nexus отправляет вебхуки при событиях `ASSET` и `COMPONENT`. GuardDog Nexus поддерживает:
|
||
|
||
- **CREATED** — новое событие при создании пакета
|
||
- **UPDATED** — событие при обновлении пакета
|
||
|
||
Для валидации вебхуков установите `WEBHOOK_SECRET` — подпись проверяется через HMAC-SHA256.
|
||
|
||
> **Примечание:** Вебхуки доступны в Nexus Pro. В Nexus Repository Manager 3 Community Edition настройка вебхуков может потребовать дополнительных плагинов.
|
||
|
||
## REST API
|
||
|
||
### Сканирования
|
||
|
||
| Метод | Путь | Описание |
|
||
|-------|------|----------|
|
||
| GET | `/api/v1/scans` | Список сканирований (пагинация, фильтр `flagged`) |
|
||
| GET | `/api/v1/scans/stats` | Статистика: общее количество, уязвимые пакеты, топ правил |
|
||
| GET | `/api/v1/scans/{id}` | Детали конкретного сканирования с результатами |
|
||
| GET | `/api/v1/scans/export` | Экспорт сканирований в CSV |
|
||
|
||
### Пакеты
|
||
|
||
| Метод | Путь | Описание |
|
||
|-------|------|----------|
|
||
| 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-анализ уязвимости |
|
||
|
||
### Здоровье
|
||
|
||
| Метод | Путь | Описание |
|
||
|-------|------|----------|
|
||
| GET | `/health` | Проверка работоспособности |
|
||
|
||
## Веб-интерфейс
|
||
|
||
| Страница | URL | Описание |
|
||
|----------|-----|----------|
|
||
| Дашборд | `/` | Статистика, графики, топ уязвимых пакетов |
|
||
| Сканирования | `/scans` | Таблица всех сканирований с фильтрацией |
|
||
| Детали сканирования | `/scans/{id}` | Результаты одного сканирования |
|
||
| Пакеты | `/packages` | Таблица уникальных пакетов |
|
||
| Детали пакета | `/packages/{name}/{version}` | История сканирований и уязвимости пакета |
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
guarddog-nexus/
|
||
├── guarddog_nexus/ # Основной пакет
|
||
│ ├── main.py # Точка входа FastAPI
|
||
│ ├── config.py # Конфигурация из переменных окружения
|
||
│ ├── database.py # Async SQLAlchemy + aiosqlite
|
||
│ ├── models.py # ORM-модели (Scan, Finding)
|
||
│ ├── logging_setup.py # JSON-логирование + syslog
|
||
│ ├── harvester.py # Пайплайн: загрузка → сканирование → сохранение
|
||
│ ├── scanner.py # Интеграция с GuardDog CLI
|
||
│ ├── nexus_client.py # HTTP-клиент для Nexus REST API
|
||
│ ├── webhooks.py # Приём вебхуков Nexus
|
||
│ ├── api/ # REST API (JSON)
|
||
│ │ ├── scans.py
|
||
│ │ ├── packages.py
|
||
│ │ └── findings.py
|
||
│ ├── web/ # Веб-интерфейс
|
||
│ │ ├── routes.py
|
||
│ │ ├── templates/ # Jinja2-шаблоны
|
||
│ │ └── static/ # CSS, JS
|
||
│ ├── constants.py # Централизованные константы
|
||
│ ├── queries.py # Общие SQL-запросы
|
||
│ └── llm.py # LLM-клиент
|
||
├── tests/ # Тесты pytest
|
||
├── scripts/ # Вспомогательные скрипты
|
||
├── docker-compose.yml # Стек Docker Compose
|
||
├── Dockerfile # Образ приложения
|
||
└── pyproject.toml # Зависимости и настройки
|
||
```
|
||
|
||
## Команды Makefile
|
||
|
||
| Команда | Описание |
|
||
|---------|----------|
|
||
| `make install` | Установка зависимостей проекта |
|
||
| `make dev` | Установка зависимостей для разработки |
|
||
| `make test` | Запуск тестов |
|
||
| `make lint` | Проверка кода через Ruff |
|
||
| `make format` | Форматирование кода через Ruff |
|
||
| `make typecheck` | Проверка типов через mypy |
|
||
| `make docker-build` | Сборка Docker-образа |
|
||
| `make docker-up` | Запуск стека Docker Compose |
|
||
| `make docker-down` | Остановка стека с удалением данных |
|
||
| `make docker-logs` | Просмотр логов стека |
|
||
| `make clean` | Очистка артефактов сборки |
|
||
|
||
## Безопасность
|
||
|
||
- Вебхуки поддерживают HMAC-SHA256 подпись через `WEBHOOK_SECRET`
|
||
- Nexus-клиент использует BasicAuth для аутентификации
|
||
- Результаты сканирования хранятся в локальной 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
|