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

REST API 레퍼런스

KYRA MDR REST API는 alert, incident, collector 및 기타 플랫폼 리소스에 대한 프로그래밍 방식의 접근을 제공합니다. 기존 도구와 KYRA MDR을 통합하거나, 워크플로우를 자동화하거나, 커스텀 대시보드를 구축하는 데 사용할 수 있습니다.

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

인증

모든 API 요청에는 Authorization 헤더에 Bearer 토큰이 필요합니다.

API Key 생성

  1. KYRA MDR Console을 엽니다
  2. Settings > API Keys로 이동합니다
  3. Create API Key를 클릭합니다
  4. 키에 이름을 지정합니다 (예: “SIEM Integration”)
  5. 권한 범위를 선택합니다 (read-only 또는 read-write)
  6. 키를 복사합니다 — 다시 표시되지 않습니다

API Key 사용

모든 요청에 키를 포함합니다:

Terminal window
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.seekerslab.com/api/v1/alerts

인증 오류

상태의미
401 UnauthorizedAPI key 누락 또는 유효하지 않음
403 ForbiddenAPI key에 필요한 권한 없음
429 Too Many RequestsRate limit 초과 (아래 참조)

Rate Limit

플랜Rate Limit
FREE60 requests/minute
MDR300 requests/minute
PRO1,000 requests/minute
CUSTOMCustom

Rate limit 헤더는 모든 응답에 포함됩니다:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1700000060

공통 파라미터

파라미터타입설명
pageinteger페이지 번호 (기본값: 1)
sizeinteger페이지당 항목 수 (기본값: 20, 최대: 100)
sortstring정렬 필드 (예: created_at)
orderstring정렬 순서: asc 또는 desc
fromISO 8601시간 범위 시작
toISO 8601시간 범위 종료

Alerts

Alert 목록 조회

GET /alerts

쿼리 파라미터:

파라미터타입설명
severitystring심각도별 필터: critical, high, medium, low, info
statusstring상태별 필터: open, in_progress, resolved, false_positive
source_typestring소스별 필터: fortigate, windows, aws-cloudtrail 등

예시:

Terminal window
# 최근 24시간의 모든 미처리 critical alert 조회
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.seekerslab.com/api/v1/alerts?severity=critical&status=open&from=2026-03-21T00:00:00Z"

응답:

{
  "data": [
    {
      "id": "alert-550e8400-e29b",
      "title": "Brute Force Authentication Attempt",
      "severity": "high",
      "status": "open",
      "source_type": "windows",
      "source_ip": "10.0.1.55",
      "mitre_tactic": "Credential Access",
      "mitre_technique": "T1110",
      "created_at": "2026-03-22T08:15:30Z",
      "event_count": 47,
      "ai_summary": "47 failed logon attempts (Event ID 4625) from 10.0.1.55 targeting 3 accounts in 2 minutes."
    }
  ],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 1,
    "total_pages": 1
  }
}

Alert 상세 조회

GET /alerts/{alert_id}
Terminal window
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.seekerslab.com/api/v1/alerts/alert-550e8400-e29b

Alert 상태 업데이트

PATCH /alerts/{alert_id}
Terminal window
curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved", "comment": "False positive - authorized penetration test"}' \
  https://api.seekerslab.com/api/v1/alerts/alert-550e8400-e29b

Incidents

Incident 목록 조회

GET /incidents
파라미터타입설명
severitystring심각도별 필터
statusstringopen, investigating, contained, resolved, closed
assigneestring담당 분석가별 필터
Terminal window
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.seekerslab.com/api/v1/incidents?status=open"

응답:

{
  "data": [
    {
      "id": "inc-7c9e6679-a1f4",
      "title": "Suspected Lateral Movement - WORKSTATION-12",
      "severity": "critical",
      "status": "investigating",
      "alert_count": 5,
      "created_at": "2026-03-22T07:00:00Z",
      "updated_at": "2026-03-22T08:30:00Z",
      "assignee": "analyst@company.com",
      "mitre_tactics": ["Lateral Movement", "Credential Access"],
      "ai_summary": "Multiple pass-the-hash logons from WORKSTATION-12 to 4 servers within 10 minutes, followed by LSASS memory access."
    }
  ]
}

Incident 상세 조회

GET /incidents/{incident_id}

타임라인, 관련 alert, 영향받는 자산, 대응 조치를 포함한 전체 incident를 반환합니다.

