본문으로 건너뛰기
KYRA MDR KYRA MDR Docs

Console API

KYRA MDR 관리 콘솔용 REST API 엔드포인트로, 모든 플랫폼 기능에 대한 프로그래밍 방식의 접근을 제공합니다.

모든 API는 tenant 인식 방식이며 JWT 기반 인증을 통해 tenant 격리를 적용합니다.

Base URL: https://api.kyramdr.com/v1

인증: Authorization 헤더에 Bearer JWT 토큰

1. Connector 관리 API

GET /connectors

tenant의 모든 connector 목록 조회

응답:

{
  "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

connector의 상세 상태 정보 조회

응답:

{
  "connector_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "healthy",
  "last_check": "2026-02-20T10:30:00Z",
  "checks": [
    {
      "type": "connectivity",
      "status": "pass",
      "message": "Connection established",
      "latency_ms": 45
    },
    {
      "type": "authentication",
      "status": "pass",
      "message": "API key valid"
    },
    {
      "type": "data_flow",
      "status": "pass",
      "message": "Receiving events",
      "events_in_last_minute": 85
    }
  ],
  "history": [
    {
      "timestamp": "2026-02-20T10:30:00Z",
      "status": "healthy"
    },
    {
      "timestamp": "2026-02-20T10:25:00Z",
      "status": "healthy"
    }
  ]
}

GET /connectors/{id}/metrics

connector의 시계열 메트릭 조회 (차트용)

쿼리 파라미터:

  • from: ISO 8601 타임스탬프 (기본값: 1시간 전)
  • to: ISO 8601 타임스탬프 (기본값: 현재)
  • interval: 집계 간격 (1m, 5m, 15m, 1h)

응답:

{
  "connector_id": "550e8400-e29b-41d4-a716-446655440000",
  "metrics": {
    "events_received": [
      {"timestamp": "2026-02-20T10:00:00Z", "value": 2550},
      {"timestamp": "2026-02-20T10:05:00Z", "value": 2680},
      {"timestamp": "2026-02-20T10:10:00Z", "value": 2420}
    ],
    "events_failed": [
      {"timestamp": "2026-02-20T10:00:00Z", "value": 2},
      {"timestamp": "2026-02-20T10:05:00Z", "value": 1},
      {"timestamp": "2026-02-20T10:10:00Z", "value": 0}
    ],
    "throughput_eps": [
      {"timestamp": "2026-02-20T10:00:00Z", "value": 42.5},
      {"timestamp": "2026-02-20T10:05:00Z", "value": 44.7},
      {"timestamp": "2026-02-20T10:10:00Z", "value": 40.3}
    ]
  }
}

POST /connectors

새 connector 생성

요청:

{
  "name": "Production CrowdStrike",
  "type": "crowdstrike",
  "enabled": true,
  "config": {
    "client_id": "abc123...",
    "client_secret": "secret...",
    "base_url": "https://api.crowdstrike.com",
    "polling_interval": "30s"
  }
}

PUT /connectors/{id}

connector 설정 업데이트

DELETE /connectors/{id}

connector 삭제

POST /connectors/{id}/test

저장 전 connector 연결 테스트

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
    }
  },
  "queue": {
    "topics": [
      {
        "name": "normalized-events",
        "consumer_lag": 1250,
        "messages_per_second": 125.5
      },
      {
        "name": "alerts",
        "consumer_lag": 45,
        "messages_per_second": 1.4
      }
    ]
  }
}

GET /pipeline/metrics/timeseries

파이프라인 메트릭의 시계열 데이터 조회 (차트용)

쿼리 파라미터:

  • from, to, interval (connector 메트릭과 동일)

응답:

{
  "ingestion_rate": [
    {"timestamp": "2026-02-20T10:00:00Z", "value": 120.5},
    {"timestamp": "2026-02-20T10:05:00Z", "value": 125.2}
  ],
  "normalization_latency": [
    {"timestamp": "2026-02-20T10:00:00Z", "p50": 10.2, "p95": 35.5, "p99": 48.2},
    {"timestamp": "2026-02-20T10:05:00Z", "p50": 12.5, "p95": 38.1, "p99": 45.0}
  ],
  "alerts_generated": [
    {"timestamp": "2026-02-20T10:00:00Z", "value": 45},
    {"timestamp": "2026-02-20T10:05:00Z", "value": 52}
  ],
  "queue_consumer_lag": {
    "normalized-events": [
      {"timestamp": "2026-02-20T10:00:00Z", "value": 1500},
      {"timestamp": "2026-02-20T10:05:00Z", "value": 1250}
    ]
  }
}

3. 탐지 엔진 API

