ZombieGuard

ZIP 아카이브의 구조적 메타데이터 기반 회피를 탐지하는 방어용 스캐너.

ZombieGuard는 ZIP 로컬 파일 헤더, 중앙 디렉터리 레코드, 페이로드 특성 간의 모순을 탐지합니다. 이러한 모순은 한 파서에는 아카이브 내용이 비어 있거나 무해해 보이게 하면서도 다른 파서는 여전히 페이로드에 도달할 수 있게 만드는 데 악용될 수 있습니다.

제한된(bounded) ZIP 파서와 소형 LightGBM 모델을 결합합니다. 아카이브 내용을 추출하거나 실행하지 않습니다.

[!IMPORTANT] ZombieGuard는 악성코드가 아닌 아카이브 회피 신호를 탐지합니다. 정상(clean) 결과는 아카이브 내부 파일이 안전하다는 증거가 아닙니다.

60초 빠른 시작

ZombieGuard는 Python 3.11 및 3.12를 지원합니다.

git clone https://github.com/mdshoaibuddinchanda/zombieguard.git
cd zombieguard
python -m pip install .
zombieguard scan suspicious.zip --include-features

릴리스 모델은 패키지와 함께 설치됩니다. 입력 크기 제한, JSON/SARIF 출력, 디렉터리 스캔 옵션은 zombieguard scan --help를 참조하세요.

개발 시에는 저장소를 편집 가능(editable) 모드로 설치합니다:

python -m pip install -e ".[dev]"
python -m pytest

검사 항목

ZombieGuard는 악성코드 시그니처를 찾는 대신 각 ZIP을 일관성 문제로 취급합니다:

• 로컬 파일 헤더와 중앙 디렉터리의 일치 여부;
• 압축 방식, 크기, 오프셋, CRC의 일관성;
• 선언된 압축 대비 페이로드 엔트로피;
• 형식 오류, 잘림, 암호화, 지원되지 않는 구조;
• 첫 번째 항목뿐만 아니라 모든 항목에 걸친 의심스러운 동작.

스캐너는 판정(verdict)과 함께 근거 코드(reason code)를 보고합니다. 파싱 실패는 판정 불가(indeterminate) 또는 의심(suspicious) 조건으로 보고되며, 정상(clean) 결과로 조용히 변환되지 않습니다.

아키텍처

Untrusted ZIP bytes
       │
       ▼
Bounded structural parser ──► explicit parse/limit failures
       │
       ▼
Per-entry consistency features
       │
       ▼
Versioned LightGBM model
       │
       ▼
verdict + score + reasons

구조 검증 오류는 명시적인 '스캔 불가(unscannable)' 결과를 생성합니다. 성공적으로 파싱된 아카이브는 모델이 점수를 매기고, 관찰된 불일치는 근거 코드로 반환됩니다. 모델 메타데이터에는 피처 스키마, 학습 구성, 소스 해시, 모델 체크섬이 기록됩니다.

검증된 평가

릴리스 평가는 의도적으로 범위를 좁혀 재현 가능하게 구성되었습니다. 실제 환경에서의 악성코드 탐지나 교차 형식 일반화를 주장하지 않습니다.

현재 아티팩트는 다음과 같이 보고합니다:

혼동 행렬은 TN=1,565, FP=3, FN=0, TP=1,150입니다. 공식 결과는 artifacts/metrics.json에 있습니다. 이 파일에는 변종별 폴드 요약, 데이터 소스 해시, 누수(leakage) 검증, 모델 체크섬, 정확한 구성도 포함되어 있습니다. 지표를 이력서, 논문, 발표 자료에 사용할 경우 그 범위를 합성 중첩 leave-one-variant-out 피처 평가로 명시하세요.

음성 행은 PyPI 파생 686개, 생성된 하드 네거티브 478개, 생성된 소형 정상 400개, Office 파생 4개의 피처 행으로 구성됩니다. 음성 소스 패밀리는 패밀리 단위로 홀드아웃되지 않고 폴드 전체에 분산됩니다. 신뢰 구간은 이 벤치마크 내 행 수준의 불확실성을 설명하며, 배포 불확실성이나 도메인 이동(domain shift)을 추정하지 않습니다. LightGBM 출력은 확률이 아닌 보정되지 않은(uncalibrated) 점수로 보고됩니다. 임계값 정책은 중첩 폴드로 평가된 개발 단계의 동작점(operating point)입니다. 측정된 오탐률을 프로덕션 환경의 증거로 간주하려면 현재 릴리스로 파싱한 새로운 정상 아카이브가 여전히 필요합니다.

