Version: 1.8

Установка и запуск сервиса AI FP

Сервис AI False-Positive (AI FP) предназначен для AI-анализа результатов сканирований TRON.ASOC с целью выявления ложноположительных срабатываний и повышения точности проверок безопасности.

Сервис устанавливается на локальной инфраструктуре пользователя. Предусмотрено два способа установки:

в составе TRON.ASOC (рекомендуемый);
на отдельной инфраструктуре.

Компоненты сервиса

Сервер vLLM — inference-сервер для LLM с OpenAI-совместимым API (Application Programming Interface) для self-hosted варианта.
Сервис copilot-fp-service — REST API сервис анализа на ложноположительность. Получает задачи от TRON.ASOC, отправляет их в LLM, управляет очередью, возвращает результаты и рекомендации.

Установка в составе TRON.ASOC

Этот способ установки доступен, если сервис AI FP включен в состав TRON.ASOC как опциональный компонент.

Доступен вариант установки на базе Docker Compose или Kubernetes (Helm Chart).

Docker Compose

Чтобы установить сервис на базе Docker Compose, выполните следующие шаги:

В файле .env добавьте профиль fp в переменную COMPOSE_PROFILES:
```
COMPOSE_PROFILES=minio,fp
```
Задайте следующие значения переменных для сервиса core:
```
ASOC_COPILOT_ENABLED=true
FP_SERVICE_API_KEY=<api-key>
FP_SERVICE_BASE_URL=http://fp:8010/api/v1
```
При необходимости переопределите значения переменных для сервиса fp — у них уже есть рабочие значения по умолчанию:
```
FP_API_KEY=<api-key>
FP_LLM_BASE_URL=${FP_LLM_BASE_URL:-https://api.deepseek.com/v1}
FP_LLM_MODEL=${FP_LLM_MODEL:-deepseek-chat}
FP_LLM_API_KEY=<llm-api-key>
```
info
Начиная с версии ИИ спец релиз, сервис fp работает внутри сети Docker Compose: порт наружу не публикуется, отдельный маршрут /fp/ в nginx раскомментировать не требуется.

Kubernetes (Helm Chart)

Чтобы включить сервис AI FP как компонент системы, если TRON.ASOC развернут в Kubernetes, выполните следующие шаги:

Включите сервис флагом в файле values.yaml:
```
features:
  fp: true
```
Задайте секрет:
```
secrets:
  LLM_API_KEY: "<ключ LLM-провайдера>"
```
info
Остальные параметры сервиса fp (LLM_BASE_URL, LLM_MODEL, LLM_TIMEOUT, WORKER_COUNT, QUEUE_SIZE, CLEANUP_INTERVAL, READ_TASK_TTL, UNREAD_TASK_TTL, LOG_LEVEL) уже заданы в конфигурации чарта. При необходимости их можно переопределить в файле values.yaml.
Значения API_KEY и LLM_API_KEY указаны выше в качестве примера. При установке используйте собственные секретные данные.

Установка на отдельной инфраструктуре

Этот способ установки предполагает развертывание компонентов vLLM и copilot-fp-service на отдельной машине с последующим подключением к TRON.ASOC.

Чтобы установить AI FP этим способом, выполните следующие шаги:

Подготовьте инфраструктуру в соответствии с требованиями из раздела Технические требования.

Создайте файл docker-compose.yaml со следующей конфигурацией:

services:
  fp-service:
    image: pcr.tronasoc.ru/asoc/copilot-fp-service:v1.8.0
    ports:
      - "8088:8080"
    environment:
      - SERVER_PORT=8080
      - API_KEY=${API_KEY:-<api-key>}
      - LLM_BASE_URL=http://vllm:8000/v1
      - LLM_MODEL=Qwen/Qwen2.5-7B-Instruct
      - LLM_TIMEOUT=120s
      - WORKER_COUNT=2
      - QUEUE_SIZE=100
      - CLEANUP_INTERVAL=5m
      - READ_TASK_TTL=15m
      - UNREAD_TASK_TTL=1h
      - LOG_LEVEL=info
    depends_on:
      - vllm
    networks:
      - web
  vllm:
    image: vllm/vllm-openai:latest
    ports:
      - "8089:8000"
    volumes:
      - vllm_data:/root/.cache/huggingface
    environment:
      - HF_HOME=/root/.cache/huggingface
    command: >
      --model Qwen/Qwen2.5-7B-Instruct
      --kv-cache-dtype auto
      --gpu-memory-utilization 0.7
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
networks:
  web:
    external: true
volumes:
  vllm_data:

