ini-icam-send-event

INI-ICAM 플랫폼에 단건 보안 이벤트를 전송합니다.

문법

ini-icam-send-event profile=STRING severity=INT category=STRING [src-ip=STRING] [dst-ip=STRING] [dst-port=INT] [user=STRING] [msg=STRING] [time=STRING] [id=STRING] [dry-run=BOOL]

옵션

profile=STRING: 필수. 인증에 사용할 INI-ICAM 접속 프로파일 식별자. 소나 시스템 > 접속 프로파일에서 등록한 프로파일의 식별자를 입력합니다. 프로파일은 하나만 지정할 수 있습니다.
severity=INT: 필수. 이벤트 심각도. 0~10 범위의 정수만 허용하며, 값이 클수록 위험합니다.
category=STRING: 필수. 보안 이벤트를 분류하는 유형 또는 카테고리 (예: malware, authentication).
src-ip=STRING: 선택. 이벤트가 발생한 출발지 IPv4 주소.
dst-ip=STRING: 선택. 이벤트의 목적지 IPv4 주소.
dst-port=INT: 선택. 이벤트의 목적지 포트.
user=STRING: 선택. 이벤트와 연관된 ICAM 등록 사용자 식별자. ICAM에 등록된 사용자와 일치해야 점수가 반영됩니다. 값이 없거나 일치하지 않으면 이벤트는 정상 수신(HTTP 200)되지만 위험 점수에는 반영되지 않습니다.
msg=STRING: 선택. 보안 이벤트의 내용을 설명하는 상세 메시지.
time=STRING: 선택. 이벤트가 발생(탐지)한 시각. 서버 시간대 기준 yyyy-MM-dd HH:mm:ss 형식으로 입력합니다 (예: 2026-07-24 19:00:00). ICAM에는 ISO8601 UTC 초 단위로 변환되어 rt 필드로 전송됩니다. 생략하면 ICAM이 이벤트를 수신한 시각이 사용됩니다.
id=STRING: 선택. 이벤트 유형 코드. 송신 도구가 정의하는 세부 이벤트 식별자 (예: trojan_quarantined). ICAM에는 signature_id 필드로 전송됩니다.
dry-run=BOOL: 선택. 시험 실행 여부 (t, true, f, false. 기본값: t). t이면 ICAM API를 호출하지 않고 옵션 유효성만 검사합니다.

출력 필드

필드	타입	이름	설명
profile	문자열	프로파일	사용된 접속 프로파일 이름
_result	문자열	결과	실제 실행(`dry-run=f`) 시 반환. 성공하면 `success`
_expected	문자열	예상 결과	시험 실행(`dry-run=t`) 시 반환. 유효성 통과 시 `success`

오류 코드

파싱 오류

옵션 검증 단계에서 발생하며, 쿼리 실행이 시작되지 않습니다.

오류 코드	오류 메시지	원인	해결
214700	사용 가능한 INI-ICAM 프로파일이 없습니다	사용 가능한 접속 프로파일이 없음	접속 프로파일을 먼저 등록하세요
214701	profile 옵션을 입력하세요	profile 옵션 누락	`profile=프로파일식별자` 추가
214702	severity 옵션을 입력하세요	severity 옵션 누락	`severity=0~10` 추가
214703	category 옵션을 입력하세요	category 옵션 누락	`category=카테고리명` 추가
214704	severity 옵션은 정수(0~10)여야 합니다	정수가 아니거나 0~10 범위를 벗어남	0~10 범위의 정수 입력
214705	src-ip, dst-ip는 유효한 IPv4 주소여야 합니다	IP 주소 형식 오류	유효한 IPv4 주소 입력
214706	dst-port 옵션은 정수여야 합니다	dst-port에 정수가 아닌 값 입력	정수 입력
214707	프로파일은 하나만 지정할 수 있습니다	profile 값에 쉼표로 복수 지정	프로파일 식별자 하나만 지정
214708	dry-run 옵션은 t, true, f, false 중 하나여야 합니다	허용되지 않는 dry-run 값	`t`, `true`, `f`, `false` 중 하나 입력
214709	time 옵션은 서버 시간대 기준 'yyyy-MM-dd HH:mm:ss' 형식의 문자열이어야 합니다	epoch 값·ISO8601·존재하지 않는 날짜/시각 등 형식 불일치	`time="2026-07-24 19:00:00"` 형식으로 입력

