Deserializer

프로젝트 소개

• Deserializer는 Python 생태계 전반에서 안전하지 않은 객체 재구성 및 상태 지속성 싱크를 식별하도록 설계된 고급 추상 구문 트리(AST) 정적 분석 엔진으로, AI, LLM, 로보틱스, 데이터 과학, 머신러닝 및 딥러닝 분야에 특히 중점을 두고 있지만 이에 국한되지는 않습니다.
• Deserializer는 앱, 스크립트, 프레임워크, 라이브러리, Python pip 패키지 등 Python 소스 코드를 기반으로 하는 모든 종류의 프로젝트를 스캔하고 분석하도록 설계되었습니다.

핵심 기술 역량

전통적인 스캐너를 훨씬 뛰어넘어, YAML, Msgpack, CBOR, 사용자 정의 JSON 훅을 포함한 120개 이상의 라이브러리와 형식을 감사하기 위한 범용 고성능 프레임워크를 제공합니다. 여기서 "안전한" 직렬화에 대한 전통적인 신뢰는 로직 기반의 치명적인 RCE 벡터를 숨기고 있습니다. 임포트, 별칭, 복잡한 점 표기 속성을 해석함으로써, 이 도구는 현대 분산 아키텍처와 AI/ML 저장소에서 위험한 코드 경로의 우선순위를 정하는 고충실도 신호 증폭기 역할을 합니다.

이 프로젝트는 원시 탐지에서 심층 기술 감사로 전환하는 모듈식 다단계 워크플로를 통해 작동합니다. 초기 고속 SAST 스캔에 이어, 생태계는 실행 흐름을 추적하는 특수 관계 매퍼와 상세한 보안 보고서를 생성하는 결과 프로세서를 활용합니다. 이러한 체계적인 접근 방식은 모든 발견 사항이 애플리케이션의 더 넓은 아키텍처 내에서 맥락화되도록 보장하여, 대량의 텔레메트리를 실행 가능한 연구 자산과 인프라 수준의 공격 표면 매핑을 단순화하는 구조화된 마일스톤으로 전환합니다.

자율 AI 보안 에이전트

가장 고급 단계에서 Deserializer는 자율 AI 보안 에이전트(Phase 4)를 통합하며, 이는 "자기 명령 주입" 제한을 탐색하고 HuggingFace 추론 API, 로컬 LLM(llama.cpp 등), 또는 OpenAI API 호환을 기반으로 기능적 재현 가이드를 합성하도록 명시적으로 설계되었습니다.

프로젝트가 발전함에 따라, 추상 구문 트리 정적 분석, 관계 매핑, 보고, 문서화된 연구에 기반한 기능적 익스플로잇 개발 사이의 간극을 메움으로써 자동화된 취약점 연구의 최전선을 계속 정의해 나가고 있습니다.

연구 (AI, 로보틱스, 데이터 과학, 머신러닝 및 딥러닝)

Deserializer는 Genesis World (v0.2.1), MuJoCo (v3.7.0), LeRobot (v0.5.1), Brax (v0.14.2), TensorFlow (v2.21.0), LangGraph (v1.1.6), VibeVoice (v0.0.1), Hugging Face Hub (v1.11.0), PyGlove (v0.4.5) 등 다양한 대규모 AI, 로보틱스, 데이터 과학 프로젝트 및 환경 전반에서 RCE 및 안전하지 않은 역직렬화 경로를 찾아내어 보안 연구를 직접 지원합니다.

그 기능은 업계를 선도하는 프레임워크에서 치명적인 취약점 발견을 직접적으로 지원하여, 복잡한 MLOps 및 에이전트 AI 환경 감사에서의 효용성을 입증했습니다.

Deserializer의 4단계

이 프로젝트는 네 가지 뚜렷한 단계로 구성되며, 각 단계는 분석을 대량의 자동화된 텔레메트리에서 심층적이고 기능적인 보안 연구로 전환하도록 설계되었습니다:

단계	제목	도구 / 엔진	목표
1	고속 탐지	deserializer.py (Triple-Pass)	잠재적인 역직렬화 싱크를 식별하기 위해 대규모 SAST를 수행합니다.
2	관계 매핑	결과 프로세서 / 매퍼	실행 흐름과 컴포넌트 상호 의존성을 추적하여 발견 사항을 맥락화합니다.
3	기술 종합	연구 문서화	발견 사항을 기술 문서로 공식화하고 인프라 수준의 공격 표면을 매핑합니다.
4	자율 AI 에이전트	AI 보안 에이전트	HuggingFace 추론 API, 로컬 LLM(llama.cpp 등), 또는 OpenAI API 호환을 사용하여 0-day 발견을 자동화하고 기능적 재현 가이드/익스플로잇을 생성합니다.

프로젝트 구조

저장소 구성의 개략도와 각 전문 디렉터리의 기술적 목적:

