ini-icam-send-event-batch

파이프라인의 각 레코드에서 INI-ICAM 플랫폼에 보안 이벤트를 전송합니다.

문법

... | ini-icam-send-event-batch profile=STRING [dry-run=BOOL]

옵션

profile=STRING: 필수. 인증에 사용할 INI-ICAM 접속 프로파일 식별자. 소나 시스템 > 접속 프로파일에서 등록한 프로파일의 식별자를 입력합니다. 프로파일은 하나만 지정할 수 있습니다.
dry-run=BOOL: 선택. 시험 실행 여부 (t, true, f, false. 기본값: t). t이면 각 레코드의 유효성만 검사하고 ICAM API를 실제로 호출하지 않습니다.

입력 필드

파이프라인에서 넘어오는 각 레코드에서 아래 필드를 읽습니다.

필드	타입	필수	설명
severity	정수	Y	이벤트 심각도 (0~10, 클수록 위험).
category	문자열	Y	보안 이벤트 카테고리 (예: `malware`, `authentication`)
src_ip	문자열 / IP	N	출발지 IPv4 주소.
dst_ip	문자열 / IP	N	목적지 IPv4 주소.
dst_port	정수	N	목적지 포트 번호.
user	문자열	N	ICAM 등록 사용자 식별자. 미등록 값이면 이벤트 수신은 되지만 위험 점수에 반영되지 않습니다.
msg	문자열	N	이벤트 상세 메시지
event_time	날짜 / 문자열	N	이벤트 발생(탐지) 시각. 날짜 타입 값은 그대로 사용하며, 문자열은 서버 시간대 기준 `yyyy-MM-dd HH:mm:ss` 형식이어야 합니다. ICAM에는 `rt` 필드로 전송됩니다. 값이 비어 있으면 생략되어 ICAM 수신 시각이 사용됩니다.
signature	문자열	N	이벤트 유형 코드 (예: `trojan_quarantined`). ICAM에는 `signature_id` 필드로 전송됩니다.

출력 필드

레코드별로 기존 필드에 아래 필드가 추가됩니다.

필드	타입	이름	설명
profile	문자열	프로파일	사용된 접속 프로파일 이름
_result	문자열	결과	실제 실행(`dry-run=f`) 시 반환. `success` 또는 `fail`
_expected	문자열	예상 결과	시험 실행(`dry-run=t`) 시 반환. `success` 또는 `fail`
_error	문자열	오류	처리 실패 시 오류 메시지. 성공 레코드에는 추가되지 않음

오류 코드

파싱 오류

쿼리 파싱 단계에서 발생하며, 파이프라인 실행 자체가 중단됩니다.

오류 코드	오류 메시지	원인	해결
214700	사용 가능한 INI-ICAM 프로파일이 없습니다	사용 가능한 접속 프로파일 없음	접속 프로파일을 먼저 등록하세요
214701	profile 옵션을 입력하세요	profile 옵션 누락	`profile=프로파일식별자` 추가
214707	프로파일은 하나만 지정할 수 있습니다	profile 값에 쉼표로 복수 지정	프로파일 식별자 하나만 지정
214708	dry-run 옵션은 t, true, f, false 중 하나여야 합니다	허용되지 않는 dry-run 값	`t`, `true`, `f`, `false` 중 하나 입력

런타임 오류 (레코드별 `_error` 필드)

파이프라인은 계속 실행되며, 실패한 레코드에만 _result=fail과 _error 메시지가 기록됩니다.