왜 합성 양성을 사용할까요? 이처럼 범위가 좁은 회피 기법에 대한 공개적이고 독립적으로 검증된 사례는 드물기 때문입니다. 생성 방식을 사용하면 각 구조적 변형이 명시적이고 반복 가능해집니다. 합성 성능은 탐지기가 그러한 변형을 인식한다는 증거이며, 독립적으로 라벨링된 실제 환경 벤치마크를 대체하지는 않습니다.

출처(provenance), 라벨 의미, 실패 모드는 데이터 카드와 모델 카드를 참조하세요.

릴리스 재현

핵심 의존성을 설치하고 커밋된 아티팩트를 검증합니다. 추가 생성 및 갱신 단계는 모든 안전한 합성 양성을 재현하고, 재학습 전에 커밋된 피처가 현재 파서와 여전히 일치하는지 확인합니다:

python -m pip install -e .
python -m zombieguard.evaluate --check
python data/scripts/generate_zombie_samples.py
python scripts/refresh_synthetic_features.py
python -m zombieguard.evaluate --train --check

학습은 커밋된 피처 및 라벨 테이블을 읽고 다음을 생성합니다:

• src/zombieguard/assets/zombieguard_lgbm.txt — 이식 가능한 LightGBM 모델;
• src/zombieguard/assets/zombieguard_lgbm.metadata.json — 스키마 및 무결성 메타데이터;
• artifacts/metrics.json — 기계 판독 가능한 평가 보고서.

지속적 통합(CI)은 린팅, 의존성 및 정적 보안 감사, 바이트 컴파일, 커버리지 테스트, Python 3.11 및 3.12 패키지 빌드, 생성기/파서 정합성, 커밋된 아티팩트 검증, 격리된 학습-점검(train-and-check) 스모크 테스트를 실행합니다.

저장소 구조

src/zombieguard/        installable scanner package and release assets
tests/                  self-contained unit, adversarial, and CLI tests
data/processed/         committed feature table and labels
data/scripts/           safe synthetic-data builders
scripts/                dataset curation and audit helpers
artifacts/metrics.json  reproducible release metrics
docs/                   data and model cards

원본 악성코드, 다운로드된 코퍼스, 자격 증명, 로컬에서 학습된 임시(scratch) 모델은 저장소에 포함되지 않습니다.

범위 및 제한 사항

• 지원되는 아카이브 형식은 ZIP뿐입니다. RAR, 7z, APK, JAR에 대한 성능은 주장하지 않습니다.
• 모델은 생성된 회피 변종과 정상 라벨 피처 행으로 학습됩니다. 새로운 파서 차이(parser differential)는 학습된 피처 분포와 일치하지 않을 수 있습니다.
• 암호화된 콘텐츠는 검사할 수 없습니다. 디렉터리 재귀는 중첩 폴더에서 ZIP 파일을 찾지만, 다른 아카이브 내부에 포함된 아카이브는 스캔하지 않습니다.
• 결과는 격리 또는 검토 워크플로우에 입력으로 제공되어야 하며, 안티바이러스 엔진, 샌드박스, 콘텐츠 스캐너, 인간 분석가를 대체해서는 안 됩니다.
• 적대적(adversarial) 아카이브는 메모리나 CPU를 소비할 수 있습니다. --max-size-mb 입력 상한을 활성화된 상태로 유지하고, 프로덕션 배포에서는 프로세스 수준의 메모리 및 시간 제한을 추가하세요.

기여 및 보안

파서, 데이터셋, 평가 프로토콜을 변경하기 전에 CONTRIBUTING.md를 읽으세요. 재현 가능한 아티팩트 없이 악성코드 샘플, API 자격 증명, 벤치마크 주장을 커밋하지 마세요.

취약점 또는 파서 우회(bypass) 보고는 SECURITY.md를 따르세요. 공개 이슈에 실제 악성코드를 첨부하지 마세요.

라이선스

Apache License 2.0에 따라 라이선스가 부여됩니다.

데이터 카드 · 모델 카드 · 보안 정책 · 기여 · CI