• agent/
  Phase 4 AI 보안 에이전트의 구현으로, 심층 분석, 재현 가이드 합성, LLM 상호작용을 위한 오케스트레이션 로직을 포함합니다.
• docs/
  프로젝트 문서, 아키텍처 다이어그램, 브랜딩 자산, 지원 고수준 기술 자료를 위한 중앙 저장소입니다.
• exploit_development/
  기능적 익스플로잇 엔지니어링, 역직렬화 프리미티브(훅/메서드) 연구, 크로스 플랫폼 오케스트레이션 기법 문서화를 위한 전용 공간입니다.
• modules/
  도구 체인의 탐지 및 관계 매핑 단계를 구동하는 핵심 로직 컴포넌트, 보조 유틸리티 함수, 스캐너 확장입니다.
• reports/
  다단계 프로젝트 평가 중 스캐너가 생성한 구조화된 보안 분석 출력, 텔레메트리, 감사 결과의 저장소입니다.
• research/
  현대 AI/ML 프레임워크에 대해 수행된 고충실도 취약점 문서, 검증된 Proof-of-Concept(PoC) 스크립트, 심층 감사의 모음입니다.
• templates/
  취약점 문서와 상관관계 보고서 전반에 걸쳐 기술적 일관성을 유지하기 위해 사용되는 표준화된 보고 및 연구 템플릿입니다.

성능 및 멀티프로세싱

이 스캐너는 Python의 concurrent.futures.ProcessPoolExecutor를 기반으로 구축된 고성능 병렬 실행 엔진을 특징으로 합니다. 사용 가능한 모든 CPU 코어에 걸쳐 확장되도록 설계되었으며(-j 또는 --concurrency 플래그로 제어 가능), 수만 개의 파일을 몇 초 만에 스캔할 수 있습니다.

• 논블로킹 UI: 깔끔한 결과 표시를 위한 한 줄 간격이 있는 안정적인 도킹형 진행 표시줄을 제공합니다.
• 네이티브 시그널 처리: Windows에서는 ctypes를 통해 네이티브 SetConsoleCtrlHandler를 활용하여 과중한 처리 중에도 Ctrl+C가 100% 반응하도록 보장합니다.
• 무음 트레이스백: 워커 프로세스는 무음 처리되어 인터럽트와 내부 오류가 기술 출력을 어지럽히지 않도록 합니다.
• 네이티브 Windows UI 지원: 최신 CMD 및 PowerShell 환경에서 네이티브 ANSI 색상 지원을 위해 ctypes를 통해 가상 터미널 처리를 자동으로 활성화합니다.

[!WARNING] 성능 경고: 매우 크거나 복잡한 파일(예: 1MB, 2MB, 3MB 이상)을 분석할 때, 깊은 AST 트리를 파싱하는 동안 도구가 상당히 느려지거나 "멈춘" 것처럼 보일 수 있습니다. 이러한 병목 현상이 발생하면 --timeout(느린 파일 건너뛰기) 및 --max-size(거대한 파일 건너뛰기) 플래그를 사용하여 스캔 속도를 유지하는 것을 고려하십시오.

기능

• Triple-Pass 스캔 엔진: "깨지지 않는" 다계층 접근 방식을 구현합니다:
  • Pass 1 (AST): 정밀한 분석을 위한 고충실도 문법 분해.
  • Pass 2 (토큰 폴백): 구문 오류나 파싱 불가능한 섹션을 만났을 때 스트림 기반 토크나이저로 자동 폴백.
  • Pass 3 (정규식 비상): 극도로 적대적이거나 파편화된 소스 파일에서도 커버리지를 보장하는 최종 패턴 매칭 계층.
• 네이티브 템플릿 중화: Jinja2 및 Mako 태그 정제를 기본 지원하여, 스캐너가 비-Python 구문에 걸리지 않고 웹 템플릿과 코드 생성 파일을 처리할 수 있습니다.
• 호출 및 참조 탐지: 직접적인 실행 싱크(예: pickle.loads())뿐만 아니라 위험한 함수 참조(예: func = pickle.load)도 식별하여 로컬 네임스페이스 전반의 할당을 추적합니다.
• 다음과 같은 호출을 해석하기 위해 임포트/별칭을 추적합니다:
  • import pickle as p → p.loads(...)
  • import torch as t → t.load(...)
  • pkg.pickle.loads(...) 또는 torch.serialization.load(...)와 같은 깊은 속성
• 발견 사항을 JSONL로 출력하며, 한 줄에 하나의 객체로 다음을 포함합니다:
  • 파일 경로 + 위치 (lineno, col_offset)
  • module, name, qualified_name
  • category 및 severity (추가 필드, 하위 호환)
  • parser: 어떤 엔진 패스가 발견을 수행했는지 나타내는 메타데이터 (ast, tokenize_fallback, 또는 regex_fallback).
