증거 중심의 악성코드 리버스 엔지니어링으로, 심층 PE/.NET 검사, Ghidra 재구성, AI 교차 검증, YARA, ELF 디버깅을 포함합니다.
AIDebug는 증거 중심의 악성코드 리버스 엔지니어링 CLI 및 터미널 UI입니다. 결정적 오프라인 트리아지, 전체 파일 16진수 검사, 심층 PE 구조 분석, Capstone 디스어셈블리, Ghidra 재구성, 선택적 LLM 교차 검증, 로컬 ELF 디버깅, 컴파일된 학습 연습문제, 그리고 분석가 검토 보고를 결합합니다.
현재 소스 버전: AIDebug 3.1.0. 3.1.0 릴리스 노트를 참조하세요.
최신 불변 게시 릴리스는 AIDebug v3.0.0으로 유지되며,
1200km-aidebug로 제공됩니다.
버전이 일치하는 3.1.0 태그와 GitHub 릴리스가 검증된 게시 워크플로를 완료할 때까지입니다.
PyPI에서 안정 패키지를 설치합니다:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install 1200km-aidebug==3.0.0
aidebug --version
필요에 따라 선택 기능을 설치합니다:
# 원격/로컬 LLM 제공자 및 검증된 YARA 생성
python -m pip install "1200km-aidebug[ai]==3.0.0"
# Frida 동적 계측
python -m pip install "1200km-aidebug[dynamic]==3.0.0"
# 모든 선택적 Python 통합
python -m pip install "1200km-aidebug[all]==3.0.0"
개발용:
git clone https://github.com/anpa1200/AIDebug.git
cd AIDebug
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev,dynamic]"
Ghidra, GDB, Bubblewrap, C 컴파일러, Frida 대상 구성 요소는 해당 워크플로에서만 사용되는 외부 도구입니다.
메인 터미널 인터페이스에서 PE 또는 ELF 샘플을 엽니다:
aidebug --binary /path/to/sample.exe --offline
전체 화면 UI 없이 결정적 분석을 실행하고 증거를 내보냅니다:
aidebug --binary /path/to/sample.exe \
--offline --no-tui --report --json-export --yara \
--out-dir reports/
Ghidra 재구성 사용:
aidebug --binary /path/to/sample.exe --offline --no-tui --decompile
aidebug --binary /path/to/sample.exe --offline --no-tui \
--decompile-all reports/sample-reconstruction.c
임시 비실행 ELF 아티팩트를 통해 하나의 C 번역 단위를 분석합니다:
aidebug --source /path/to/example.c --offline --no-tui
파일 확장자와 무관하게 임의의 파일을 식별합니다:
aidebug --identify /path/to/renamed-or-unknown-file --offline
--identify는 선언된 유형, MIME 유형, 일반 확장자, 신뢰도, 방법, 증거, SHA-256, 크기를 포함한 구조화된 JSON을 보고합니다. 결정적 커버리지에는 일반 실행 파일 및 바이트코드 형식, 아카이브 및 디스크 이미지, Office/OpenDocument/EPUB 컨테이너, 문서, 이미지, 오디오/비디오, 패킷 캡처, 데이터베이스, 레지스트리/이벤트 로그 아티팩트, 스크립트, 텍스트가 포함됩니다. ZIP 기반 형식은 제한된 멤버 이름과 작은 메타데이터 읽기로 검사됩니다. 파일은 실행되거나 추출되지 않습니다.
로컬 플랫폼에 알려진 추가 시그니처를 위해 python-magic과 운영 체제의 libmagic 데이터베이스를 설치합니다:
python -m pip install python-magic
결정적 시그니처, 구조 또는 텍스트 규칙이 일치하지 않으면 구성된 AI 제공자가 제한된 메타데이터(확장자, 크기, SHA-256, 최대 96바이트 헤더, 32바이트 테일, 샘플 엔트로피, NUL 비율)에서 후보를 추론할 수 있습니다. 파일 본문, 추출된 문자열, 파일 시스템 경로는 전송되지 않습니다. AI 전용 결과는 ai-inference로 표시되고, 신뢰도 60%로 제한되며, 분석가 검증이 필요합니다. 폴백을 완전히 비활성화하려면 --offline을 사용하세요. 해결되지 않은 유형은 종료 상태 2로 Unknown으로 보고됩니다.
메인 터미널 인터페이스에서 S를 누르거나 워크스페이스에서 직접 시작합니다:
aidebug --binary /path/to/sample.exe --offline --strings
워크스페이스는 파일 오프셋, 사용 가능한 매핑 주소, 인코딩, 바이트 및 문자 길이, 중복 발생 정보, 섹션 컨텍스트, 신뢰도, 트리아지 점수, 각 분류의 결정적 이유를 보존합니다. 필터는 최소 길이, 인코딩, 카테고리, 자유 텍스트 검색을 포함합니다. 열 정렬과 페이지네이션으로 대규모 인벤토리를 사용 가능하게 유지합니다. 선택된 각 인코딩은 크기 제한 아티팩트 전체를 스캔합니다. 보존된 인벤토리는 25,000개 레코드와 값당 4,096자 표시로 제한됩니다. 정확한 후보/누락 수와 전체 바이트 커버리지로 두 제한이 모두 표시됩니다. 각 레코드는 최대 32개의 DLL/API 주석과 4,096자의 설명 문자를 유지합니다. 적대적 오버플로는 레코드 이유에 보고됩니다.
탐지는 다중 레이블입니다. 단일 값은 동시에 DLL, Windows 경로, URL, IP 주소, 레지스트리 키, 명령, PowerShell 조각, 명명된 파이프, 해시, 자격 증명 후보, 사용자 에이전트 또는 기타 지원되는 증거 유형이 될 수 있습니다. 도메인 후보는 IDNA 정규화되고 패키지된 오프라인 IANA 루트 존 스냅샷과 대조됩니다. IP 주소는 완전한 유효 토큰을 차지해야 하며, 구성 할당은 보수적인 전체 줄 문법과 일치해야 합니다. 이는 짧은 바이너리 조각이 점, 콜론 또는 등호를 포함한다는 이유만으로 승격되는 것을 방지합니다. 관련 레이블은 하나의 신뢰도 패밀리를 공유하므로 ip_address와 ipv6는 두 개의 독립적인 관찰로 취급되지 않습니다. 알려진 DLL과 API는 짧은 중립적 기능 설명을 받습니다. 알려지지 않은 이름은 추측된 용도 대신 명시적인 미검증 폴백을 받습니다. 추출된 이름은 존재의 증거이지 코드가 이를 호출했거나 샘플이 악성이라는 증거는 아닙니다.
결정적 인벤토리를 로컬에서 출력하고, 표시된 CLI 뷰를 필터링하거나, 표준 전체 인벤토리를 소유자 전용 JSON으로 작성합니다:
aidebug --binary /path/to/sample.exe --strings --no-tui
aidebug --binary /path/to/sample.exe --strings --no-tui \
--string-encoding ascii --min-string-length 6 --string-category url
aidebug --binary /path/to/sample.exe --strings --no-tui \
--strings-output reports/sample-strings.json
AI 문자열 검토는 별도의 옵트인 작업입니다. 워크스페이스 내에서 A를 누르고 개인정보/비용 경고를 확인하거나 CLI 모드에서 명시적으로 요청합니다:
aidebug --binary /path/to/sample.exe --strings --no-tui \
--analyze-strings --accept-ai-cost \
--strings-output reports/sample-strings-ai.json
보존된 각 문자열에는 안정적인 증거 ID가 할당됩니다. 명시적 확인 후 AI 경로는 결정적, 제한된 청크로 모든 보존 레코드를 계획합니다. 제공자 또는 검증 실패는 안전하게 중지되고 표시됩니다. 응답은 제공된 모든 ID를 설명해야 하며 수락 전에 엄격한 로컬 스키마, 열거형, 참조, IOC 근거 검증을 통과해야 합니다. 최종 리듀서는 원시 인벤토리가 아닌 검증된 발견을 봅니다. 추출 제한, 실패한 배치, 검토/전송 수는 항상 보고됩니다. 불완전한 커버리지는 전체 평가를 unknown으로 강제합니다. 문자열에는 비밀번호, API 토큰, 고객 데이터, 공격자가 작성한 프롬프트 인젝션이 포함될 수 있으므로 이 기능을 활성화하기 전에 원격 AI 경계를 검토하세요.
파일 또는 SHA-256로 이전 분석을 검사합니다:
aidebug --history /path/to/sample.exe
aidebug --history 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
PE 파일을 로드하고 메인 GUI에서 X(또는 P)를 누릅니다. AIDebug는 해시한 정확한 바이트를 제시하고 구조적 증거를 제한된 탐색 가능한 뷰로 구성합니다.
| 영역 | 증거 |
|---|---|
| 헤더 | DOS, NT, COFF, 선택적 헤더, 특성, 데이터 디렉터리, 완화 플래그 |
| 섹션 | 전체 IMAGE_SECTION_HEADER 필드, 매핑된 범위, 엔트로피, 권한 |
| 임포트 및 익스포트 | 임포트 디스크립터, INT/IAT 항목, 지연 임포트, 서수, 이름, RVA, 포워더 |
| 리소스 | 유형/이름/언어 계층, 메타데이터, 해시, 미리보기, 안전한 덮어쓰기 방지 내보내기 |
| 재배치 및 ASLR | 재배치 블록/항목 및 구조적 ASLR 호환성 평가 |
| TLS | TLS 디렉터리, 템플릿 데이터, 인덱스, 콜백 테이블, 매핑, 종료 증거 |
| 예외 및 언와인드 | x64 런타임 함수, UNWIND_INFO, 연산, 핸들러, 체인 레코드 |
| 로드 구성 | 버전 관리 필드, Guard 플래그, 스택 쿠키 및 익스플로잇 완화 증거 |
| CFG | 체크/디스패치 포인터, Guard Function ID 대상, 순서, 억제, 일관성 검사 |
| Authenticode | 인증서 레코드, PKCS#7/X.509 증거, PE 이미지 다이제스트 비교, 서명자 검증 |
| 디버그 및 출처 | Rich 헤더, 디버그 디렉터리, CodeView RSDS/NB10, PDB GUID, age, 경로 |
| 오버레이 | 정확한 오프셋, 크기, 해시, 엔트로피, 미리보기, 안전한 내보내기 |
| .NET / CLR | COR20 헤더, 메타데이터 루트 및 스트림, ECMA-335 테이블, 어셈블리, 참조, 리소스 |
AIDebug는 이러한 뷰를 구축하는 동안 PE를 실행하지 않습니다. 정적 인증서 검증은 Windows 루트 신뢰 또는 해지 검증이 아니며, Rich 메타데이터는 귀속이 아니며, 강력한 이름 메타데이터는 게시자 신뢰가 아니며, 정적 완화 플래그는 효과적인 런타임 정책의 증거가 아닙니다.
이 문서들은 저장소 문서를 보완하는 장문 워크플로와 스크린샷을 제공합니다:
전체 카탈로그를 열거나 특정 사례로 시작합니다:
aidebug --learn
aidebug --learn mov-load
aidebug --learn lea-arithmetic
aidebug --learn switch-dispatch
번들된 각 사례는 learning/cases/ 아래의 독립형 파일입니다. AIDebug는 선택한 사례를 임시 x86-64 ELF로 컴파일하고, 정확한 C 소스와 컴파일러 생성 명령을 표시하고, Ghidra에 독립적 재구성을 요청하고, 빌드 출처를 기록하고, 임시 아티팩트를 제거합니다. 생성된 학습 바이너리는 실행되지 않습니다.
텍스트 출력에는 --no-tui를 사용하거나 검토된 외부 컬렉션을 로드합니다:
aidebug --learn movsxd --no-tui
aidebug --learn --learning-collection /path/to/reviewed-cases
AI 분석은 선택 사항입니다. 결정적 오프라인 모드는 자격 증명 없이 사용할 수 있습니다.
python -m pip install "1200km-aidebug[ai]==3.0.0"
cp .env.example .env
chmod 600 .env
정확히 하나의 제공자를 구성하거나 여러 자격 증명이 있을 때 AIDEBUG_LLM_PROVIDER를 명시적으로 설정합니다:
AIDEBUG_LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=replace_with_your_key
# 대안:
# OPENAI_API_KEY=replace_with_your_key
# GEMINI_API_KEY=replace_with_your_key
# OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
AIDEBUG_ENV_FILE=/absolute/path/to/private.env를 사용하여 신뢰할 수 없는 분석 디렉터리에서 구성을 분리합니다. 원격 대량 분석에는 명시적 --accept-ai-cost 확인이 필요합니다. 샘플 증거를 제공자에게 보내기 전에 원격 AI 데이터 경계를 검토하세요.
GDB 기반 활성 모드는 선택한 로컬 ELF를 실행합니다. 격리되고 승인된 랩 내에서만 사용하세요:
aidebug --binary ./sample.elf --mode debug --breakpoint main
사용 가능한 명령에는 break, continue, step, next, finish, registers, changes, io, disassemble, quit이 포함됩니다. Frida 동적 모드는 지원되는 로컬 또는 원격 계측 워크플로에 대해 별도로 사용할 수 있습니다.
| 출력 | 의도된 용도 |
|---|---|
| HTML 보고서 | 인간 검토 및 사례 노트 |
| 버전 관리 JSON | 사용자 정의 통합 입력, 벤더 네이티브 또는 STIX 스키마 아님 |
| 문자열 인텔리전스 JSON | 표준 보존 문자열 인벤토리 및 선택적 검증된 AI 주석과 커버리지 |
| YARA 후보 | 검토와 테스트가 필요한 로컬 컴파일 탐지 엔지니어링 시드 |
| ATT&CK 후보 | 분석가 검증이 필요한 기술 수준 가설 |
| CFG 시각화 | 함수 수준 제어 흐름 검토 |
| SQLite 기록 | 로컬 세션 증거 및 SHA-256 기반 발견 복원 |
flowchart LR
Input[PE, ELF, or C source] --> Parse[Bounded parsing and hashing]
Parse --> Structure[Hex and PE structure evidence]
Parse --> Strings[Deterministic string intelligence]
Parse --> Disasm[Capstone disassembly]
Disasm --> Patterns[Deterministic patterns]
Disasm --> Ghidra[Ghidra reconstruction]
Patterns --> Offline[Offline findings]
Patterns --> AI[Optional LLM cross-check]
Strings --> StringAI[Opt-in chunked string AI review]
Ghidra --> AI
Offline --> Reports[HTML, JSON, YARA, CFG]
AI --> Reports
StringAI --> StringJSON[Structured string JSON]
Reports --> History[SHA-256-indexed history]AIDebug는 승인된 소프트웨어와 시스템에서만, 격리된 악성코드 분석 VM 또는 랩 내에서만 사용하세요.
신뢰할 수 없는 샘플을 분석하기 전에 전체 안전 모델, 보안 정책, 제한 사항 및 검증 계획을 읽으세요.
| 문서 | 목적 |
|---|---|
| 분석가 워크플로 | 반복 가능한 분석 프로세스 |
| 안전 모델 | 신뢰 경계 및 안전한 운영 |
| 검증 계획 | 테스트 가능한 기능 주장 |
| 샘플 증거 | 예시 스크린샷 및 모의 아티팩트 |
| 비교 | 범위 및 포지셔닝 |
| 릴리스 준비 | 재현 가능한 릴리스 게이트 |
| AIDebug 3.1 릴리스 노트 | 현재 소스 릴리스 변경 사항 |
| AIDebug 3.0 릴리스 노트 | 이전 게시 릴리스 변경 사항 |
| 변경 로그 | 버전 기록 |
빠른 로컬 검사를 실행합니다:
python -m ruff check .
python -m pytest -q
완전한 격리 릴리스 게이트를 실행합니다:
./scripts/release-readiness.sh
기여 지침은 CONTRIBUTING.md를 참조하세요. 이슈나 풀 리퀘스트에 라이브 악성코드, 자격 증명, 개인 사례 데이터 또는 편집되지 않은 증거를 첨부하지 마세요.
AIDebug는 MIT 라이선스로 배포됩니다.