iocx-dev/iocxPE 바이너리와 텍스트에서 고신호 IOC를 추출하는 확장 가능하고 결정론적인 정적 분석 엔진으로, SOC 자동화 및 현대 위협 분석 파이프라인을 위해 구축되었습니다.
# IOCX
### **현대 보안 파이프라인을 위한 결정적(Deterministic), 무위험 IOC 추출**
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7470/35e58092394d24631c5bf5a2ef49c2c64bb1726cc5798d35bdaa36800597e402.gif" width="720" alt="IOCX Demo">
</p>
<p align="center"><sub>IOCX CLI를 사용한 PE 파일의 정적 IOC 추출</sub></p>
<p align="center">
<a href="https://pypi.org/project/iocx/"><img src="https://img.shields.io/pypi/v/iocx?logo=pypi&logoColor=white"></a>
<img src="https://img.shields.io/badge/tests-2802_passed-brightgreen">
<img src="https://img.shields.io/badge/coverage-100%25-brightgreen">
<img src="https://img.shields.io/badge/python-3.12-blue">
<a href="https://github.com/iocx-dev/iocx/actions"><img src="https://img.shields.io/github/actions/workflow/status/iocx-dev/iocx/ci.yml?label=build"></a>
<a href="https://github.com/iocx-dev/iocx/blob/main/LICENSE"><img src="https://img.shields.io/github/license/iocx-dev/iocx"></a>
</p>
# 공식 IOCX 프로젝트
이 프로젝트는 결정적 정적 IOC 추출 및 PE 분석을 위한 원본 IOCX 엔진입니다.
"iocx"라는 이름을 사용하는 다른 모든 저장소는 이 프로젝트와 **관련이 없습니다**.
**공식 링크:**
- PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
- Github: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
- 웹사이트: [https://iocx.dev/](https://iocx.dev/)
---
# IOCX가 중요한 이유
현대 악성코드는 **기본적으로 적대적(adversarial)** 입니다 — 변형되고, 회피적이며, 단순한 추출기를 무너뜨리도록 설계되었습니다.
- **바이너리를 인식하지 못하는 도구**는 변형된 PE에서 붕괴됩니다
- **샌드박스**는 안전하지 않으며 CI/CD에서 사용할 수 없습니다
- **재현성**은 자동화된 파이프라인에 필수적입니다
**IOCX는 정확성과 결정성이 실제로 중요한 환경을 위해 구축되었습니다.**
---
# IOCX 엔진
**IOCX는 공식 정적 IOC 추출 엔진**입니다 — DFIR, SOC 자동화, CI/CD 보안, 대규모 위협 인텔리전스 파이프라인을 위해 구축된 결정적이고 바이너리를 인식하는 시스템입니다.
정규식 전용 추출기나 샌드박스 의존 도구와 달리 IOCX는 다음을 수행합니다:
- **순수 정적 분석**
- **실행 위험 제로**
- **안정적이고 결정적인 출력**
- **적대적 테스트를 거친 휴리스틱**
확장 가능한 현대 위협 분석을 위한 MalX Labs 생태계의 핵심 구성 요소입니다.
---
# 10초 만에 IOCX 사용해보기
```bash
echo "http://malicious.example" | iocx -
```
또는 PE 파일을 안전하게 스캔:
```bash
iocx suspicious.exe -a deep
```
---
# IOCX가 존재하는 이유
보안 팀은 세 가지 지속적인 문제에 직면합니다:
1. **정규식 추출기**는 적대적 입력에서 붕괴됩니다
2. **샌드박싱**은 안전하지 않고 느리며 자동화에 부적합합니다
3. **대부분의 IOC 도구**는 일관성이 없거나 느리거나 실행 간에 미묘하게 다른 출력을 생성합니다
IOCX는 자동화, 안전성, 확장성을 위해 설계된 **결정적이고 정적 전용 엔진**으로 이 문제를 해결합니다.
---
# IOCX가 *아닌* 것
IOCX는 의도적으로 **다음이 아닙니다**:
- 샌드박스
- 행동 분석 도구
- 에뮬레이터
- 강화(enrichment) 엔진
신뢰할 수 없는 코드를 절대 실행하지 않습니다.
동적 분석을 절대 수행하지 않습니다.
안전성, 결정성, CI/CD 호환성을 위해 **설계상 정적 전용**입니다.
---
# 설계 철학
IOCX는 레거시 도구의 가정이 아닌 현대 악성코드의 현실을 위해 설계되었습니다.
### **1. 모호성보다 결정성**
안정적이고 재현 가능한 출력 — 무작위성 없음, 변동성 없음.
### **2. 동적보다 정적**
실행은 안전하지 않습니다. 정적 분석은 예측 가능하고 확장 가능하며 CI 친화적입니다.
### **3. 적대적 우선 엔지니어링**
변형된 PE, 손상된 RVA, 적대적 문자열 — IOCX는 이를 정상 입력으로 취급합니다.
### **4. 계약으로서의 스키마 안정성**
다운스트림 시스템은 업그레이드 시 절대 중단되지 않아야 합니다.
### **5. 타협 없는 성능**
원시 텍스트에서 150–300 MB/s.
일반적인 PE에서 6–15 MB/s.
최악의 적대적 부하에서도 예측 가능.
---
이러한 약속은 PE 구조 분석에 대한 발표된 연구 방법론 — 결정적 픽스처 구성, 단일 이상 징후 규율, 정확성의 기준으로서의 Windows 로더 동작 — 에서 파생되었습니다. 전체 방법론은 docs/methodology.md를 참조하고, 더 넓은 적대적 PE 분류 체계와 상업용 픽스처 제품군은 [paax.dev](https://paax.dev)를 참조하십시오.
# IOCX의 차별점
| 기능 | **IOCX** | 일반적인 IOC 추출기 | 샌드박스 / 동적 도구 |
|-----------|-----------|------------------------|--------------------------|
| **안전성** | 무실행, 정적 전용 | 정규식 전용, 바이너리 안전성 없음 | 신뢰할 수 없는 코드 실행 (고위험) |
| **결정성** | 완전히 결정적인 출력 | 노이즈에서 비결정적 | 설계상 비결정적 |
| **바이너리 인식** | 전체 PE 파싱, 휴리스틱 | 바이너리 지원 없음 | 가능하지만 안전하지 않고 느림 |
| **적대적 복원력** | 변형된 PE, 적대적 문자열에 대해 테스트됨 | 쉽게 우회됨 | 종종 충돌하거나 오분류 |
| **성능** | 150–300 MB/s (텍스트), 6–15 MB/s (PE) | 매우 가변적 | 극도로 느림 |
| **CI/CD 친화성** | 예 — 안전, 결정적, 빠름 | 부분적 | 아니요 — 파이프라인에 안전하지 않음 |
| **스키마 안정성** | 보장됨 | 드묾 | 없음 |
**요약:** IOCX는 이상적인 입력이 아닌 *실제 적대적 현실*을 위해 구축되었습니다.
---
# 사용 사례
### CI/CD 및 DevSecOps
- 릴리스 전 바이너리 스캔
- 빌드 내 우발적 URL, IP 또는 비밀번호 감지
- 실행 위험 제로로 보안 게이트 적용
### SOC 및 침해 대응
- 알림 또는 분석가 클립보드 텍스트에서 지표 추출
- 실행 없이 악성코드 샘플 안전하게 검사
- IOC를 구조화된 JSON으로 정규화
### 위협 인텔리전스
- 대규모 피드 처리
- 비구조화된 보고서 파싱
- 결정적 출력 기반 강화 파이프라인 구축
### 자동화 및 스크립팅
- 로그 또는 아티팩트를 IOCX에 파이프
- ETL 또는 배치 워크플로우에 Python API 사용
- 사용자 정의 감지기로 확장
---
# 성능 프로필
### **1. 원시 IOC 추출 (텍스트, 로그, 버퍼)**
**150–300 MB/s** 지속 처리량
빠른 경로 — PE 파싱 없음.
| 감지기 | 1 MB 시간 | 처리량 |
|-----------|-----------|------------|
| Crypto | 0.0037 s | ~270 MB/s |
| Filepaths | 0.0041 s | ~250 MB/s |
| IP | 0.0065 s | ~156 MB/s |
| Domains | 0.0035 s | ~300 MB/s |
---
### **2. 일반적인 PE 파일 (~39 KB)**
- **0.0122 s** (일반)
- **0.0145 s** (휴리스틱 포함)
- **6–15 MB/s** 처리량
---
### **3. 적대적 고밀도 PE (1.5 MB)**
- **0.192 s**
- **~7.6 MB/s** 처리량
- TLS 이상 징후, 구조적 이상 징후, 안티디버그 패턴 트리거
---
### **4. 전체 엔진 (비-PE)**
- **1 MB:** 0.038 s
---
# 버전 주요 사항
<details>
<summary><strong>버전 기록 보기</strong></summary>
<br>
### v0.7.6.2 — Import 테이블 검증기
- 새로운 결정적 **import 테이블 구조 검증기** (`IMPORT_*` 사유 코드).
- `version_info`가 이제 제한된 공개 프로젝션을 통해 **모든** 분석 수준에서 파싱되어 표시됩니다 (`-a full`뿐만 아니라).
- CLI 재구축: 브랜드화된 `--version` 출력, 더 명확한 `--help` 텍스트, 인수 그룹 재구성.
- 모든 항목에서 도달 가능한 리로케이션 파서 충돌, PE32+ 데이터 디렉토리 오프셋 버그, 여러 가지 조용한 export/resource 오류 누락 수정.
- 파서 오류 태그가 검증기에 의해 조용히 소비되지 않도록 방지하는 새로운 정적 CI 검사.
- 테스트 스위트: 2,136 → 2,802 테스트.
---
### v0.7.6.1 — 예외 디렉토리 검증기
- PE 예외 (`.pdata`) 디렉토리의 심층 의미론적 검증 추가; 14개의 새로운 사유 코드; 총 15개의 검증기.
- 엔진 전반에 걸쳐 구조적 발견 사항을 억제하던 결함 수정.
- 프로덕션에서 죽은 것으로 확인된 추가 검사 4개: 디렉토리 배치 2개, 섹션 매핑 1개, 리소스 디렉토리 경계 검사 1개.
- **출력에 표시됨:** 이전에 억제되거나 잘못 레이블링된 발견 사항이 이제 표시됩니다.
- 테스트: 1620 → 2136. 커버리지: 100%.
---
### **v0.7.6 — 구조 검증기 확장: Debug 및 리로케이션 디렉토리**
- 두 개의 새로운 PE 구조 검증기 — 리로케이션 및 디버그
- WIN_CERTIFICATE 및 tls 검증기는 이제 pefile과 독립적인 전용 구조 파서에서 구조적 진실을 소싱
- 우선순위 해결 하위 사유 분류 체계를 갖춘 12개의 새로운 사유 코드
- 결정적 바이트 수준 파싱 — pefile의 지연 해석에 의존하지 않음
- 100% 커버리지의 1620 테스트
---
### **v0.7.5 — 구조 검증기 확장**
- 네 개의 새로운 PE 구조 검증기 — exports, delay-load imports, VS_VERSIONINFO, 리소스 계층 구조
- 우선순위 해결 하위 사유 분류 체계를 갖춘 24개의 새로운 사유 코드
- 결정적 바이트 수준 파싱 — pefile의 지연 해석에 의존하지 않음
- 보안 관련 메타데이터 — DLL 특성, 하위 시스템/머신 이름 디코딩, 리소스별 엔트로피
- 100% 커버리지의 1370 테스트 — 실제 바이너리에서 `dumpbin`에 대해 종단 간 검증됨
---
### **v0.7.4.1 — Windows 호환성 핫픽스**
- Windows 시스템에서 import 실패를 유발한 `python-magic` 의존성 제거
- 완전한 크로스 플랫폼 이식성을 위한 순수 Python 파일 유형 감지기 추가
- 엄격한 Windows 호환 PE 검증을 적용하여 PE 감지 로직 개선
- IOC 추출에 대한 동작 변경 없음
- `--min-length` 일관성 수정은 **v0.7.5**에서 계획됨
---
### **v0.7.4 — 고급 디렉토리 파싱**
- 전체 **Load Config 디렉토리** 파싱 및 검증
- 다운스트림 휴리스틱을 위한 확장된 Optional Header 메타데이터
- 새로운 GuardCF, cookie, 이상 징후 휴리스틱
- 더 빠른 PE 분석
- 테스트 스위트의 99개 PE 픽스처; 45개 완전히 사양 검증됨
---
### **v0.7.3 — 구조적 정확성 및 결정적 휴리스틱**
- 모든 PE 구조 검증기의 주요 강화
- 결정적이고 스냅샷 안정적인 동작
- 명확하고 일관된 ReasonCodes
- 구조적 진실에 기반한 더 강력한 휴리스틱
---
### **v0.7.2 — 의존성 수정**
- 누락된 `idna` 의존성 추가
- 동작 또는 스키마 변경 없음
---
### **v0.7.1 — 적대적 휴리스틱 확장 및 파서 강화**
- 여섯 개의 새로운 PE 휴리스틱
- 확장된 적대적 PE 코퍼스
- 강화된 도메인/URL/crypto/hash 추출기
- 결정적 스냅샷 검증 출력
---
### **v0.7.0 — 결정적 휴리스틱 및 적대적 테스트 기반**
- 결정적 휴리스틱
- 레이어-3 적대적 샘플
- 스냅샷 계약 테스트
- Rich Header 충돌 수정
---
### **v0.6.0 — 안정적인 출력 스키마 및 결정적 메타데이터**
- 완전히 안정적인 JSON 스키마
- 정규화된 PE 메타데이터
- 공식화된 분석 수준
---
### **v0.5.0 — 분석 수준, PE 섹션 분석, 난독화 힌트**
- 새로운 분석 수준 시스템
- PE 구조 분석
- 난독화 휴리스틱
---
### **v0.4.0 — 플러그인 아키텍처**
- 플러그인 준비 규칙 엔진
- 통합 감지 흐름
---
### **v0.3.0 — Crypto IOC 감지**
- Ethereum 및 Bitcoin 지갑 감지
---
### **v0.2.0 — 고신뢰성 IP 감지**
- 주요 IPv4/IPv6 개선
</details>
---
# 빠른 시작
### 설치
```bash
pip install iocx
```
### 파일에서 IOC 추출
```bash
iocx suspicious.exe
```
### 텍스트에서 추출
```bash
echo "Visit http://bad.example.com" | iocx -
```
### PE 분석 활성화
```bash
iocx suspicious.exe -a
```
### Python API
```python
from iocx.engine import Engine
engine = Engine()
results = engine.extract("suspicious.exe")
print(results)
```
---
# 출력 예시
> IOCX는 IOC, PE 메타데이터, 섹션 분석, 휴리스틱 및 난독화 지표를 포함하는 구조화되고 결정적인 JSON을 생성합니다.
>
> 아래 예시는 실제 적대적 PE 샘플의 축약된 출력입니다. 문서화 목적으로 크기를 관리 가능하게 유지하면서 스키마의 형태와 깊이를 보여줍니다.
<details>
<summary><strong>예시 JSON 출력 보기</strong></summary>
```json
{
"file": "heuristic_rich.full.exe",
"type": "PE",
"iocs": {
"urls": ["http://not-a-real-domain.test/payload"],
"domains": ["example-malware.com"],
"ips": ["192.0.2.123"],
"hashes": [
"abcd1234ef567890abcd1234ef567890",
"1234567890",
"3333333333333333"
],
"filepaths": [
"/usr/src/mingw-w64-11.0.1-3build1/mingw-w64-crt/crt/crtexe.c",
"/usr/x86_64-w64-mingw32/include",
"/usr/src/mingw-w64-11.0.1-3build1/mingw-w64-crt/crt/pseudo-reloc.c"
]
},
"metadata": {
"file_type": "PE",
"imports": ["KERNEL32.dll", "msvcrt.dll", "USER32.dll"],
"sections": [
".text", ".data", ".rwx", ".rdata",
"UPX0", ".pdata", ".xdata", ".tls"
],
"resources": [],
"resource_strings": [],
"delayed_imports": [],
"bound_imports": [],
"exports": [],
"signatures": [],
"has_signature": false,
"tls": {
"start_address": 5368758272,
"end_address": 5368758280,
"callbacks": 5368754232
},
"header": {
"entry_point": 5088,
"image_base": 5368709120,
"machine": "AMD64",
"subsystem": "Windows GUI"
},
"optional_header": {
"section_alignment": 4096,
"file_alignment": 512,
"size_of_image": 155648
}
},
"analysis": {
"sections": [
{ "name": ".text", "entropy": 5.92 },
{ "name": ".rwx", "entropy": 0 },
{ "name": "UPX0", "entropy": 0.34 },
{ "name": ".rdata", "entropy": 4.03 }
],
"obfuscation": [
{
"value": "abnormal_section_layout_virtual_only",
"category": "obfuscation_hint",
"metadata": {
"section": ".bss",
"raw_size": 0,
"virtual_size": 384
}
}
],
"extended": [
{
"value": "summary",
"category": "pe_metadata",
"metadata": {
"dll_count": 3,
"import_count": 45,
"resource_count": 0,
"has_tls": true,
"has_signature": false
}
}
],
"heuristics": [
{
"value": "packer_suspected",
"metadata": {
"reason": "packer_section_name",
"section": "UPX0"
}
},
{
"value": "anti_debug_heuristic",
"metadata": {
"reason": "anti_debug_api_import",
"dll": "kernel32.dll",
"function": "CheckRemoteDebuggerPresent"
}
},
{
"value": "anti_debug_heuristic",
"metadata": {
"reason": "timing_api_import",
"dll": "kernel32.dll",
"function": "GetTickCount"
}
},
{
"value": "pe_structure_anomaly",
"metadata": {
"reason": "section_overlaps_headers",
"section": ".bss",
"raw_address": 0,
"size_of_headers": 1536
}
},
{
"value": "pe_structure_anomaly",
"metadata": {
"reason": "data_directory_overlap",
"directory_a": "IMAGE_DIRECTORY_ENTRY_IMPORT",
"directory_b": "IMAGE_DIRECTORY_ENTRY_IAT"
}
}
]
}
}
```
</details>
---
# 아키텍처
```
iocx/
├── examples/
├── docs/
├── tests/
└── iocx
├── detectors/
├── parsers/
├── plugins/
├── cli/
└── analysis/
```
---
# 플러그인 생태계 및 확장성
IOCX는 안전하고 예측 가능하게 확장되도록 설계되었습니다.
플러그인은 **일급 시민**이며, 코어 엔진과 동일한 결정적 스냅샷 테스트로 검증됩니다.
다음을 구축할 수 있습니다:
- 사용자 정의 IOC 감지기
- 사용자 정의 정규식 규칙
- 바이너리 인식 플러그인
- 내부 휴리스틱
- 파이프라인별 추출기
참조:
- `docs/specs/overlap-suppression.md`
- `docs/specs/plugin-authoring-guidelines.md`
---
# 생태계 개요
IOCX는 단일 바이너리 그 이상입니다 — 모듈식 생태계입니다:
- **코어 엔진** — 결정적 IOC 추출 + PE 분석
- **플러그인 시스템** — 사용자 정의 감지기 및 분석 모듈
- **적대적 코퍼스** — 변형된 PE, 적대적 문자열, 퍼즈 샘플
- **스냅샷 테스트 프레임워크** — 결정적 출력 보장
- **성능 벤치마크** — CI에서 강제됨
- **문서 스위트** — 사양, 계약 및 플러그인 가이드
---
# IOCX 사용자
IOCX는 다음 분야에서 사용됩니다:
- DFIR 팀
- SOC 자동화 파이프라인
- CI/CD 보안 게이트
- 위협 인텔리전스 플랫폼
- 악성코드 연구소
- 보안 엔지니어링 팀
지표를 **안전하게**, **결정적으로**, **대규모로** 추출해야 하는 모든 곳에서 IOCX가 적합합니다.
---
# 안전한 테스트 (악성코드 불필요)
모든 테스트 샘플은:
- 합성
- 무해
- 공개적으로 안전 (EICAR, GTUBE)
- 우발적 악성코드 취급을 피하도록 설계됨
---
# 성능 보장
IOCX는 CI에서 엄격한 성능 임계값을 적용하여 다음을 보장합니다:
- 정규식 역추적 중단 없음
- 병리적 속도 저하 없음
- 릴리스 전반에 걸친 안정적인 성능
참조:
- `docs/performance.md`
---
# 프로젝트 정체성 및 명명
**IOCX**라는 이름은 다음에 게시된 공식 엔진만을 지칭합니다:
- PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
- GitHub: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
### 허용되지 않음
- `iocx`라는 이름의 저장소
- 이 프로젝트의 일부가 아닌 "iocx"라는 도구
- 허가 없이 제휴를 암시하는 행위
### 허용됨
- `iocx-<plugin>`
- `iocx-extension-<name>`
- `iocx-detector-<feature>`
---
# 공식 IOCX 저장소
- 코어 엔진: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
- 플러그인 메타 저장소: [https://github.com/iocx-dev/iocx-plugins](https://github.com/iocx-dev/iocx-plugins)
- 문서: [https://github.com/iocx-dev/iocx/tree/main/docs/specs](https://github.com/iocx-dev/iocx/tree/main/docs/specs)
- PyPI 패키지: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
---
# 로드맵
IOCX 개발은 안정성, 확장성 및 더 깊은 정적 분석 범위에 중점을 둡니다.
아래 항목은 진행 중인 작업 및 탐구 영역을 나타냅니다.
- **확장된 PE 휴리스틱** (delay-load 동작, 구조적 이상 징후, 리로케이션 패턴)
- OSINT, DFIR 및 위협 인텔리전스 워크플로우를 위한 **선택적 억제 규칙**
- **ELF 및 Mach-O 메타데이터 추출**
- 다중 아티팩트 워크플로우를 위한 **배치 분석 모드**
- **YARA 스타일 출력 모드** 및 강화 훅
- **바이너리 무관 정적 분석**
- **크로스 플랫폼 플러그인 생태계**
- Rust, Go 및 Node.js용 **언어 바인딩**
---
# 기여
다음을 환영합니다:
- 새로운 감지기
- 파서 개선
- 문서 업데이트
- 합성 적대적 샘플
지침은 `CONTRIBUTING.md`를 참조하십시오.
---
# 보안
보안 문제를 발견한 경우 **GitHub 이슈를 열지 마십시오**.
`SECURITY.md`의 지침을 따르십시오.
---
# 라이선스
MPL‑2.0 라이선스 — `LICENSE` 참조.