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개)
filters	json	true	로그 조회 기간 (from, to 필수)
sort	array	true	정렬 조건 배열
pagination_key	array	false	페이징 기준값 배열, 응답 결과의 sort 값을 그대로 사용해야 합니다.
license	string	true	소프트캠프에서 제공한 라이선스 키

3. 검색 시간 제한

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

4. 샘플 요청

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

5. 페이징 처리

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

{
  "size": 10000,
  "filters": { "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
500	Internal Server Error	예외 발생
-1	기타 에러	기타 오류

---

5. 검색 결과 개수 제한 및 예제 추가

• 검색 기간 동안의 전체 로그 개수를 반영하도록 수정되었습니다.
• size 제한(최대 10,000개)이 존재하며, total 값이 10,000을 초과할 경우 10,000까지만 반환됨.

예시 응답:

{
    "code": 0,
    "msg": "",
    "total": 10000,
    "items": [...],
    "pagination_key": "abcd1234"
}

• total: 검색 기간 내 존재하는 전체 로그 개수 (size 제한으로 인해 최대 10,000개까지만 표시됨).

Example:

{
    "size": 10000,
    "filters": { "from": 1735689600000, "to": 1747357192199 },
    "sort": [ { "time": "desc" } ],
    "license": "8PZU-GAZSF-QTM7-TXPHB"
}

---