Версия: 1.7

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

Сервис AI FP можно установить одним из следующих способов:

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

Установка и запуск AI FP в составе TRON.ASOC

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

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

Установка на базе Docker Compose

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

Раскомментируйте сервис fp в файле docker-compose.yaml.

Установите следующие значения переменных для сервиса core:

- ASOC_COPILOT_ENABLED=${ASOC_COPILOT_ENABLED:-true}
- FP_SERVICE_API_KEY=<api-key>
- FP_SERVICE_BASE_URL=https://fp:8010/api/v1/

Установите следующие значения переменных для сервиса fp:

- SERVER_PORT=8010
- API_KEY=${FP_API_KEY:-<api-key>}
- LLM_BASE_URL=${FP_LLM_BASE_URL:-https://api.deepseek.com/v1}
- LLM_MODEL=${FP_LLM_MODEL:-deepseek-chat}
- LLM_API_KEY=${FP_LLM_API_KEY:-<llm-api-key>}

Раскомментируйте следующий блок в файле nginx.conf:

# FP service
location /fp/ {
    proxy_pass http://fp:8010/;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;
    client_max_body_size 100m;
}

Установка на базе Kubernetes

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

Измените блок component в файле values.yaml:
```
asoc-ai:
  enabled: true
```
Установите следующие значения переменных в файле configmap.infraconfig:

## FP-Provider
SERVER_PORT: 8010
API_KEY: <api-key>
LLM_BASE_URL: https://api.deepseek.com/v1
LLM_MODEL: deepseek-chat
LLM_API_KEY: <llm-api-key>
LLM_TIMEOUT: 120s
WORKER_COUNT: 2
QUEUE_SIZE: 100
CLEANUP_INTERVAL: 5m
READ_TASK_TTL: 15m
UNREAD_TASK_TTL: 1h
LOG_LEVEL: info
 
## ASOC service
FP_SERVICE_BASE_URL: http://asoc-ai-fp:8010/api/v1
FP_SERVICE_API_KEY: <api-key>
ASOC_COPILOT_ENABLED: true

К сведению

Значения API_KEY и LLM_API_KEY указаны выше в качестве примера. При установке используйте собственные секретные данные.

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

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

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

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

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

services:
  fp-service:
    image: pcr.tronasoc.ru/asoc/fp:v1.4.2
    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-3B-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-3B-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/

Запуск сервиса AI FP

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

Сервис AI FP не привязан к определенному LLM-провайдеру и работает с любым OpenAI-совместимым API (Application Programming Interface). Провайдер устанавливается значениями переменных 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

Быстрый запуск

Ниже представлены технические требования для запуска:

версия Go 1.25 и выше;
установленные Docker и Docker Compose;
NVIDIA GPU (для vLLM) и CPU.

Для запуска сервиса выполните следующие шаги:

Клонируйте репозиторий с сервисом 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
```
К сведению
Команда 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)	Идентификатор отмененной задачи

Установка и запуск AI FP в составе TRON.ASOC​

Установка на базе Docker Compose​

Установка на базе Kubernetes​

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

Запуск сервиса AI FP​

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

Быстрый запуск​

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

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

Запрос​

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

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

Ответ​

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

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

Запрос​

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

Ответы​

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

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

Запрос​

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

Ответ​

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

Установка и запуск AI FP в составе TRON.ASOC

Установка на базе Docker Compose

Установка на базе Kubernetes

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

Запуск сервиса AI FP

Быстрый запуск

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

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

Запрос

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

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

Ответ

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

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

Запрос

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

Ответы

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

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

Запрос

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

Ответ

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