11로그 API와 첨부 파일 API로그 API와 첨부 파일 API
SmartConsole을 열지 않고 자동화 스크립트로 로그를 가져오고 싶을 때, 두 개의 management API가 쓰입니다. API for Logs 는 명령 하나로 로그나 상위 통계를 조회 하고, Log Attachments API 는 그 로그에 딸린 첨부(패킷 캡처·Threat Emulation 리포트 등)를 자동으로 가져옵니다. 둘 다 Management Server에서 실행하며, SmartConsole 접근 권한이 없거나 management API에 익숙한 운영자가 자동화 안에서 로그를 다루려는 상황을 위한 기능입니다.
API for Logs — 로그를 명령으로 조회
이 API의 핵심 강점은 SmartConsole의 Logs 탭 검색줄에 입력하던 필터 문법을 그대로 쓴다 는 점입니다. 평소 SmartConsole에서 손으로 치던 검색을 그대로 mgmt_cli 명령에 옮겨 적으면 되므로, 새 문법을 따로 배울 필요가 없습니다. 모든 명령은 Management Server에서 실행 해 환경 안의 로그를 끌어옵니다.
어떤 상황에서 쓰나
SmartConsole에 접근할 수 없거나, management API 사용에 익숙한 고객을 위한 기능입니다. 운영자가 자신의 자동화 스크립트 안에서 로그를 가져오고, 그 로그로 통계를 내는 작업을 SmartConsole 없이 처리할 수 있습니다. 한 가지 중요한 원칙은 권한이 로그인한 사용자 프로파일에 따라 그대로 적용 된다는 점입니다 — API라고 해서 더 넓은 권한을 주지 않습니다.
이 API로 할 수 있는 일
API for Logs로 처리할 수 있는 작업은 크게 다섯 가지입니다.
- 로그 가져오기(Fetch Logs) — 환경 안의 어느 Log Server에서든 명령 하나로 로그를 끌어옵니다. 출력은 조건에 맞는 모든 로그가 모든 필드를 담은 JSON 형식으로 돌아옵니다. 입력에 붙일 수 있는 선택 파라미터는 로그 종류(Traffic/Audit)·기간(time-frame)·필터 조건(SmartConsole 쿼리 줄과 동일)·조회할 특정 Log Server·결과 건수 제한 입니다.
- 로그 페이지 나눠 받기(Page through Logs) — 결과가 많을 때 Log Server에 부담을 주지 않도록, 로그는 작은 묶음(기본·최대 모두 100건)으로 나눠 가져옵니다. 첫 "페이지"에는 정해진 수의 로그만 담기고, 같은 쿼리의 다음 묶음은 앞 응답에서 받은
query-id를 명령에 넣어 이어 받습니다. - 상위 통계 조회(Get Top Statistics) — 여러 필드의 top 값(예: top sources·top destinations) 을 한 번에 조회합니다.
- 첨부 여부 확인(Fetch Log Attachments) — 쿼리 응답의 각 로그는 자신이 첨부를 가졌는지 표시 합니다. 첨부는 패킷 캡처일 수도, Threat Emulation 리포트일 수도 있습니다. 별도의 명령(Log Attachments API)이 로그 ID로 그 첨부를 가져와 하나의 JSON 응답으로 돌려줍니다.
- SmartConsole에서 API 명령 생성(Generate API Commands) — SmartConsole의 Logs 탭에서 버튼을 누르면, 현재 화면에 떠 있는 쿼리를 그대로 API 명령으로 만들어 줍니다. 여기에는 기간·선택한 Log Server·필터(쿼리 줄)·기본 50건 제한 이 포함됩니다. 즉 API for Logs의 동작 방식은 SmartConsole 로그 쿼리와 똑같습니다.
새 로그 쿼리 만들기
기본 꼴은 다음과 같습니다.
mgmt_cli show-logs new-query.filter product:<product name> new-query.time-frame <time-frame> new-query.max-logs-per-request <limit>각 파라미터의 뜻은 이렇습니다.
| 파라미터 | 설명 |
|---|---|
filter | SmartConsole/SmartView에 입력하는 그대로의 필터. 형식: String |
time-frame | 로그를 조회할 기간. 기본값 last-7-days. 형식: String (아래 표의 값 중 하나) |
custom-start | custom 기간의 시작. 반드시 ISO 8601 형식. 형식: String |
custom-end | custom 기간의 끝. 반드시 ISO 8601 형식. 형식: String |
max-logs-per-request | 한 번에 받을 건수. 값 범위 1~100, 기본값 10. 형식: String |
type | 돌려줄 로그 종류. 값 logs/audit, 기본값 logs. 형식: String |
log-servers | 조회할 Log Server들의 IP 목록. 기본값 all(전체). 형식: String |
time-frame 에 넣을 수 있는 값은 다음과 같습니다.
| 값 | 의미 |
|---|---|
last-7-days | 최근 7일(기본값) |
last-hour | 최근 1시간 |
today | 오늘 |
last-24-hours | 최근 24시간 |
yesterday | 어제 |
this-week | 이번 주 |
this-month | 이번 달 |
last-30-days | 최근 30일 |
all-time | 전체 기간 |
custom | 사용자 지정 기간(custom-start·custom-end 함께 사용) |
custom 기간을 직접 정해 조회하려면 시작·끝 날짜를 함께 줍니다.
mgmt_cli show logs new-query.time-frame "custom" new-query.custom-start YYYY-MM-DD new-query.custom-end YYYY-MM-DD상위 통계 조회하기
특정 필드의 top 값을 뽑을 때는 top.field 와 top.count 를 줍니다.
mgmt_cli show-logs new-query.filter product:<product name> new-query.top.field blades new-query.top.count <number> --format json -r true| 파라미터 | 설명 |
|---|---|
count | 가져올 상위 항목 수. 값 범위 1~50. 형식: String |
field | 통계를 낼 필드. 형식: String (아래 값 중 하나) |
field 에 쓸 수 있는 값은 sources·destinations·services·actions·blades·origins·users·applications 입니다.
기존 쿼리의 다음 페이지 받기
이미 실행한 쿼리에서 더 많은 결과가 필요하면 query-id 로 이어 받습니다.
mgmt_cli show-logs query-id <query-id> --session-id <session-id>| 파라미터 | 설명 |
|---|---|
query-id | 지정한 제한만큼, 마지막으로 실행한 쿼리의 다음 페이지를 가져옵니다. 형식: String |
ignore-warnings | 경고가 있어도 무시합니다. 형식: Boolean |
제약 사항
Log Attachments API — 첨부를 자동으로 가져오기
Log Attachments API 는 로그 첨부를 자동으로 가져오는 길을 제공합니다. 블레이드마다 딸리는 첨부의 종류가 다른데, 예를 들어 IPS 로그에는 패킷 캡처가, Threat Emulation 로그에는 요약 리포트 가 붙습니다. 트래픽 부담을 줄이려고 로그는 보통 첨부를 모두 담아 내보내지는 않으므로, 첨부가 필요하면 이 API로 따로 가져와야 합니다. 이 기능은 모든 게이트웨이 버전을 지원 합니다.
어떤 상황에서 쓰나
다음 같은 사용자를 위한 기능입니다.
- Log Exporter 로 외부 syslog 시스템에 로그 첨부를 끌어와, 자동화 과정에서 전용 스크립트로 다루려는 경우.
- Log Exporter 를 쓰면서, 최종 사용자에게 SmartConsole 접근 권한을 주지 않으려는(또는 줄 수 없는) 경우.
- API for Logs 를 쓰는 경우.
첨부를 가져오는 두 가지 길
첨부를 가져오는 방식은 두 가지이고, 첨부를 가리키는 식별자를 어디서 얻느냐 가 다릅니다.
| 방식 | 식별자를 얻는 곳 |
|---|---|
| Log Exporter | 내보낸 로그에 붙는 attachment ID를 사용 |
| API for Logs | 쿼리 결과에 들어 있는 log ID를 사용 |
Log Exporter 경로
Log Exporter 는 로그를 외부 SIEM으로 내보내면서 log-attachment-id 라는 식별자를 덧붙이는데, 이 값은 그 로그의 모든 첨부 ID를 공백으로 구분해 담고 있습니다. Log Exporter에는 이 attachment ID를 내보낼지 켜고 끄는 파라미터가 있습니다.
받은 식별자를 명령에 넣으면 원하는 첨부가 담긴 JSON 응답이 돌아옵니다. 이 JSON에는 첨부 데이터가 base64로 인코딩되어 있으므로, 디코딩해서 지정한 대상 폴더에 풀어야 비로소 쓸 수 있습니다.
Log Exporter로 로그 첨부를 가져오는 명령은 다음과 같습니다.
1. cp_log_export set name <name> [domain-server <domain-server>] export-attachment-ids true
2. cp_log_export restart name <name> [domain-server <domain-server>]
3. mgmt_cli get-attachment attachment-id "<id from the exported log>"반대로 Log Exporter가 attachment ID를 내보내지 않게 끄려면 다음과 같이 합니다.
1. cp_log_export set name <name> [domain-server <domain-server>] export-attachment-ids false
2. cp_log_export restart name <name> [domain-server <domain-server>]API for Logs 경로
이 경로에서는 먼저 Management Server에서 로그 쿼리를 실행합니다. JSON 응답에는 각 로그마다 id 필드 가 들어 있는데, 이 log ID를 손에 넣은 다음 Log Attachments API를 호출하면 그 로그에 딸린 모든 첨부 를 받습니다.
로그 결과 중 하나의 첨부를 가져오는 절차입니다.
1. Run: mgmt_cli show-logs
2. Run: mgmt_cli get-attachment id "<log id from the previous response>"