Security365 로그 조회 API 가이드

Security365 로그 조회를 위한 API 사용 가이드입니다. 본 문서는 고객사에서 로그 데이터를 조회하기 위해 필요한 API 호출 방법, 샘플 요청/응답, 및 오류 처리 방안을 제공합니다. 로그 조회를 원활히 진행하기 위해 본 문서를 참고하여 설정을 완료해 주시기 바랍니다.

---

1. API Key 발급 및 준비 사항

1. API Key 사용 안내
   • 로그 조회 API를 사용하려면 API Key가 필요합니다.
   • API Key는 요청 데이터에 포함되어 인증 정보로 사용됩니다.
2. 필수 사전 준비
   • API 호출 환경 설정 (네트워크 방화벽, IP 허용 목록 등)
   • Access Token 발급 (인증을 위한 보안 토큰)
3. Access Token 발급
   • Access Token은 API 호출 시 필수로 포함되어야 하며, 인증 서버에서 발급받을 수 있습니다.
   • 요청 헤더에 포함: Authorization: Bearer AccessToken

---

2. 순차적인 작업 가이드

2.1. 로그 조회 API 호출

1. 엔드포인트 정보

• Endpoint: POST /v1/siems/externalSearch

2. 요청 본문(Request Body)

Name	Type	필수	Description
size	int	true	검색 결과 중 가져올 목록 수 (최대 10,000개)
from	int	true	로그 조회 시작 기간 (timestamp)
to	int	true	로그 조회 종료 기간 (timestamp)
sort	array	true	정렬 조건 배열
pagination_key	array	false	페이징 기준값을 지정하는 배열 (응답 결과의 sort 값을 그대로 사용)
license	string	true	검색 대상 라이선스

3. 검색 시간 제한

• API 요청 시 최소 3분 이상의 시간을 설정해야 함. (4분 이상 권장)
• 검색 시간이 너무 짧을 경우 일부 로그가 누락될 수 있음.

4. 샘플 요청

{
    "size": 10000,
    "from": 1735653652984,
    "to": 1747357192199,
    "sort": [ { "time": "desc" } ],
    "license": "HWIX-1DGC0-MKQ6-B2HAF"
}

5. 페이징 처리

• size 값(최대 10,000개)을 초과하는 데이터를 가져올 경우, pagination_key 를 사용해 다음 데이터를 조회해야 함.
• 첫 호출 응답에서 sort 값을 다음 요청의 pagination_key 로 사용.

{
  "size": 10000,
  "from": 1735653652984,
  "to": 1747357192199,
  "sort": [ { "time": "desc" } ],
  "pagination_key": [1747357192199, "6263DE9F46D0FD219A2ABB6C02630A72349BB6AD10F47C2F42F7B"],
  "license": "HWIX-1DGC0-MKQ6-B2HAF"
}

---

3. API 호출 제한

3.1. 호출 횟수 제한

• API 호출 횟수는 30분당 최대 10회로 제한됩니다.
• 과도한 요청을 방지하고 안정적인 서비스 제공을 위한 조치입니다.

3.2. API 응답 예시

{
  "code": 0,
  "items": [
    { "time": 1747357192199, "logLevel": "INFO", "event": "LOGIN" }
  ]
}

---

4. 에러 처리 및 상태 코드

성공 HTTP Status Code 200 Body (JSON 형식)

Name	Type	Description
code	int	성공 여부 (성공: 0)
items	json array	조건에 맞는 로그 데이터 목록

실패 HTTP Status Code

HTTP status code	HTTP 메시지	설명
400	Bad Request	요청 정보 오류
401	Unauthorized	권한 없음
403	Forbidden
404	Not Found
429	Request limit exceeded	요청 제한 초과
500	Internal Server Error	예외 발생
61001	Fail to search	검색 실패
61002	Referer does not match system domain	Referer와 SystemDomain 불일치
61003	JSON conversion error	JSON 변환 오류

---