Corporate Information Systems & Applications

Docs · CISA‑SC

Документация CISA‑SC

Практическое описание: что такое инцидент в системе, какие роли участвуют, какие сущности и статусы рекомендуются, как строить интеграции и как развернуть CISA‑SC в закрытом корпоративном контуре.

Страница продукта API пример

Обзор

CISA‑SC — централизованная система для агрегации, анализа и визуализации инцидентов информационной безопасности. Система объединяет инциденты из различных источников: антивирусных решений, систем обнаружения несанкционированного доступа, а также результаты сканирований из DevSecOps процессов.

Основные возможности

  • Агрегация инцидентов ИБ — сбор данных из различных источников безопасности.
  • Управление инцидентами — полный жизненный цикл: создание, обновление, классификация, приоритизация и отслеживание.
  • Комментарии и история — отслеживание изменений инцидентов с полной историей и комментариями.
  • Предложения по устранению — автоматическая генерация рекомендаций по устранению уязвимостей на основе CVE/CWE.
  • Проекты и рабочие пространства — организация инцидентов по проектам и workspace.
  • API токены проектов — безопасная интеграция через API токены на уровне проектов.
  • Дашборд и аналитика — статистика, графики, тренды, метрики (MTTR, топ CVE/CWE).
  • Корреляция и дедупликация — связывание связанных инцидентов и объединение дублей.
  • Системные настройки — централизованное управление настройками для администраторов.

Реальные кейсы использования

Ниже — практические сценарии, которые соответствуют текущим возможностям и инструкциям проекта.

Кейс 1. CI/CD: Trivy сканирует образы и автоматически загружает отчёт в CISA‑SC

В GitLab CI пайплайне CISA‑SC используется стадия docker-scan, которая запускает Trivy по каждому собранному образу и затем отправляет JSON‑отчёт в коллектор CISA‑SC. В результате в системе появляются инциденты по CVE и формируются рекомендации по устранению на основе CVE/CWE. 

trivy image $DOCKER_IMAGE --no-progress --severity HIGH,CRITICAL --format json --output trivy-report.json

curl -X POST $CISA_SC_API_URL/api/v1/collectors/trivy/upload \
  -H "X-Project-Token: $CISA_SC_PROJECT_TOKEN" \
  -F "file=@trivy-report.json" \
  -F "source_id=2" \
  -F "repository=$CI_PROJECT_NAME" \
  -F "repository_url=$CI_PROJECT_URL"

Практический эффект: безопасность получает единый реестр находок по контейнерным образам, с привязкой к репозиторию и проекту; команды разработки видят динамику (дедупликация/корреляция) и могут планировать remediation.

Кейс 2. CI/CD: параллельная сборка сервисов и скан‑воркеров + Trivy scan на все образы

В pipeline предусмотрены стадии сборки приложения (sc-core, frontend, migrations, news), отдельная база для воркеров (sc-worker-base) и сборка воркеров сканирования (cron, zap, zap-scanner, trivy-scanner). Затем Trivy‑скан проходит по матрице образов.

Такой подход упрощает эксплуатацию: один тег релиза покрывает и приложение, и “инфру” вокруг него.

Кейс 3. On‑prem: включение воркеров сканирования через Kafka (scan-workers profile)

В поставке DELIVERY воркеры (cron/zap/zap-scanner/trivy-scanner) вынесены в профиль scan-workers. Это позволяет включать их только при необходимости. 

# .env
KAFKA_ENABLED=true
INTERNAL_API_TOKEN=<случайная строка>
# (не рекомендуется) ALLOW_INTERNAL_NO_AUTH=true

docker compose -f docker-compose.yaml --profile scan-workers up -d

Практический эффект: SOC/DevSecOps может запускать DAST/Trivy‑задачи асинхронно, не перегружая основной API, и получать результаты централизованно.

Кейс 4. Интеграции экосистемы: единая идентичность + SSO SC→TM