Incident 코멘트 추가

POST /incidents/{incident_id}/comments
Terminal window
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Isolated WORKSTATION-12 from network. Investigating root cause."}' \
  https://api.seekerslab.com/api/v1/incidents/inc-7c9e6679-a1f4/comments

Collectors

Collector 목록 조회

GET /collectors
Terminal window
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.seekerslab.com/api/v1/collectors

응답:

{
  "data": [
    {
      "id": "col-abc123",
      "name": "DC-Collector-01",
      "hostname": "collector01.internal.company.com",
      "status": "connected",
      "version": "1.5.2",
      "os": "Ubuntu 22.04",
      "last_seen": "2026-03-22T09:00:15Z",
      "events_per_second": 245,
      "uptime_hours": 720
    }
  ]
}

Collector 상세 조회

GET /collectors/{collector_id}

상태 메트릭, 설정된 소스, 버퍼 상태를 포함한 상세 정보를 반환합니다.

로그 검색

이벤트 검색

POST /search
Terminal window
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "source_type:windows AND event_id:4625",
    "from": "2026-03-21T00:00:00Z",
    "to": "2026-03-22T00:00:00Z",
    "size": 50
  }' \
  https://api.seekerslab.com/api/v1/search

응답:

{
  "data": [
    {
      "timestamp": "2026-03-21T14:22:10Z",
      "source_type": "windows",
      "source_ip": "10.0.1.55",
      "event_id": 4625,
      "message": "An account failed to log on.",
      "fields": {
        "TargetUserName": "admin",
        "LogonType": 3,
        "WorkstationName": "ATTACKER-PC",
        "IpAddress": "192.168.1.100"
      }
    }
  ],
  "total": 342
}

검색 쿼리 구문

연산자예시설명
필드 일치source_type:windows정확한 필드 일치
ANDseverity:critical AND status:open두 조건 모두
ORsrc_ip:10.0.1.1 OR src_ip:10.0.1.2하나의 조건
NOTNOT source_type:sysmon일치 제외
와일드카드user:admin*접두사 일치
범위event_count:[10 TO 100]숫자 범위

Webhooks

Webhook 생성

POST /webhooks
Terminal window
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Critical Alerts",
    "url": "https://hooks.slack.com/services/T00/B00/xxx",
    "events": ["alert.created"],
    "filters": {
      "severity": ["critical", "high"]
    }
  }' \
  https://api.seekerslab.com/api/v1/webhooks

Webhook 이벤트

이벤트설명
alert.created새 alert 탐지됨
alert.updatedAlert 상태 변경됨
incident.created새 incident 생성됨
incident.updatedIncident 상태 변경됨
collector.disconnectedCollector 오프라인 전환

Webhook Payload

{
  "event": "alert.created",
  "timestamp": "2026-03-22T08:15:30Z",
  "data": {
    "id": "alert-550e8400-e29b",
    "title": "Brute Force Authentication Attempt",
    "severity": "high",
    "source_type": "windows",
    "url": "https://kyra-mdr-console.seekerslab.com/alerts/alert-550e8400-e29b"
  }
}

오류 응답

모든 오류는 일관된 형식을 따릅니다:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid severity value. Allowed: critical, high, medium, low, info",
    "details": {
      "parameter": "severity",
      "value": "urgent"
    }
  }
}
HTTP 상태오류 코드설명
400INVALID_PARAMETER유효하지 않은 요청 파라미터
401UNAUTHORIZEDAPI key 누락 또는 유효하지 않음
403FORBIDDEN권한 부족
404NOT_FOUND리소스를 찾을 수 없음
429RATE_LIMITED요청 과다
500INTERNAL_ERROR서버 오류 — 고객 지원에 문의

SDK 및 라이브러리

REST API는 모든 HTTP 클라이언트에서 사용 가능합니다. 아래는 주요 언어에서의 예시입니다:

# Python 예시
import requests


API_KEY = "your-api-key"
BASE_URL = "https://api.seekerslab.com/api/v1"


headers = {"Authorization": f"Bearer {API_KEY}"}


# 미처리 critical alert 조회
response = requests.get(
    f"{BASE_URL}/alerts",
    headers=headers,
    params={"severity": "critical", "status": "open"}
)


alerts = response.json()["data"]
for alert in alerts:
    print(f"[{alert['severity']}] {alert['title']}")

도움이 필요하신가요?