• 다음과 같은 방법으로 병리적 입력을 방지합니다:
  • 최대 파일 크기 (MAX_FILE_BYTES)
  • 최대 방문 AST 노드 (MAX_AST_NODES)
• 선택 사항: rules.json에서 사용자 정의 규칙 세트를 로드하고 잘못된 형식의 항목/오타에 대해 경고합니다.

설치

최소 Python 버전 3.9+ 권장, 3.10+ 테스트 완료.

python --version
# Python 3.9+ 권장

설정 요구 사항:

• 환경: 공급자에 따라 루트 디렉터리에 .env 파일을 생성하십시오:

  # Hugging Face 공급자의 경우
  HF_TOKEN=your_token_here
  
  # OpenAI / 로컬 LLM 공급자의 경우
  HA_LLM_TOKEN=your_jwt_token_here
  

스캐너를 실행하기 전에 반드시 종속성을 설치해야 합니다:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

사용법

권장 사용법:

AI 에이전트 없이

python deserializer.py --path cloned-repo --rules-file rules.json -j 4 --out cloned-repo/cloned-repo.jsonl

AI 에이전트 사용 (로컬 LLM)

python deserializer.py --path cloned-repo --rules-file rules.json -j 4 --out cloned-repo/cloned-repo.jsonl --agent --agent-provider local --llm-api-url http://127.0.0.1:8181/v1

AI 에이전트 사용 (OpenAI / 로컬 LLM)

python deserializer.py --path cloned-repo --rules-file rules.json -j 4 --out cloned-repo/cloned-repo.jsonl --agent --agent-provider openai --llm-api-url http://127.0.0.1:8181/v1

AI 보안 에이전트를 통한 AI 기반 심층 분석 (Phase 4)

이 단계는 심층 코드 검토를 수행하고 복잡한 0-day RCE 벡터를 매핑하기 위해 특수 AI 보안 에이전트를 통합합니다. 에이전트는 발견 사항을 분석하여 "자기 명령 주입" 컨텍스트를 역추적하고 다중 플랫폼(예: 공격자 UNIX/Raspberry vs 피해자 Windows)에 중점을 둔 기술 재현 가이드를 생성합니다. 참고: 이 단계는 --agent 플래그가 제공된 경우에만 실행됩니다.

추론 공급자:

• Hugging Face (기본값): MiniMax-M2.5와 같은 클라우드 기반 API 모델을 사용합니다.
  • .env 파일 또는 환경 변수에 HF_TOKEN이 필요합니다.
  • 명령: python deserializer.py --path /path/to/repo --agent --agent-provider huggingface
• 로컬 LLM (llama.cpp): 로컬 REST 서버(llama-server.exe)를 사용합니다.
  • 서버 실행 명령 예시: .\llama-server.exe --model .\models\model.gguf --host 127.0.0.1 --port 8181 --ctx-size 600000 --jinja
  • 명령: python deserializer.py --path /path/to/repo --agent --agent-provider local --llm-api-url http://127.0.0.1:8181/v1
• OpenAI 호환:
  • .env에 HA_LLM_TOKEN(또는 OPENAI_API_KEY)이 필요합니다.
  • 명령: python deserializer.py --path /path/to/repo --agent --agent-provider openai --llm-api-url http://127.0.0.1:8181/v1

1. 기본 스캔

현재 디렉터리를 스캔하고 발견 사항을 터미널에 출력합니다(기본적으로 JSONL을 stdout에 기록):

python deserializer.py

2. 대상 감사

특정 저장소를 스캔하고 발견 사항을 JSONL 파일에 저장합니다:

python deserializer.py --path /path/to/my-repo --out audit_results.jsonl

3. 터보 모드 (성능 튜닝)

8개의 동시 프로세스와 파일당 5초 타임아웃을 사용하여 스캔을 계속 진행합니다:

python deserializer.py -j 8 --timeout 5 --out findings.jsonl

4. CI/CD 및 파이프라인 통합

배너를 비활성화하고 파이프 처리를 위해 JSONL을 stdout으로 직접 스트리밍합니다(사람용 로그는 stderr로 이동):

python deserializer.py --no-banner --out - | jq .

5. 강화 / 안전 스캔

처리를 1MB 미만의 파일로 제한하고 특정 데이터 디렉터리를 건너뜁니다:

python deserializer.py --max-size 1048576 --skip-dirs "data,samples,tests"

6. 사용자 정의 탐지 규칙

독점 규칙 세트를 사용하여 로직 특정 호출을 탐지합니다:

python deserializer.py --rules-file my_custom_rules.json --out legacy_audit.jsonl

7. AI 심층 분석

스캔과 매핑이 완료된 후 AI 기반 심층 분석(Phase 4)을 트리거합니다:

python deserializer.py --path /path/to/repo --out findings.jsonl --agent

CLI 플래그