После запуска сервисов установите следующие значения переменных для сервиса asoc-back для интеграции с TRON.ASOC:
```
ASOC_COPILOT_ENABLED: true
FP_SERVICE_API_KEY: <api-key>
FP_SERVICE_BASE_URL: https://fp-service:8080/api/v1/
```

Настройка LLM-провайдера

Сервис AI FP не привязан к определенному LLM-провайдеру и работает с любым OpenAI-совместимым API. Провайдер устанавливается значениями переменных LLM_BASE_URL и LLM_MODEL.

Рекомендуемый вариант настройки — self-hosted vLLM, так как он обеспечивает приватность данных и лучшую производительность. При необходимости провайдер можно заменить, например:

# Ollama
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL=qwen2.5:7b-instruct

# OpenAI API
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini

# Другой OpenAI-совместимый эндпоинт
LLM_BASE_URL=https://your-llm-server/v1
LLM_MODEL=your-model-name

Быстрый запуск через репозиторий

При запуске AI FP этим способом инфраструктура должна соответствовать следующим требованиям:

сервер с NVIDIA GPU (видеопамять от 16 ГБ для модели по умолчанию (Qwen2.5-7B-Instruct)), либо внешний LLM-провайдер;

info

При выборе внешнего LLM-провайдера GPU и доступ к Hugging Face не требуются.

установленные Docker и Docker Compose, драйверы NVIDIA и NVIDIA Container Toolkit;
сетевой доступ к реестру pcr.tronasoc.ru;
доступ к Hugging Face для загрузки модели (только для self-hosted vLLM).

Чтобы запустить сервис этим способом, выполните следующие шаги:

Клонируйте репозиторий с сервисом AI FP и установите его:

git clone https://github.com/ximidev/tron-asoc/copilot-fp-service.git
cd copilot-fp-service
cp .env.example .env

Укажите API-токен для доступа к LLM в переменной API_KEY в файле .env.
Запустите сервисы:
```
make docker-up
```
info
Команда make docker-up запускает следующие сервисы:
- fp-service (порт 8080);
- vllm (порт 8000).
Проверьте состояние сервисов:
```
curl http://localhost:8080/api/v1/health
```

Работа с сервисом AI FP через API

С помощью API-запросов выполняются следующие действия с AI FP:

создавать задачу на FP-анализ;
получать статус задачи;
отменять задачу.

Создание задачи на FP-анализ

Метод: POST /api/v1/check-fp

Запрос

curl -X POST http://localhost:8080/api/v1/check-fp \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "issues": [{
      "issue_id": "VUL-12345",
      "cve": "CVE-2023-1234",
      "cwe": "CWE-79",
      "severity": "HIGH",
      "title": "XSS vulnerability",
      "description": "User input not sanitized",
      "file_path": "src/app.go",
      "line_number": 42,
      "code_snippet": "fmt.Fprintf(w, userInput)",
      "context": {
        "function": "handleRequest",
        "framework": "net/http"
      }
    }]
  }'

Заголовки запроса

Параметр	Значение	Описание
`X-API-Key`	`your-api-key`	Ключ API для аутентификации запроса
`Content-Type`	`application/json`	Формат передаваемых данных (JSON)

Параметры запроса

Параметр	Тип	Описание
`issues`	`array[object]`	Массив объектов с информацией об уязвимости для проверки

Поля объекта issues

Параметр	Тип	Описание
`issue_id`	`string`	Уникальный идентификатор уязвимости в TRON.ASOC
`cve`	`string`	Идентификатор CVE (Common Vulnerabilities and Exposures)
`cwe`	`string`	Идентификатор CWE (Common Weakness Enumeration)
`severity`	`string`	Уровень критичности уязвимости
`title`	`string`	Краткое название уязвимости
`description`	`string`	Подробное описание проблемы
`file_path`	`string`	Путь к файлу, в котором обнаружена уязвимость
`line_number`	`integer`	Номер строки в файле
`code_snippet`	`string`	Фрагмент кода с уязвимостью
`context`	`object`	Дополнительный контекст уязвимости

Поля объекта context

Параметр	Тип	Описание
`function`	`string`	Название функции/метода, где обнаружена уязвимость
`framework`	`string`	Используемый фреймворк или библиотека (например, `net/http`)

Ответ

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2024-11-10T12:00:00Z"
}

Параметры ответа

Параметр	Тип	Описание
`task_id`	`string` (UUID)	Уникальный идентификатор созданной задачи
`status`	`string`	Текущий статус задачи
`created_at`	`string`	Дата и время создания задачи в формате UTC (например, `2024-11-10T12:00:00Z`)

