Console API

KYRA MDR 管理控制台的 REST API 端点，提供对所有平台功能的程序化访问。

所有 API 均具有租户感知能力，并通过基于 JWT 的认证强制执行租户隔离。

基础 URL： https://api.seekerslab.com/v1

认证： 在 Authorization 头中使用 Bearer JWT 令牌

1. 连接器管理 API

GET /connectors

列出租户的所有连接器

响应：

{
  "connectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Primary Data Source",
      "type": "siem",
      "status": "healthy",
      "enabled": true,
      "health": {
        "last_check": "2026-02-20T10:30:00Z",
        "message": "Connected, receiving events",
        "consecutive_failures": 0
      },
      "stats": {
        "events_received_total": 125430,
        "events_failed_total": 12,
        "bytes_received_total": 45678900,
        "events_per_second": 42.5,
        "last_event_at": "2026-02-20T10:30:15Z"
      },
      "config": {
        "url": "https://siem.internal.example.com",
        "polling_interval": "30s"
      },
      "created_at": "2026-01-15T08:00:00Z",
      "updated_at": "2026-02-20T10:30:00Z"
    }
  ]
}

GET /connectors/{id}/health

获取连接器的详细健康状态

GET /connectors/{id}/metrics

获取连接器的时间序列指标（用于图表）

查询参数：

from：ISO 8601 时间戳（默认：1 小时前）
to：ISO 8601 时间戳（默认：现在）
interval：聚合间隔（1m、5m、15m、1h）

POST /connectors

创建新连接器

PUT /connectors/{id}

更新连接器配置

DELETE /connectors/{id}

删除连接器

POST /connectors/{id}/test

在保存前测试连接器连接

2. 事件流水线监控 API

GET /pipeline/metrics

获取整体流水线指标

响应：

{
  "timestamp": "2026-02-20T10:30:00Z",
  "stages": {
    "ingestion": {
      "events_total": 1250000,
      "events_per_second": 125.5,
      "active_connectors": 5,
      "healthy_connectors": 5
    },
    "normalization": {
      "events_processed": 1248500,
      "events_failed": 50,
      "success_rate": 99.96,
      "avg_latency_ms": 12.5,
      "p99_latency_ms": 45
    },
    "detection": {
      "events_evaluated": 1248500,
      "rules_matched": 1250,
      "alerts_generated": 856,
      "false_positives": 394,
      "avg_evaluation_time_ms": 8.2
    },
    "enrichment": {
      "alerts_processed": 856,
      "avg_enrichment_time_ms": 150,
      "intel_cache_hit_rate": 78.5
    }
  }
}

GET /pipeline/metrics/timeseries

获取流水线指标的时间序列数据（用于图表）

3. 检测引擎 API

GET /detection/rules

列出检测规则

查询参数：

level：按严重等级过滤（low、medium、high、critical）
enabled：按状态过滤（true/false）
tactic：按 MITRE 战术过滤
technique：按 MITRE 技术过滤
page、size：分页

GET /detection/rules/{id}

获取详细规则信息

GET /detection/rules/{id}/matches

获取规则的近期匹配

PUT /detection/rules/{id}

更新规则（启用/禁用、修改定义）

POST /detection/rules/{id}/test

对示例事件测试规则

GET /detection/metrics

获取检测引擎性能指标

4. 系统健康 API

GET /health

整体系统健康检查

响应：

{
  "status": "healthy",
  "timestamp": "2026-02-20T10:30:00Z",
  "services": {
    "connector-service": {
      "status": "up",
      "replicas": 3,
      "healthy_replicas": 3
    },
    "normalizer-service": {
      "status": "up",
      "replicas": 5,
      "healthy_replicas": 5
    },
    "detection-service": {
      "status": "up",
      "replicas": 5,
      "healthy_replicas": 5
    },
    "enrichment-service": {
      "status": "up",
      "replicas": 3,
      "healthy_replicas": 3
    }
  }
}

5. 告警管理 API

GET /alerts

列出告警

查询参数：

severity：按严重等级过滤
status：open、investigating、resolved、false_positive
from、to：时间范围
page、size：分页

PUT /alerts/{id}

更新告警状态

6. WebSocket API 实时更新

WS /ws/monitoring

用于实时指标更新的 WebSocket 连接

认证： JWT 令牌在查询参数 ?token=xxx 中

消息类型：

服务器推送（每 5 秒）：

{
  "type": "metrics_update",
  "timestamp": "2026-02-20T10:30:00Z",
  "data": {
    "ingestion_rate": 125.5,
    "normalization_latency_p99": 45.0,
    "alerts_last_minute": 8,
    "queue_consumer_lag_total": 1250
  }
}

服务器推送（事件触发）：

{
  "type": "new_alert",
  "timestamp": "2026-02-20T10:30:00Z",
  "data": {
    "alert_id": "alert-123-456",
    "severity": "critical",
    "rule_title": "Mimikatz Detected",
    "host": "DC-01"
  }
}

客户端订阅：

{
  "action": "subscribe",
  "topics": ["metrics", "connector_health", "alerts"]
}

7. 控制台页面

关键控制台页面

仪表板 - 实时指标概览
连接器 - 管理数据源集成
检测规则 - 检测规则管理
告警 - 告警分类和调查
流水线 - 详细的流水线指标和健康状态
系统健康 - 服务状态

8. 客户门户页面

以下页面在面向租户的门户中可用：

门户首页 / SOC 概览 - 告警量、活跃事件、采集健康和检测趋势
告警与分类 - 按严重等级、状态、来源、MITRE 战术和时间范围搜索/过滤
时间线搜索 - 支持结构化查询的完整时间线搜索
资产与暴露 - 每资产活动时间线和关联检测
连接器 - 租户连接器引导入门和健康监控
报告 - 定时合规和高管报告（PDF/CSV 导出）
租户设置 - SSO、角色映射、保留策略、通知渠道

门户 API 要求

租户隔离

每个请求从 JWT 解析 tenant_id 并在查询执行前强制执行租户上下文
内部系统标识符永远不会在 API 响应中暴露

性能 SLO

告警列表页面：30 天查询窗口 p95 < 2.0s
时间线搜索页面：分页结果 p95 < 3.0s
连接器健康页面：刷新间隔 30s，过期读取 <1%

可审计性

记录门户用户操作，包括搜索查询、案例更新和连接器变更
持久化不可变审计跟踪条目，最少保留 1 年

9. 大数据集 API 行为（排序/搜索/过滤）

查询规范标准

sort：逗号分隔的允许字段列表，带方向（示例：detected_at:desc,severity:desc）
cursor：用于下一页的不透明令牌
limit：默认 50，端点最大值强制执行
q：关键字搜索，带页面特定字段范围
filters：用于高级过滤端点的结构化 JSON 表达式

后端要求

所有排序/过滤/搜索操作在服务器端执行
不支持的排序/过滤字段返回 400 INVALID_QUERY_FIELD

性能目标

API 响应时间：< 200ms（p95）
WebSocket 延迟：< 100ms
仪表板刷新率：5 秒
指标保留：90 天