Findings API

Просматривайте, читайте и разбирайте алерты из скрипта — по тем же правилам, что и консоль, включая причину для каждого отклонения.

Алерт в консоли — это finding (находка) в API. Для чтения нужны роль VIEWER и область read; для любых изменений — ANALYST и write. См. Ключи API и роли.

Список находок

curl "https://soc.example.com/api/findings?severity=critical&status=open&include_detail=false" \
  -H "X-API-Key: legit_…"

Параметр	Значение
`limit`	1–1 000, по умолчанию 200
`severity`	`info`, `low`, `medium`, `high` или `critical`
`status`	Например, `open`, `confirmed`, `escalated`
`q`	Текстовый поиск
`source_type`	Откуда пришло событие, например `windows_event` или `ssh_monitor`
`team`	`Identity & Access`, `Endpoint & Malware`, `Network & C2`, `Intrusion Response`, `General SOC`
`assigned_to`	`me`, `unassigned` или имя пользователя
`sla_breached`	`true` для алертов с истёкшим сроком разбора
`include_detail`	`false` исключает доказательства, трассу рассуждений ИИ и хронологию. Списки примерно вдвое меньше.

Ответ: {"items": [...], "total": n}.

Что содержит находка

Поле	Значение
`id`, `title`, `summary`	Идентификатор и описание
`severity`, `risk_score`, `confidence_score`	Важность и две оценки от 0 до 100
`status`	На каком этапе разбора
`rule_key`	Правило, которое её подняло, если было
`asset_hostname`, `affected_assets`	Машина и все вовлечённые сущности
`mitre_attack`	ID техник ATT&CK, например `T1110.001`
`occurrence_count`, `last_seen_at`	Сколько раз повторился тот же сигнал и когда последний
`assigned_to`	Кому назначена
`evidence`, `timeline`	События и совпадения правил за ней и что с ней происходило дальше
`recommended_actions`, `ai_summary`	Что делать дальше и объяснение аналитика

Изменение статуса

curl -X PATCH https://soc.example.com/api/findings/<id>/status \
  -H "X-API-Key: legit_…" -H "Content-Type: application/json" \
  -d '{"status": "dismissed", "reason": "Quarterly scan by the IT team", "fp_reason_category": "approved_scan"}'

Действуют те же переходы, что и в консоли (см. Статусы).

Ответ	Почему
`200`	Изменено; возвращается обновлённая находка
`400`	Отклонение без `reason`
`404`	Такой находки в вашем тенанте нет
`422`	Переход запрещён (например, из `resolved`) или неизвестный `status` или `fp_reason_category`

fp_reason_category — одно из known_tool, approved_scan, test_activity, wrong_rule_logic, other. Эскалация открывает расследование по находке, если она ещё не связана ни с одним.

Чтобы назначить находку, отправьте {"action": "assign", "assigned_to": "alice"} на /api/findings/<id>/triage.

Другие эндпоинты

Метод и путь	Что делает
`GET /api/findings/{id}`	Одна находка полностью
`GET /api/findings/{id}/evidence`	Её доказательства
`GET /api/findings/{id}/timeline`	Что с ней происходило, по порядку
`GET /api/findings/{id}/audit`	Каждая смена статуса: кто, из какого, в какой, почему
`GET`, `POST /api/findings/{id}/notes`	Прочитать заметки или добавить: `{"note": "…"}`
`POST /api/findings/{id}/investigate`	Открыть из неё расследование
`GET /api/findings/stats`	Итоги: открытые, подтверждённые, отклонённые и по важности
`GET /api/findings/sla-summary`	Сроки: нарушены, под угрозой, в норме; среднее время реагирования
`GET /api/findings/export/csv`, `/export/xlsx`	Таблица находок
`GET /api/findings/rule-metrics/{rule_key}`	Срабатывания правила, ложные срабатывания и их доля