kapezip

KAPE(Kroll Artifact Parser and Extractor) 모듈이 생성한 CSV 산출물 ZIP 패키지를 압축 해제하지 않고 그대로 읽어 들입니다. KAPE는 Kroll 사가 배포하는 윈도우 포렌식 트리아지 도구로, 수집·파싱한 아티팩트를 모듈별 CSV로 묶어 ZIP에 출력합니다. kapezip 명령어는 이 ZIP을 입력으로 받아 모듈 산출물을 곧바로 쿼리에서 분석하는 용도로 사용합니다.

명령어 속성

항목	설명
명령어 유형	드라이버 쿼리
필요 권한	클러스터 관리자
라이선스 사용량	집계함
병렬 실행	미지원
분산 실행	수집 노드에서 실행 (mapper)

문법

kapezip [entrycs=STR] [cs=STR] [rest=BOOL] FILE_PATH [ENTRY_PATH]

옵션

entrycs=STR: ZIP 파일 엔트리 이름의 문자 인코딩 (기본값: utf-8). ZIP 내부 엔트리 이름이 비표준 인코딩(예: cp949)으로 저장된 경우 지정합니다.
cs=STR: CSV 파일의 문자 인코딩 (기본값: utf-8). CSV 본문이 비표준 인코딩으로 저장된 경우 지정합니다.
rest=BOOL: t 지정 시 CSV 파서가 허용하는 최대 컬럼 수를 초과하는 컬럼을 _rest 필드에 모아서 반환합니다. 생략하거나 f를 지정하면 초과 컬럼은 무시됩니다 (기본값: f).

대상

FILE_PATH: 조회할 ZIP 파일의 경로. 파일 이름 부분에 * 와일드카드를 사용하여 같은 디렉터리의 여러 ZIP 파일을 한 번에 지정할 수 있습니다.
ENTRY_PATH: 조회할 ZIP 내부 CSV 엔트리 경로. * 와일드카드를 사용할 수 있으며, 생략하면 ZIP 내부의 모든 .csv 엔트리를 조회합니다.

출력 필드

필드	타입	설명
`_file`	문자열	레코드의 출처 ZIP 엔트리 경로
(헤더 컬럼)	문자열	CSV 첫 번째 줄의 헤더에 정의된 필드 이름과 해당 값
`column<N>`	문자열	헤더 컬럼 수보다 데이터 행의 컬럼이 많을 때 초과 컬럼에 부여되는 필드 (`N`은 헤더 컬럼 수부터 시작하는 인덱스)
`_rest`	문자열	CSV 파서의 최대 컬럼 수를 초과하는 헤더 컬럼 (`rest=t` 지정 시에만 출력)

오류 코드

파싱 오류

해당 사항 없음

런타임 오류

오류 코드	메시지	설명	후처리 동작
-	csvfile load failure	ZIP 내부 CSV 엔트리를 읽거나 파싱하는 도중 오류가 발생한 경우	쿼리 실행을 중단함
-	-	ZIP 파일을 열 수 없거나 손상된 경우 (`RuntimeException`으로 전파)	쿼리 실행을 중단함

설명

kapezip 명령어는 지정한 ZIP 파일을 열어 내부의 .csv 확장자 엔트리만 골라 차례대로 읽어 들입니다. 각 CSV 엔트리의 첫 번째 줄을 헤더로 인식하여 필드 이름을 자동으로 지정하며, 한 ZIP 파일에 여러 CSV 엔트리가 포함되어 있으면 모든 엔트리의 레코드를 차례로 반환합니다.

ENTRY_PATH를 지정하면 해당 패턴과 일치하는 엔트리만 조회합니다. 와일드카드(*)가 포함되면 패턴 매칭으로, 그렇지 않으면 엔트리 이름 전체와의 정확한 일치로 비교합니다. 어느 쪽이든 .csv 확장자가 아닌 엔트리는 자동으로 건너뜁니다.

CSV 파일이 UTF-8 BOM(Byte Order Mark, 0xEF 0xBB 0xBF)으로 시작하는 경우 자동으로 인식하여 건너뜁니다. 단, cs 옵션을 utf-8 이외의 인코딩으로 지정한 경우에는 BOM을 검사하지 않습니다.

CSV 파서가 허용하는 최대 컬럼 수를 헤더가 초과하는 경우, 기본 동작은 초과 헤더를 무시합니다. rest=t를 지정하면 초과 위치의 헤더를 _rest 필드로 대체합니다. 데이터 행의 컬럼이 헤더 컬럼 수보다 많은 경우 초과 컬럼은 column<N> 형식의 필드(N은 헤더 컬럼 수부터 시작하는 0 기반 인덱스)로 반환됩니다.

FILE_PATH에 와일드카드를 사용하면 매칭되는 모든 ZIP 파일을 차례로 처리합니다. 와일드카드는 파일 이름 부분에서만 동작하며, 디렉터리 부분에는 사용할 수 없습니다.

이 명령어는 클러스터 관리자 권한이 필요하며, 접근 가능한 파일 경로가 ALLOWED_FILE_SCAN_PATHS 설정으로 제한됩니다. 자세한 내용은 파일 접근 제한을 참고하세요.

사용 예

각 사용 예의 파일 경로는 ALLOWED_FILE_SCAN_PATHS 설정에 포함되어 있다고 가정합니다.

ZIP 내부의 모든 CSV 엔트리 조회
```
kapezip /opt/logpresso/evidence/kape-output.zip
```
kape-output.zip 안에 포함된 모든 .csv 엔트리에서 레코드를 차례로 반환합니다. 각 레코드의 _file 필드에는 출처 엔트리 경로가 기록됩니다.
특정 CSV 엔트리만 조회
```
kapezip /opt/logpresso/evidence/kape-output.zip Modules/FileSystem/MFTECmd.csv
```
ZIP 내부에서 정확히 Modules/FileSystem/MFTECmd.csv 경로의 엔트리만 읽어 레코드를 반환합니다.
와일드카드로 여러 엔트리 조회
```
kapezip /opt/logpresso/evidence/kape-output.zip Modules/Registry/*.csv
```
Modules/Registry/ 디렉터리 아래의 모든 CSV 엔트리를 조회합니다.
한국어 인코딩 ZIP 패키지 조회
```
kapezip entrycs=cp949 cs=cp949 /opt/logpresso/evidence/kape-kr.zip
```
엔트리 이름과 CSV 본문이 모두 CP949로 인코딩된 ZIP 패키지를 정상적으로 읽어 들입니다.
와일드카드로 여러 ZIP 파일 일괄 처리
```
kapezip /opt/logpresso/evidence/host-*.zip
```
같은 디렉터리에 있는 host-로 시작하는 모든 ZIP 파일에서 CSV 엔트리를 조회합니다.
초과 컬럼 보존 후 특정 출처 필터링
```
kapezip rest=t /opt/logpresso/evidence/kape-output.zip
| search _file == "Modules/FileSystem/MFTECmd.csv"
```
최대 컬럼 수를 초과하는 헤더는 _rest 필드에 보존하면서 ZIP 전체를 조회한 뒤, _file 필드를 기준으로 특정 엔트리에서 발생한 레코드만 필터링합니다.

호환성

kapezip 명령어는 소나 4.0 이전 버전부터 제공되었습니다. 4.0.2511.0 버전부터 클러스터 관리자 권한이 필요하며, 접근 가능한 파일 경로가 제한됩니다.