GET /detection/rules

탐지 규칙 목록 조회

쿼리 파라미터:

  • level: 심각도별 필터 (low, medium, high, critical)
  • enabled: 상태별 필터 (true/false)
  • tactic: MITRE 전술별 필터
  • technique: MITRE 기법별 필터
  • page, size: 페이지네이션

응답:

{
  "rules": [
    {
      "id": "fb843269-508c-4b76-8b8d-88679db22ce7",
      "title": "Suspicious Encoded PowerShell Command",
      "level": "high",
      "status": "stable",
      "enabled": true,
      "logsource": {
        "category": "process_creation",
        "product": "windows"
      },
      "mitre": {
        "tactics": ["execution"],
        "techniques": ["T1059.001"]
      },
      "stats": {
        "evaluations_total": 125000,
        "matches_total": 45,
        "true_positives": 38,
        "false_positives": 7,
        "match_rate": 0.036
      },
      "created_at": "2026-01-15T08:00:00Z",
      "updated_at": "2026-02-10T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 50,
    "total": 450
  }
}

GET /detection/rules/{id}

상세 규칙 정보 조회

응답:

{
  "id": "fb843269-508c-4b76-8b8d-88679db22ce7",
  "title": "Suspicious Encoded PowerShell Command",
  "description": "Detects suspicious PowerShell command with base64 encoded arguments",
  "level": "high",
  "status": "stable",
  "author": "Florian Roth",
  "date": "2018-03-05",
  "modified": "2023-01-05",
  "logsource": {
    "category": "process_creation",
    "product": "windows"
  },
  "mitre": {
    "tactics": ["execution"],
    "techniques": ["T1059.001"]
  },
  "false_positives": ["Unknown"],
  "references": [
    "https://attack.mitre.org/techniques/T1059/001/"
  ],
  "tags": ["attack.execution", "attack.t1059.001"],
  "enabled": true,
  "stats": {
    "evaluations_last_24h": 8500,
    "matches_last_24h": 3,
    "true_positives_last_7d": 12,
    "false_positives_last_7d": 2
  }
}

GET /detection/rules/{id}/matches

규칙의 최근 일치 항목 조회

쿼리 파라미터:

  • from, to: 시간 범위
  • page, size: 페이지네이션

응답:

{
  "rule_id": "fb843269-508c-4b76-8b8d-88679db22ce7",
  "matches": [
    {
      "match_id": "alert-123-456",
      "timestamp": "2026-02-20T10:15:30Z",
      "event": {
        "process_name": "powershell.exe",
        "command_line": "powershell.exe -enc SQBFAFgA...",
        "user": "DESKTOP-ABC\\john",
        "host": "DESKTOP-ABC"
      },
      "verdict": "true_positive",
      "reviewed_by": "analyst@example.com",
      "reviewed_at": "2026-02-20T10:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 45
  }
}

PUT /detection/rules/{id}

규칙 업데이트 (활성화/비활성화, 정의 수정)

POST /detection/rules/{id}/test

샘플 이벤트에 대해 규칙 테스트

요청:

{
  "events": [
    {
      "process_name": "powershell.exe",
      "command_line": "powershell.exe -enc SQBFAFgA..."
    }
  ]
}

응답:

{
  "results": [
    {
      "event_index": 0,
      "matched": true,
      "matched_conditions": ["selection"]
    }
  ]
}

GET /detection/metrics

탐지 엔진 성능 메트릭 조회

응답:

{
  "rules_loaded": 450,
  "rules_enabled": 420,
  "evaluations_per_second": 125.5,
  "avg_evaluation_time_ms": 8.2,
  "p99_evaluation_time_ms": 25.5,
  "top_alerting_rules": [
    {
      "rule_id": "...",
      "title": "Suspicious Process Creation",
      "alerts_last_24h": 45
    }
  ],
  "alerts_by_severity": {
    "critical": 12,
    "high": 85,
    "medium": 320,
    "low": 120
  },
  "alerts_by_tactic": {
    "execution": 120,
    "persistence": 45,
    "defense_evasion": 78
  }
}

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. Alert 관리 API

GET /alerts

alert 목록 조회

쿼리 파라미터:

  • severity: 심각도별 필터
  • status: open, investigating, resolved, false_positive
  • from, to: 시간 범위
  • page, size: 페이지네이션

응답:

{
  "alerts": [
    {
      "id": "alert-123-456",
      "rule_id": "fb843269-508c-4b76-8b8d-88679db22ce7",
      "rule_title": "Suspicious Encoded PowerShell Command",
      "severity": "high",
      "status": "open",
      "event": {
        "timestamp": "2026-02-20T10:15:30Z",
        "source": "endpoint",
        "host": "DESKTOP-ABC",
        "user": "john",
        "process": "powershell.exe",
        "command_line": "powershell.exe -enc ..."
      },
      "enrichment": {
        "user_context": {
          "department": "IT",
          "is_privileged": true
        },
        "asset_context": {
          "criticality": "high",
          "os": "Windows 11",
          "ip": "10.0.1.50"
        },
        "threat_intel": {
          "known_malicious": false,
          "reputation_score": 45
        }
      },
      "mitre": {
        "tactics": ["execution"],
        "techniques": ["T1059.001"]
      },
      "created_at": "2026-02-20T10:15:31Z",
      "updated_at": "2026-02-20T10:15:31Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 50,
    "total": 856
  }
}

PUT /alerts/{id}

alert 상태 업데이트

요청:

{
  "status": "investigating",
  "assignee": "analyst@example.com",
  "notes": "Investigating with user"
}

6. 실시간 업데이트용 WebSocket API

WS /ws/monitoring

실시간 메트릭 업데이트를 위한 WebSocket 연결

인증: 쿼리 파라미터 ?token=xxx에 JWT 토큰

메시지 유형:

서버 푸시 (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": "connector_status_change",
  "timestamp": "2026-02-20T10:30:00Z",
  "data": {
    "connector_id": "550e8400-...",
    "old_status": "healthy",
    "new_status": "unhealthy",
    "message": "Connection timeout"
  }
}
{
  "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. 콘솔 페이지

주요 콘솔 페이지

  1. Dashboard - 실시간 메트릭이 포함된 개요
  2. Connectors - 데이터 소스 연동 관리
  3. Detection Rules - 탐지 규칙 관리
  4. Alerts - Alert triage 및 조사
  5. Pipeline - 상세 파이프라인 메트릭 및 상태
  6. System Health - 서비스 상태

8. 고객 포털 페이지

tenant 대상 포털에서 이용 가능한 페이지:

  1. 포털 홈 / SOC 개요
    • Alert 볼륨, 활성 incident, 수집 상태, 탐지 트렌드 위젯
  2. Alerts & Triage
    • 심각도, 상태, 소스, MITRE 전술, 시간 범위별 검색/필터
  3. 타임라인 검색
    • 구조화된 쿼리를 지원하는 전체 타임라인 검색
  4. 자산 & 노출
    • 자산별 활동 타임라인 및 연결된 탐지
  5. Connectors
    • Tenant connector 온보딩 및 상태 모니터링
  6. 보고서
    • 예약된 컴플라이언스 및 경영진 보고서 (PDF/CSV 내보내기)
  7. Tenant 설정
    • SSO, 역할 매핑, 보존 정책, 알림 채널

포털 API 요구사항

Tenant 격리

  • 모든 요청은 JWT에서 tenant_id를 확인하고 쿼리 실행 전에 tenant 컨텍스트를 적용합니다.
  • 내부 시스템 식별자는 API 응답에 노출되지 않습니다.

성능 SLO

  • Alert 목록 페이지: 30일 쿼리 범위에서 p95 < 2.0초.
  • 타임라인 검색 페이지: 페이지네이션된 결과에서 p95 < 3.0초.
  • Connector 상태 페이지: 30초 갱신 간격, 1% 미만의 stale read.

감사 가능성

  • 검색 쿼리, 케이스 업데이트, connector 변경에 대한 포털 사용자 활동을 기록합니다.
  • 최소 1년간 불변 감사 추적 항목을 유지합니다.

9. 대용량 데이터 API 동작 (정렬/검색/필터)

쿼리 규약 표준

  • sort: 방향이 포함된 쉼표 구분 허용 필드 (예: detected_at:desc,severity:desc)
  • cursor: 다음 페이지를 위한 불투명 토큰
  • limit: 기본값 50, 엔드포인트 최대값 적용
  • q: 페이지별 필드 범위가 있는 키워드 검색
  • filters: 고급 필터링 엔드포인트를 위한 구조화된 JSON 표현식

백엔드 요구사항

  • 모든 정렬/필터링/검색 작업은 서버 측에서 실행됩니다.
  • 지원되지 않는 정렬/필터 필드는 400 INVALID_QUERY_FIELD를 반환합니다.
  • 응답에 메타데이터를 포함합니다:
    • took_ms
    • total_estimate
    • truncated (boolean)
    • query_warnings (array)

성능 목표

  • API 응답 시간: < 200ms (p95)
  • WebSocket 지연: < 100ms
  • Dashboard 갱신 주기: 5초
  • 메트릭 보존: 90일