_error 값	원인	해결
`severity field is required`	severity 필드 없음 또는 빈 값	입력 레코드에 severity 필드 추가
`category field is required`	category 필드 없음 또는 빈 값	입력 레코드에 category 필드 추가
`severity must be an integer (0~10)`	severity가 정수가 아니거나 0~10 범위 외	severity 값을 0~10 범위 정수로 설정
`src_ip must be a valid IPv4 address`	src_ip 형식 오류	유효한 IPv4 주소로 입력
`dst_ip must be a valid IPv4 address`	dst_ip 형식 오류	유효한 IPv4 주소로 입력
`dst_port must be an integer`	dst_port가 정수가 아님	정수로 입력
`event_time must be a Date object or a 'yyyy-MM-dd HH:mm:ss' formatted string in server time zone (e.g. 2026-07-24 19:00:00)`	event_time 형식 오류	날짜 타입 필드로 넘기거나 `yyyy-MM-dd HH:mm:ss` 문자열로 입력
`no matching INI-ICAM profile found`	지정한 프로파일이 존재하지 않음	접속 프로파일 식별자 확인
ICAM token endpoint rejected credentials ...	client_id 또는 client_secret 오류	ICAM 콘솔에서 자격증명 확인 후 프로파일 수정
ICAM event rejected: PIP permission required	이벤트 전송 권한(PIP) 부족	ICAM 콘솔에서 클라이언트에 PIP 권한 부여

설명

이 명령어는 파이프라인의 각 레코드를 순차적으로 처리하는 배치(Batch) 명령어입니다. 파이프라인 시작 시 지정한 INI-ICAM 접속 프로파일로 연결을 초기화하고, 이후 각 레코드에 대해 유효성을 검사한 뒤 API를 호출합니다.

event_time 필드는 날짜 타입 값을 그대로 사용하므로, 수집된 로그의 발생 시각(_time 등)을 그대로 전달할 수 있습니다. 문자열로 넘길 때는 소나 서버 시간대 기준 yyyy-MM-dd HH:mm:ss 형식이어야 하며, 형식이 맞지 않으면 해당 레코드만 실패하고 나머지 레코드는 정상 전송됩니다. 값이 비어 있는 레코드는 발생 시각 없이 전송되어 ICAM 수신 시각이 사용됩니다.

한 레코드 처리가 실패해도 나머지 레코드는 계속 처리됩니다. 실패한 레코드에는 _result=fail과 _error 메시지가 추가되고, 성공한 레코드에는 _result=success가 추가됩니다.

OAuth2 토큰은 실행 시작 시 1회 발급해 재사용합니다. 실행 중 토큰이 만료되면(HTTP 401) 자동으로 새 토큰을 발급하고 해당 레코드를 재시도합니다.

Note

dry-run 옵션 기본값이 t이므로, 실제 이벤트를 전송하려면 반드시 dry-run=f를 명시해야 합니다.

단건 전송이 필요한 경우 ini-icam-send-event를 사용합니다.

사용 예

예시: 탐지 로그를 INI-ICAM에 일괄 전송 검증 (시험 실행)

상황: 최근 10분간 탐지된 이벤트를 INI-ICAM에 전송하기 전에, 레코드별 필드 유효성을 먼저 검증합니다.

table my_detection_table
| search _time >= dateadd(now(), "min", -10)
| fields severity, category, src_ip, dst_ip, user, msg
| ini-icam-send-event-batch profile=icam dry-run=t

예상 결과:

severity	category	src_ip	profile	_expected
8	malware	192.0.2.10	icam	success
5	authentication	192.0.2.50	icam	success

결과 해석: 모든 레코드의 _expected=success이면 필드 형식은 유효한 것입니다. 단, 시험 실행은 ICAM에 접속하지 않으므로 자격증명·연결은 검증되지 않습니다. _expected=fail 레코드가 있으면 _error 값을 확인해 입력 데이터를 수정하고, 실제 접속·전송은 dry-run=f로 확인합니다.

예시: 수집된 로그의 발생 시각으로 일괄 전송

상황: 저장된 악성코드 탐지 로그를 조회해 각 로그의 발생 시각과 이벤트 유형 코드를 ICAM에 전송합니다.

table my_malware_events
| eval event_time = _time, signature = "trojan_quarantined"
| ini-icam-send-event-batch profile=icam dry-run=f