런타임 오류

dry-run=f로 실제 실행 시 외부 ICAM API 호출 과정에서 발생합니다. 쿼리는 오류로 종료됩니다.

오류 메시지	원인	해결
ICAM token issuance failed: cannot resolve host ...	엔드포인트 호스트 이름 조회 실패	엔드포인트 URL 및 DNS 설정 확인
ICAM token issuance failed: connection refused ...	ICAM 서버에 접속 불가	엔드포인트 URL 및 방화벽 정책 확인
ICAM token endpoint rejected credentials (HTTP 401) ...	client_id 또는 client_secret 오류	ICAM 콘솔에서 자격증명 확인 후 프로파일 수정
ICAM event rejected: PIP permission required (HTTP 403) ...	이벤트 전송 권한(PIP) 부족	ICAM 콘솔에서 클라이언트에 PIP 권한 부여

설명

이 명령어는 실행 시 지정한 프로파일의 ICAM 서버에 OAuth2 client_credentials 방식으로 Bearer 토큰을 발급하고, API를 호출해 보안 이벤트 1건을 전송합니다.

토큰은 프로파일별로 캐싱되어 재사용되며, 실행 중 토큰이 만료되거나 거부(HTTP 401)되면 자동으로 새 토큰을 발급해 1회 재시도합니다.

Note

dry-run 옵션 기본값이 t이므로, 실제 이벤트를 전송하려면 반드시 dry-run=f를 명시해야 합니다. 시험 실행(dry-run=t)에서는 ICAM API를 호출하지 않고 옵션 유효성만 검사합니다.

user 옵션에 ICAM에 등록되지 않은 식별자를 지정해도 ICAM이 이벤트를 수신(HTTP 200)하지만, 해당 사용자의 위험 점수에는 반영되지 않습니다.

time 옵션은 소나 서버의 시간대를 기준으로 해석됩니다. 서버 시간대가 Asia/Seoul이면 time="2026-07-24 19:00:00"은 2026-07-24T10:00:00Z로 변환되어 전송됩니다. 시각을 지정하지 않으면 ICAM이 이벤트를 수신한 시각이 발생 시각으로 기록됩니다.

여러 건을 한 번에 전송해야 하는 경우 ini-icam-send-event-batch를 사용합니다.

사용 예

예시: 악성코드 탐지 이벤트 단건 전송 검증 (시험 실행)

상황: 특정 악성코드 탐지 이벤트를 ICAM에 전송하기 전에, 옵션 형식을 먼저 검증합니다.

ini-icam-send-event profile=icam severity=8 category=malware src-ip="192.0.2.10" dst-ip="192.0.2.20" dst-port=443 user=user@example.com msg="C2 연결 시도 탐지" dry-run=t

예상 결과:

profile	_expected
icam	success

결과 해석: _expected=success이면 옵션 형식이 유효한 것입니다. 단, 시험 실행은 ICAM에 접속하지 않으므로 자격증명이나 연결 가능 여부는 검증되지 않습니다. 실제 접속·전송 검증은 dry-run=f로 실행해야 합니다.

예시: 발생 시각과 이벤트 유형 코드를 포함해 전송

상황: 백신이 탐지한 트로이목마 격리 이벤트를 탐지 시각과 이벤트 유형 코드까지 포함해 ICAM에 전송합니다.

ini-icam-send-event profile=icam severity=8 category=malware user=user@example.com msg="트로이목마 격리" time="2026-07-24 19:00:00" id="trojan_quarantined" dry-run=f

예상 결과:

profile	_result
icam	success

결과 해석: ICAM에는 발생 시각이 2026-07-24T10:00:00Z(서버 시간대 Asia/Seoul 기준)로, 이벤트 유형 코드가 trojan_quarantined로 기록됩니다.