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] [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: 선택. 보안 이벤트의 내용을 설명하는 상세 메시지.
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` 중 하나 입력

런타임 오류

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)하지만, 해당 사용자의 위험 점수에는 반영되지 않습니다.

여러 건을 한 번에 전송해야 하는 경우 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로 실행해야 합니다.