Документация ПО VAHREST

1Общие сведения

VAHREST предназначен для автоматизированного обнаружения уязвимостей в API, оценки соответствия требованиям информационной безопасности и формирования отчётов для регуляторного аудита.

2Описание функциональных характеристик программного обеспечения

Данный раздел содержит полное описание функциональных характеристик программного обеспечения VAHREST в соответствии с требованиями п. 4 «ж» Правил формирования и ведения единого реестра российских программ для электронных вычислительных машин и баз данных.

2.1Назначение

VAHREST — платформа автоматизированного тестирования безопасности API, объединяющая 35 инструментов безопасности в единую систему с централизованным управлением, оркестрацией и унифицированной моделью результатов. Платформа предназначена для:

• Автоматизированного обнаружения уязвимостей в REST API, GraphQL, WebSocket, gRPC
• Проверки соответствия требованиям информационной безопасности (152-ФЗ, 187-ФЗ КИИ, ГОСТ 57580, PCI DSS)
• Комплексного анализа защищённости: DAST, SAST, SCA, фаззинг, сетевое сканирование
• Формирования регуляторных отчётов для аудита и сертификации
• Интеграции в CI/CD для непрерывного контроля безопасности

2.2Оркестрация сканирования

Двухуровневый движок сканирования обеспечивает параллельный запуск инструментов с межинструментным обменом данными. Сканирование проходит через последовательные фазы, внутри каждой фазы инструменты работают параллельно:

Пул из 10 воркеров (настраивается) обрабатывает очередь из 1500 задач с retry-механизмом (до 2 повторов, экспоненциальная задержка). Таймаут на плагин — 30 секунд. Результаты всех инструментов нормализуются в Unified Finding Model.

2.3Инструменты безопасности

Платформа интегрирует 35 инструментов безопасности в 8 категориях. Инструменты запускаются через CLI, Docker-контейнеры, API или как встроенные Go-модули:

Дополнительно: 17 встроенных плагинов обеспечивают 100% покрытие OWASP API Security Top 10 (2023).

2.4Профили сканирования

6 предустановленных профилей позволяют выбрать баланс между скоростью и глубиной проверки:

Профиль express подходит для быстрой проверки в CI/CD, full_security — для полного аудита перед релизом, compliance_ru — для проверки соответствия российским стандартам.

2.5Unified Finding Model

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

Дедупликация осуществляется по SHA256-хешу от комбинации category + url + title + cwe. Если несколько инструментов обнаружили одну и ту же уязвимость, она отображается один раз с указанием всех источников.

2.6Соответствие стандартам

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

Инструменты с сертификатами ФСТЭК: XSpider (серт. №3247), RedCheck (серт. №3172), ScanOVAL, БДУ ФСТЭК.

2.7Управление доступом (RBAC)

Ролевая модель доступа с 5 базовыми ролями:

2.8Аутентификация

• JWT-токены (httpOnly cookies): access (24ч), refresh (7 дней), partial (15 мин для 2FA)
• Двухфакторная аутентификация (2FA): TOTP (Google Authenticator, Authy), Email-код, SMS-код, резервные коды
• SSO/SAML 2.0 и OpenID Connect (OIDC) для корпоративной интеграции
• OAuth 2.0: Google, GitHub, Yandex
• Верификация email и телефона при регистрации
• Сброс пароля через email с одноразовой ссылкой

2.9Мультитенантность

Полная изоляция данных между организациями реализована на уровне базы данных:

• PostgreSQL Row Level Security (RLS) по org_id — каждая организация видит только свои данные
• MinIO bucket prefixes — изоляция файлового хранилища (отчёты, артефакты сканирований)
• Все storage-методы принимают orgID (UUID) — изоляция на уровне API
• Отдельные API-ключи для каждой организации с scope-ограничениями

2.10AI-рекомендации

• Автоматическая генерация рекомендаций по устранению уязвимостей с примерами кода
• AI Triage — приоритизация уязвимостей по контексту приложения
• False Positive Analysis — снижение ложных срабатываний
• Мультипровайдерная LLM-архитектура — выбор на уровне конфигурации

2.11Отчётность

Генерация отчётов в форматах:

Дополнительно: SBOM (Software Bill of Materials) в форматах CycloneDX и SPDX, compliance-отчёты с маппингом на конкретные пункты стандартов (152-ФЗ, PCI DSS, ГОСТ 57580).

2.12Архитектура и стек

Архитектура платформы:

Web UI (Next.js)
  |
  v
REST API + JWT Auth (Go / Chi)
  |
  v