Рекомендуемый продакшен‑сценарий: пользователи входят через CISA‑Auth, а дальше SC и TM используют одну идентичность. Для перехода из SC в TM без повторного логина применим SSO‑редирект (SC выдаёт короткоживущий токен, TM проверяет его общим секретом интеграции и создаёт сессию).

Принцип “один источник правды”: инциденты — в SC; задачи/дефекты/витрины BI потребляют данные из SC по API или событиям. Kafka‑события и webhook’и описываются как следующий этап (в проекте топики событий заданы, но публикация событий пока не включена).

Кейс 5. LLM (Ollama): анализ инцидента и предложения по устранению с контролем затрат

CISA‑SC поддерживает локальные модели через Ollama: анализ инцидента, генерация рекомендаций, а также большие тексты (например, отчёты/регламенты). Важно, что доступ к LLM управляется политиками и лимитами: проектный флаг, роли, cooldown на инцидент, квоты на пользователя, глобальный cap inflight.

  • Project policy: project_settings.llm (enabled/roles/project owner).
  • Ограничения: per‑incident cooldown, per‑user квоты (hour/day), опциональный глобальный inflight cap.
  • Контракты ошибок: 403 при запрете политикой, 429 при лимитах с Retry-After.
POST /api/v1/llm/analyze/incident/{incident_id}?environment=prod

Практический эффект: аналитик получает “первую версию” remediation/summary быстрее, при этом система не уходит в неконтролируемые затраты и защищена от злоупотреблений.

Рекомендуемый сценарий обработки

  • Обнаружение — автоматическое событие из источника (SAST/Trivy/AV/IDS) или ручное создание.
  • Агрегация — сбор и нормализация данных в единый формат.
  • Дедупликация — автоматическое обнаружение и объединение дублирующихся инцидентов.
  • Классификация — авто/ручная классификация (статус, серьезность, тип источника).
  • Приоритизация — определение критичности (Critical/High/Medium/Low/Info).
  • Генерация предложений — рекомендации по устранению на основе CVE/CWE.
  • Корреляция — связывание с другими инцидентами (по CVE/проекту/источнику).
  • Обработка — назначение ответственного, комментарии, расследование.
  • Отслеживание — история изменений, обновление статуса.
  • Разрешение — выполнение предложений/действий, устранение.
  • Закрытие — финализация и архивирование.

Ключевые сущности (минимальная модель)

  • Инцидент — карточка инцидента и его жизненный цикл.
  • Источник инцидента — тип и параметры источника (SAST/Trivy/AV/IDS/ручной ввод).
  • Проект — контур, в рамках которого создаются инциденты и выдаются API токены.
  • Workspace — группировка и организация инцидентов.
  • Комментарии/история — фиксация изменений и обсуждений.

Статусы инцидентов

  • NEW — новый инцидент
  • IN_PROGRESS — в работе
  • RESOLVED — устранён
  • CLOSED — закрыт
  • FALSE_POSITIVE — ложное срабатывание
  • ACCEPTED_RISK — риск принят

Уровни серьёзности

  • CRITICAL, HIGH, MEDIUM, LOW, INFO

Аутентификация и доступ

CISA‑SC выдаёт пользователям JWT после успешного входа. Защищённые API ожидают Bearer‑токен. Подключение к корпоративному каталогу и к IdP настраивается в разделе системных настроек (LDAP / Active Directory и OIDC‑провайдеры, в т.ч. Keycloak). 

Authorization: Bearer <jwt_token>

Опционально: внешний сервис авторизации (если используется в вашей поставке):

AUTH_SERVICE_URL=http://auth:8006
USE_AUTH_SERVICE=true

Интеграция с LDAP / Active Directory