Получение статуса задачи

Метод: GET /api/v1/tasks/{task_id}

Запрос

curl http://localhost:8080/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: your-api-key"

Заголовки запроса

Параметр	Значение	Описание
`X-API-Key`	`your-api-key`	Ключ API для аутентификации запроса

Ответы

Processing (задача в обработке):

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "progress": {
    "total": 1,
    "processed": 0,
    "failed": 0
  },
  "created_at": "2024-11-10T12:00:00Z",
  "updated_at": "2024-11-10T12:00:30Z"
}

Completed (задача завершена):

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "results": [{
    "issue_id": "VUL-12345",
    "is_false_positive": true,
    "probability": 0.92,
    "confidence": "high",
    "explanation": "Input is sanitized by middleware before reaching this code",
    "reasoning_steps": [
      "Analyzed code context",
      "Found sanitization in AuthMiddleware",
      "Confirmed output encoding"
    ]
  }],
  "progress": {"total": 1, "processed": 1, "failed": 0},
  "created_at": "2024-11-10T12:00:00Z",
  "updated_at": "2024-11-10T12:02:15Z",
  "completed_at": "2024-11-10T12:02:15Z"
}

Cancelled (задача отменена):

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled",
  "error": "Task cancelled by user",
  "results": [
    ...
  ],
  "progress": {"total": 5, "processed": 2, "failed": 0},
  "created_at": "2024-11-10T12:00:00Z",
  "updated_at": "2024-11-10T12:01:30Z",
  "completed_at": "2024-11-10T12:01:30Z"
}

Параметры ответа

Параметр	Тип	Описание
`task_id`	`string`	Идентификатор задачи
`status`	`string`	Статус задачи (`processing`, `completed`, `cancelled`)
`progress`	`object`	Прогресс задачи
`created_at`	`string`	Дата и время создания
`updated_at`	`string`	Дата и время последнего обновления
`completed_at`	`string`	Дата и время завершения/отмены
`results`	`array[object]`	Результаты проверки
`error`	`string`	Описание причины отмены

Поля объекта progress

Параметр	Тип	Описание
`total`	`integer`	Всего уязвимостей в задаче
`processed`	`integer`	Обработано успешно
`failed`	`integer`	Обработано с ошибкой

Поля объекта results[i]

Параметр	Тип	Описание
`issue_id`	`string`	Идентификатор уязвимости
`is_false_positive`	`boolean`	`true` — ложное срабатывание, `false` — подтвержденная уязвимость
`probability`	`number`	Вероятность ложного срабатывания
`confidence`	`string`	Уровень уверенности
`explanation`	`string`	Объяснение вердикта
`reasoning_steps`	`array[string]`	Шаги рассуждения модели

Отмена задачи

Метод: DELETE http://localhost:8080/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000

Запрос

curl -X DELETE http://localhost:8080/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: your-api-key"

Заголовки запроса

Параметр	Значение	Обязательный параметр	Описание
`X-API-Key`	`your-api-key`	Да	Ключ API для аутентификации запроса

Ответ

{
  "message": "Task cancelled successfully",
  "task_id": "550e8400-e29b-41d4-a716-446655440000"
}

Параметры ответа

Параметр	Тип	Описание
`message`	`string`	Сообщение о результате операции
`task_id`	`string` (UUID)	Идентификатор отмененной задачи

Компоненты сервиса​

Установка в составе TRON.ASOC​

Docker Compose​

Kubernetes (Helm Chart)​

Установка на отдельной инфраструктуре​

Настройка LLM-провайдера​

Быстрый запуск через репозиторий​

Работа с сервисом AI FP через API​

Создание задачи на FP-анализ​

Запрос​

Заголовки запроса​

Параметры запроса​

Ответ​

Параметры ответа​

Получение статуса задачи​

Запрос​

Заголовки запроса​

Ответы​

Параметры ответа​

Отмена задачи​

Запрос​

Заголовки запроса​

Ответ​

Параметры ответа​

Компоненты сервиса

Установка в составе TRON.ASOC

Docker Compose

Kubernetes (Helm Chart)

Установка на отдельной инфраструктуре

Настройка LLM-провайдера

Быстрый запуск через репозиторий

Работа с сервисом AI FP через API

Создание задачи на FP-анализ

Запрос

Заголовки запроса

Параметры запроса

Ответ

Параметры ответа

Получение статуса задачи

Запрос

Заголовки запроса

Ответы

Параметры ответа

Отмена задачи

Запрос

Заголовки запроса

Ответ

Параметры ответа