Scan Orchestrator (фазы RECON -> SAST -> ACTIVE_SCAN -> VERIFY -> ENRICH)
  |
  v
Tool Containers (Docker / CLI / API)
  |
  v
Unified Finding Model
  |
  v
PostgreSQL 16 + MinIO (хранение)

Технологический стек:

3Информация, необходимая для установки программного обеспечения

Данный раздел содержит информацию, необходимую для установки программного обеспечения VAHREST. Платформа доступна в двух вариантах: SaaS (облачная) и On-Premise (локальная установка).

3.1SaaS-версия

Облачная версия доступна по адресу app.vahrest.ru. Установка дополнительного ПО не требуется.

1. 1Перейдите на app.vahrest.ru/register и заполните форму регистрации
2. 2Подтвердите email по ссылке из письма
3. 3Настройте двухфакторную аутентификацию (TOTP, Email или SMS) для защиты аккаунта
4. 4Создайте первый проект, указав URL целевого API
5. 5Запустите сканирование, выбрав подходящий профиль

Поддерживаемые браузеры:

3.2On-Premise: Docker Compose

Пошаговая инструкция установки через Docker Compose:

1. 1Убедитесь, что установлены Docker 24+ и Docker Compose 2.20+:

   docker --version    # Docker version 24.0+
   docker compose version  # Docker Compose version v2.20+

2. 2Получите дистрибутив и перейдите в директорию проекта:

   cd vahrest/

3. 3Скопируйте и заполните файл конфигурации:

   cp .env.example .env
   # Отредактируйте .env: укажите JWT_SECRET, DATABASE_URL и другие параметры

4. 4Запустите платформу:

   docker compose up -d --build

5. 5Проверьте работоспособность:

   # Проверка статуса контейнеров
   docker compose ps
   
   # Проверка health-эндпоинта (дождитесь start_period ~120 сек)
   curl -s http://localhost:8080/health
   # Ожидаемый ответ: {"status":"ok"}

Миграции базы данных применяются автоматически при первом запуске. Для HTTPS настройте Nginx с сертификатом Let's Encrypt или используйте корпоративный сертификат.

3.3On-Premise: Kubernetes

Установка через Helm-чарт для Kubernetes 1.27+:

# Добавить репозиторий
helm repo add vahrest https://charts.vahrest.ru
helm repo update

# Установить с параметрами
helm upgrade --install vahrest vahrest/vahrest \
  --namespace vahrest --create-namespace \
  --set global.domain=vahrest.example.com \
  --set postgresql.auth.password=YOUR_DB_PASSWORD \
  --set config.jwtSecret=YOUR_JWT_SECRET \
  --set config.domain=vahrest.example.com

# Проверить статус
kubectl get pods -n vahrest

3.4Системные требования

Поддерживаемые операционные системы:

3.5Переменные окружения

Основные переменные окружения файла .env:

3.6Управление секретами

Для production-окружения рекомендуется использовать HashiCorp Vault для управления секретами вместо хранения их в .env файлах:

• JWT_SECRET, TWO_FACTOR_ENCRYPTION_KEY, IDENTITY_ENCRYPTION_KEY — критические секреты, обязательно через Vault
• OAuth-credentials (Google, GitHub, Yandex) — рекомендуется через Vault
• DATABASE_URL, REDIS_URL — могут быть в .env при наличии сетевой изоляции
• Ротация JWT_SECRET — поддерживается без прерывания сервиса

4Информация, необходимая для эксплуатации программного обеспечения

Данный раздел содержит информацию, необходимую для эксплуатации программного обеспечения VAHREST: порядок работы с платформой, запуск сканирований, анализ результатов, управление командой и интеграция через REST API.

4.1Быстрый старт

1. 1Вход в систему — перейдите на app.vahrest.ru/login и авторизуйтесь с помощью email/пароля или SSO
2. 2Создание проекта — нажмите «Новый проект», укажите название и URL целевого API (например, https://api.example.com)
3. 3Запуск сканирования — выберите профиль express для быстрой проверки (~5 мин) или standard для базового аудита (~30 мин)
4. 4Мониторинг — статус сканирования отображается в реальном времени: прогресс, текущая фаза, найденные уязвимости
5. 5Результаты — просмотрите дашборд с risk score, список уязвимостей с рекомендациями, скачайте отчёт в PDF

4.2Запуск через веб-интерфейс

Веб-интерфейс предоставляет пошаговый мастер создания сканирования (Scan Wizard) из 4 шагов:

1. 1Выбор проекта и целевого URL
2. 2Выбор профиля сканирования (express, standard, full_security и др.)
3. 3Настройка параметров: OpenAPI-спецификация, аутентификация API, прокси
4. 4Подтверждение и запуск

Планировщик позволяет настроить регулярные сканирования по расписанию (ежедневно, еженедельно, ежемесячно) с автоматическими уведомлениями о результатах через Telegram, Slack, Email или Webhook.

4.3Запуск через REST API

Запуск сканирования через REST API с использованием API-ключа организации:

# Создание сканирования через API
curl -X POST https://app.vahrest.ru/api/v1/scans \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PROJECT_UUID",
    "preset": "standard",
    "target_url": "https://api.example.com"
  }'