Реализация в CISA‑SC только для чтения из каталога: учётные данные проверяются, атрибуты пользователя считываются, в LDAP/AD ничего не записывается. Параметры подключения задаются в настройках LDAP (сервер, base DN, при необходимости сервисная учётная запись bind, фильтр поиска пользователя, шаблон DN, опционально ограничение по группе) либо через переменные окружения вроде LDAP_SERVER, LDAP_BASE_DN.

Вход выполняется через API POST /api/v1/auth/ldap/login (логин/пароль); при успехе создаётся/обновляется локальный пользователь и выдаются access/refresh токены. Для администрирования предусмотрены проверка конфигурации и синхронизация (см. эндпоинты /api/v1/auth/ldap/* в OpenAPI).

Интеграция с OIDC / Keycloak

Поддерживается любой совместимый OIDC‑провайдер; в типичном контуре это Keycloak. Для каждого провайдера в настройках задаются issuer URL (discovery), client id/client secret, scope (по умолчанию openid profile email). Поток: редирект пользователя на GET /api/v1/auth/oidc/{provider_id}/login → авторизация у IdP → callback /api/v1/auth/oidc/{provider_id}/callback с обменом code на токены, запрос userinfo, создание/обновление пользователя в CISA‑SC и выдача JWT.

Роли в приложении могут выводиться из claims IdP: настраивается маппинг ролей и групп (например, realm_access.roles и groups в userinfo; для групп в Keycloak нужен соответствующий mapper). При нескольких совпадениях выбирается наивысшая роль по иерархии (guest → viewer → manager → admin → super_admin).

Для запросов discovery/token/userinfo используется проверка TLS; для dev/self‑signed можно отключить через OIDC_VERIFY_SSL=false (только для непродакшен‑сред). Публичный URL для redirect_uri должен совпадать с тем, что видит браузер за reverse proxy (учитываются заголовки вроде X-Forwarded-*).

Интеграции

Поддерживаемые источники данных (по текущим инструкциям проекта):

  • SAST — результаты статического анализа безопасности кода (GitLab, SonarQube, Checkmarx).
  • Trivy — результаты сканирования уязвимостей в контейнерах и зависимостях.
  • Kaspersky — инциденты антивирусной защиты и EDR (заявлено/планируется).
  • IDS/IPS — события систем обнаружения вторжений (заявлено/планируется).
  • Ручной ввод — создание инцидентов через UI.

Интеграции с сервисами экосистемы (заявлено): CISA‑Auth, CISA‑TM, CISA‑QA, CISA‑BI.

Интеграция с OpenProject

Связь с OpenProject строится как интеграция «инцидент CISA‑SC ↔ задача (work package) в OpenProject». Подключение выполняется из настроек системы: задаётся базовый URL экземпляра OpenProject, при необходимости OAuth 2.0 (кнопка «Подключить», редирект на IdP OpenProject, callback на стороне CISA‑SC с проверкой state и сохранением токенов). Для callback и ссылок в задачах используется публичный URL приложения (за прокси — корректный redirect_uri и «Base URL приложения»).

Из карточки инцидента можно создать задачу в выбранном проекте (в т.ч. режим «по группе уязвимостей» в одном образе/пакете). Связь хранится в метаданных инцидента; повторное создание для того же незакрытого инцидента блокируется (защита от дублей). Настраивается сопоставление статусов OpenProject → статусы инцидента CISA‑SC; при изменении статуса в OpenProject или в SC выполняется синхронизация (в т.ч. перевод в завершённые статусы при закрытии/авто‑резолве инцидента).

Функциональность OpenProject в продукте зависит от лицензии (отдельная фича); в режиме Trial интеграция недоступна. Внешние вызовы к API обёрнуты в таймауты (см. внутреннюю документацию проекта по таймаутам интеграций).

Интеграция с Jira

Аналогично OpenProject: инцидент CISA‑SC ↔ задача Jira. Поддерживаются два способа доступа к Jira REST API: OAuth 2.0 (редирект на Jira, callback, хранение access/refresh токенов, авто‑обновление access token) и API token (режим Basic: email пользователя + токен; актуально для Jira Cloud). Указывается базовый URL Jira; версия REST API подбирается под Data Center / Cloud.

Из UI создаётся задача в выбранном проекте и типе; в описание передаётся текст инцидента (для REST v2 — plain text). Есть сопоставление статусов Jira → CISA‑SC, синхронизация статуса и исполнителя из Jira в карточку инцидента, комментарии к задаче. При смене статуса инцидента в SC для уже привязанной задачи выполняется обратная синхронизация в Jira (переходы по доступным transitions с учётом маппинга).

Интеграция Jira также зависит от лицензии (фича jira); в Trial недоступна. URL нормализуются при сохранении (схема, лишние слэши), чтобы OAuth и клиент REST обращались к корректному хосту.

API

Ключевые эндпоинты (по текущему описанию проекта):

  • /api/v1/incidents — управление инцидентами
  • /api/v1/incidents/{id}/comments — комментарии
  • /api/v1/incidents/{id}/history — история изменений
  • /api/v1/incidents/{id}/remediation-suggestions — предложения по устранению
  • /api/v1/dashboard — статистика и аналитика
  • /api/v1/projects — проекты и workspace
  • /api/v1/collectors — коллекторы данных
  • /api/v1/incident-sources — источники инцидентов
  • /api/v1/system — системные настройки

После запуска доступна интерактивная документация API:

  • Swagger UI: http://localhost:8030/api/docs
  • ReDoc: http://localhost:8030/api/redoc
  • OpenAPI JSON: http://localhost:8030/api/openapi.json

Развертывание on‑premise (на базе CISA‑SC/DELIVERY)

Пакет поставки предназначен для развёртывания на инфраструктуре заказчика с использованием Docker Compose. Все сервисы запускаются из готовых образов (сборка из исходников не требуется).

Требования

  • Docker 20.10+
  • Docker Compose v2
  • Доступ к registry образов hub.mkskom.ru (образы cisa-project/cisa-sc)

Состав пакета

  • docker-compose.yaml — описание стека
  • .env.example — пример переменных окружения (скопировать в .env и заполнить)
  • nginx/nginx.conf — reverse proxy (входная точка)
  • VERSION — версия поставки (используется как IMAGE_TAG)
  • install.sh — пошаговая установка и запуск (Linux)

Установка через скрипт (Linux, рекомендуется)

chmod +x install.sh
./install.sh

Скрипт делает docker login в hub.mkskom.ru, запрашивает обязательные параметры (POSTGRES_PASSWORD, SECRET_KEY), формирует .env, запускает стек, и выводит URL и учётные данные по умолчанию (admin/admin123).

Быстрый старт вручную

cp .env.example .env
# заполнить POSTGRES_PASSWORD и SECRET_KEY
docker compose -f docker-compose.yaml up -d

Проверка здоровья:

curl http://localhost:8030/health

Опционально: воркеры сканирования (profile scan-workers)

Включают cron, zap, zap-scanner, trivy-scanner и работают через Kafka.

KAFKA_ENABLED=true
INTERNAL_API_TOKEN=<случайная строка>
# (не рекомендуется) ALLOW_INTERNAL_NO_AUTH=true
docker compose -f docker-compose.yaml --profile scan-workers up -d

Лицензирование

Без лицензии приложение работает в режиме Trial. Активация: через LICENSE_KEY в .env или через файл лицензии (LICENSE_FILE + volume).

Безопасность и аудит

  • Аудит: каждое изменение инцидента должно быть трассируемым (кто/когда/что поменял).
  • Разграничение доступа: минимум прав, доступ к артефактам по ролям/делегированиям.
  • Секреты: хранение ключей/токенов вне репозитория, ротация, минимизация сроков.
  • Экспорт: контролируемые форматы, запрет утечек персональных/секретных данных.