# Проверка статуса сканирования
curl -s https://app.vahrest.ru/api/v1/scans/SCAN_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# Получение результатов (уязвимости)
curl -s https://app.vahrest.ru/api/v1/scans/SCAN_ID/vulnerabilities \
  -H "Authorization: Bearer YOUR_API_KEY"

# Скачивание отчёта в PDF
curl -s https://app.vahrest.ru/api/v1/scans/SCAN_ID/report?format=pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o report.pdf

4.4Запуск через CI/CD

Пример интеграции с GitHub Actions:

# .github/workflows/security-scan.yml
name: VAHREST Security Scan
on:
  push:
    branches: [main]
  pull_request:

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run VAHREST Scan
        env:
          VAHREST_API_KEY: ${{ secrets.VAHREST_API_KEY }}
          VAHREST_PROJECT_ID: ${{ secrets.VAHREST_PROJECT_ID }}
        run: |
          # Запуск сканирования
          SCAN_ID=$(curl -s -X POST https://app.vahrest.ru/api/v1/scans \
            -H "Authorization: Bearer $VAHREST_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"project_id":"'$VAHREST_PROJECT_ID'","preset":"express"}' \
            | jq -r '.id')

          # Ожидание завершения
          while true; do
            STATUS=$(curl -s https://app.vahrest.ru/api/v1/scans/$SCAN_ID \
              -H "Authorization: Bearer $VAHREST_API_KEY" | jq -r '.status')
            [ "$STATUS" = "DONE" ] || [ "$STATUS" = "FAILED" ] && break
            sleep 30
          done

          # Скачивание JSON-отчёта
          curl -s https://app.vahrest.ru/api/v1/scans/$SCAN_ID/report?format=json \
            -H "Authorization: Bearer $VAHREST_API_KEY" -o results.json

4.5Результаты сканирования

После завершения сканирования доступны:

• Дашборд — Risk Score (0-99), распределение уязвимостей по критичности (Critical/High/Medium/Low/Info), графики трендов по сканированиям
• Список уязвимостей — фильтрация по severity, CWE, OWASP-категории, инструменту-источнику. Сортировка по CVSS-скорингу
• Карточка уязвимости — подробное описание, evidence (запрос/ответ), CWE/OWASP-маппинг, рекомендации по устранению, PoC-запрос (curl), AI-рекомендации
• Compliance-отчёт — маппинг уязвимостей на пункты стандартов (152-ФЗ, PCI DSS, ГОСТ 57580), процент соответствия, чек-лист
• API-топология — интерактивный граф обнаруженных эндпоинтов с визуализацией связей

4.6Экспорт отчётов

Экспорт доступен через веб-интерфейс (кнопка «Скачать отчёт») и через REST API (GET /api/v1/scans/{id}/report?format=pdf|sarif|csv|json).

4.7Управление командой

• Приглашения — отправка приглашений по email с выбором роли (Admin, Security Engineer, Developer, Viewer)
• Роли и разрешения — гранулярная ролевая модель RBAC, назначение ролей на уровне организации
• SSO/SAML — настройка корпоративного SSO для автоматического добавления сотрудников
• Аудит-лог — полная история действий: входы, сканирования, изменения настроек, экспорт в CSV/JSON
• API-ключи — создание и управление ключами организации с scope-ограничениями для CI/CD-интеграций

4.8REST API эндпоинты

Основные эндпоинты REST API (базовый URL: https://app.vahrest.ru/api/v1):

Rate limiting: 1000 запросов/день на API-ключ. Аутентификация: Authorization: Bearer API_KEY. Полная документация API доступна по адресу app.vahrest.ru/api/docs.

4.9Поддержка и SLA

Техническая поддержка:

SLA по времени реагирования:

Обновления выпускаются регулярно и включают исправления и новую функциональность. SaaS-пользователи получают обновления автоматически. Для On-premise:

# Обновление On-Premise (Docker Compose)
docker compose pull
docker compose up -d --build

# Обновление On-Premise (Kubernetes)
helm repo update
helm upgrade vahrest vahrest/vahrest -n vahrest