╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║
║                                                                           ║
║             Autonomous Offensive/Defensive Research Framework             ║
║             Based on Claude Code (v3.1.0)                                 ║
║                                                                           ║
║             Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake)    ║
║             Michael Bargury, John Cartwright                              ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣤⣤⣀⣀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⣿⣿⠿⠿⠟
⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣀⣀⣀⣤⣴⣶⣶⣶⣤⣿⡿⠁⠀⠀⠀
⣀⠤⠴⠒⠒⠛⠛⠛⠛⠛⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⣿⣿⣿⡟⠻⢿⡀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⢿⣿⠟⠀⠸⣊⡽⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⣿⡁⠀⠀⠀⠉⠁⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⠿⣿⣧⠀ Get them bugs.....⠀⠀⠀⠀⠀

`raptor` 런처는 세션을 시작하는 권장 방법이며, 어느 디렉터리에서든 작동합니다. RAPTOR 설치를 확인하고, 실행한 디렉터리를 기억하며(`/scan` 같은 명령이 기본적으로 이 디렉터리를 대상으로 함), 사전 신뢰 및 프로젝트 검사를 실행하고, 커버리지 추적 플러그인을 로드하며, Claude Code에 넘기기 전에 환경을 정리합니다. 또한 선택적 대상 경로와 `--project`, `--continue`, `--model` 같은 플래그를 받습니다. 자세한 내용은 `raptor --help`를 참고하세요.

리포지터리 디렉터리 안에서 일반 `claude`를 실행하는 것도 작동합니다. Claude Code가 체크아웃에서 RAPTOR의 구성을 가져오기 때문입니다. 하지만 위에서 런처가 수행하는 모든 것을 건너뛰게 됩니다. 사전 검사도, 커버리지 추적도 없으며, "이 명령을 실행한 디렉터리"를 기본으로 하는 명령들이 그 디렉터리를 인식하지 못합니다.

**중요:** RAPTOR는 리포지터리 디렉터리에서 구성을 로드합니다. 다른 디렉터리에서 `claude`를 실행하면 RAPTOR가 아닌 일반 Claude Code가 실행됩니다. `raptor` 런처는 이러한 실패 모드를 완전히 피할 수 있습니다.

### 옵션 2: 컨테이너에서 실행 (권장)

컨테이너를 사용하는 것은 에이전트가 파일 시스템에서 접근하지 않기를 원하는 영역에 접근하는 것을 제한하고, 실행될 수 있는 악성 코드(예: 공급망 공격을 통한)의 영향을 제한하는 일반적인 보안 관행입니다. 이미지는 큽니다(약 6 GB). Microsoft Python 3.12 devcontainer에서 시작하여 정적 분석, 퍼징, 브라우저 자동화 도구를 추가합니다.

미리 빌드된 이미지를 가져올 수 있습니다:```bash
docker pull danielcuthbert/raptor:latest

이 이미지는 시작 시 RAPTOR 프레임워크(이 저장소)가 `/workspaces/raptor`에 마운트될 것으로 예상합니다. 선택적으로 로컬 분석을 위한 대상 폴더를 마운트할 수 있습니다.

컨테이너를 시작하려면:```bash
docker run -it \
  -v "$(pwd):/workspaces/raptor" \
  raptor:latest

`rr` 결정적 디버거가 필요하면 `--privileged`를 추가하세요.

VS Code devcontainer도 지원됩니다. 대상 폴더를 마운트하려면 `.devcontainer/devcontainer.json`의 `mounts` 섹션에 추가하세요:```jsonc
"mounts": [
  // ...existing entries...
  "source=/path/to/target-folder,target=/workspaces/target,type=bind,consistency=cached"
]

어느 쪽이든, 컨테이너 안에 들어가면 `raptor`를 실행하여 시작하세요.

---

## 첫 실행 시 예상할 수 있는 것

가장 간단하게 할 수 있는 일:```
/scan /path/to/code

이것은 전체 파이프라인을 실행합니다: 스캔, 중복 제거, 그런 다음 각 발견 사항을 검증 단계(A-F)를 통해 전송합니다. 약 50개의 발견 사항이 있는 중간 규모의 코드베이스에서 10-30분과 분석 계층 LLM 비용으로 $2-8이 소요될 것으로 예상됩니다(모델에 따라 다름). 기본 비용 상한은 실행당 $10이며, `--max-cost-usd`로 조정할 수 있습니다.

**비용 참고:** Claude Code 오케스트레이션 계층은 귀하의 Claude 구독을 사용합니다. 분석 디스패치 계층은 토큰당 청구되는 별도의 LLM API 호출을 수행합니다. 분석 모델로 Claude Code만 사용하는 경우(기본값), 구독 외에 추가 비용이 없습니다. 외부 모델(OpenAI, Gemini 등)을 구성하는 경우, 해당 API 호출은 해당 제공업체에 청구됩니다.

---

## 보안 모델

RAPTOR는 LLM이 생성한 코드를 실행하고 신뢰할 수 없는 저장소를 분석합니다. 신뢰할 수 없는 콘텐츠를 처리하는 하위 프로세스는 Linux 네임스페이스, Landlock, seccomp를 사용하여 샌드박스 처리됩니다. 샌드박스는 네트워크 접근을 차단하고, 파일 시스템 가시성을 제한하며, 리소스 소비를 제한합니다. 전체 위협 모델과 구성은 `docs/sandbox.md`를 참조하세요.

런처 체인에 코드를 주입할 수 있는 환경 변수는 시작 시 제거됩니다(`core/security/_dangerous_env_strip.sh`). 스캔된 저장소의 파일 경로는 셸 문자열에 절대 보간되지 않습니다 — 모든 하위 프로세스 호출은 리스트 기반 인수를 사용합니다.

---

## RAPTOR가 할 수 있는 일

| 명령어 | 수행하는 작업 | 상태 |
|---------|-------------|--------|
| `/agentic` | 전체 자율 워크플로: 스캔, 검증, 익스플로잇, 패치 | 안정 |
| `/scan` | Semgrep 및 CodeQL을 사용한 정적 분석 | 안정 |
| `/understand` | 공격 표면 매핑, 데이터 흐름 추적, 취약점 변종 탐색 | 안정 |
| `/binary` | 블랙박스 바이너리 조사, 런타임 증거, 그래프 쿼리 및 핸드오프 | 베타 |
| `/ghidra` | Ghidra RE 브리지: `.gpr` 프로젝트 연결/가져오기, 버전 간 diff, 발견 사항 내보내기 | 베타 |
| `/audit` | 가설 기반, 도구 기반 체계적 코드 리뷰 | 베타 |
| `/review` | 감사 상태 쿼리: 발견 사항, 격차, 커버리지, 운영자 노트 | 안정 |
| `/annotate` | 함수별 자유 형식 산문 주석 첨부(운영자 리뷰 노트) | 안정 |
| `/validate` | 다단계 익스플로잇 가능성 검증 파이프라인(단계 0-F) | 안정 |
| `/diagram` | `/understand` 및 `/validate` JSON 출력에서 Mermaid 시각적 맵 생성 | 베타 |
| `/codeql` | SMT 데이터 흐름 사전 스크리닝을 통한 CodeQL 전용 심층 분석 | 안정 |
| `/analyze` | 재스캔 없이 LLM으로 기존 SARIF 발견 사항 분석 | 안정 |
| `/openant` | OpenAnt LLM 소스 코드 스캔: AST 분석 및 함수별 LLM 추론 | 베타 |
| `/sca` | 소프트웨어 구성 분석: 의존성, 권고, 공급망 신호, SBOM, 수정 사항 | 베타 |
| `/cve-diff` | OSV, NVD, GitHub, GitLab 전반에서 CVE의 수정 커밋 발견 및 diff | 베타 |
| `/cve-env` | CVE의 영향을 받는 애플리케이션을 패치 전 버전으로 실행하는 Docker 환경 구축 및 검증 | 실험적 |
| `/exploit` | 개념 증명 익스플로잇 코드 생성 | 베타 |
| `/patch` | 확인된 취약점에 대한 보안 패치 생성 | 베타 |
| `/fuzz` | AFL++ 및 크래시 분석을 통한 바이너리 퍼징 | 안정 |
| `/crash-analysis` | C/C++ 크래시에 대한 자율 근본 원인 분석 | 안정 |
| `/oss-forensics` | GitHub 저장소에 대한 증거 기반 포렌식 조사 | 안정 |
| `/project` | 실행을 구성하고 시간 경과에 따른 발견 사항을 추적하기 위한 명명된 워크스페이스 | 안정 |
| `/describe` | 대상 설명: 언어 구성, 빌드 시스템, 도구 격차, 비용 추정(읽기 전용) | 안정 |
| `/threat-model` | 프로젝트별 위협 모델 생성, 검사, 유지 관리 | 안정 |
| `/sage` | 영구 메모리 계층(저장, 회상, 연결, 확증) | 안정 |
| `/ask` | 구성된 모든 LLM 모델에 자유 형식 프롬프트 전송 | 안정 |
| `/scorecard` | 결정 클래스 전반에 걸친 모델별 신뢰성 검사 | 안정 |
| `/frida` | Frida를 통한 동적 계측 | 알파 |
| `/web` | 웹 애플리케이션 스캔: 크롤링, ffuf/nuclei 통합, 오라클 검증 주입, 블라인드 SSRF 콜백 | 베타 |

---

## 파이프라인 작동 방식

모든 실행이 한 곳에 모이도록 프로젝트를 생성하는 것으로 시작하세요:```
/project create myapp --target /path/to/code   # create a project first
/project use myapp                             # set it as active
/understand --map                              # map the attack surface
/agentic --threat-model --validate             # map, model, scan, validate
/project findings                              # review everything in one place

`/understand`는 스캔이 한 줄이라도 실행되기 전에 진입점, 신뢰 경계, 싱크에 대한 컨텍스트 맵을 구축합니다. 그런 다음 `/agentic`이 Semgrep과 CodeQL을 실행하고, 발견 사항을 중복 제거한 뒤, exploitation-validator 방법론을 사용해 각각을 검증용으로 디스패치합니다:

`--threat-model`을 사용하면 RAPTOR가 먼저 맵을 실행하고, 프로젝트에 아직 `threat-model.json`과 `THREAT_MODEL.md`가 없으면 생성한 다음, 압축된 버전을 `/understand`, 자율 분석, `/validate`에 공급합니다. 기존 프로젝트 위협 모델은 `--threat-model-refresh`를 전달하지 않는 한 보존되며, 오래된 폴백 맵은 `--threat-model-use-stale`을 명시적으로 전달하지 않는 한 거부됩니다. 또한 매핑된 미검사 흐름을 후보 SARIF로 전환하여 스캐너가 놓친 부분이 실행을 죽이지 않도록 합니다. 이는 운영자 소유의 컨텍스트이지 마법 같은 증명이 아닙니다: 발견 사항에는 여전히 코드 증거 또는 오라클 기반 확인이 필요합니다. `docs/threat-model.md`를 참조하세요.

- Stage A: 이 패턴이 실제로 취약점인가, 아니면 도구의 패턴 매칭 노이즈인가?
- Stage B: 공격자가 여기에 도달하려면 무엇이 필요하며, 무엇이 방해하는가?
- Stage C: 이 코드 경로가 실제로 존재하는가? 외부에서 도달할 수 있는가?
- Stage D: 최종 판단 -- 이것이 테스트 코드인가, 비현실적인 전제 조건이 필요한가, 모델이 얼버무리고 있는가?
- Stage E: 바이너리 익스플로잇 가능성 (컴파일된 아티팩트가 있을 때)
- Stage F: 자기 검토 -- 이전 단계 중 얼버무리거나 스스로 모순된 곳이 있었는가?

검증을 통과한 발견 사항에는 익스플로잇 PoC와 패치가 생성됩니다. 공유 근본 원인과 공격 체인을 찾기 위해 마지막에 교차 발견 분석이 실행됩니다.

`/validate`는 이전 스캔에서 이미 발견 사항을 가지고 있는 경우 이 동일한 파이프라인을 독립 실행 단계로 실행합니다.

컴파일된 아티팩트의 경우, `/binary <path>`는 이제 운영자에게 원시 리버스 엔지니어링 아티팩트 더미를 쏟아내는 대신 증거 우선 조사를 실행합니다. 내부적으로는 여전히 파일 메타데이터, 임포트, radare2 xref로부터 SHA-256 바인딩 매니페스트, 증거 원장, 컨텍스트 맵, 체크리스트, SQLite 그래프를 구축합니다. Mach-O 앱은 슬라이스 인벤토리, 번들 메타데이터, Objective-C / Swift 클래스 셀렉터도 얻으며, 가치 높은 의사코드는 실행 중에 사라지지 않고 영속화됩니다. PE DLL 익스포트, Windows 드라이버 디스패처, Linux 커널 모듈 ioctl 핸들러도 자체 인그레스 후보로 처리되며, PE 아키텍처는 추측이 아니라 COFF 헤더에서 읽습니다. 그런 다음 조사 계층이 해당 그래프를 쿼리하고, 일반 싱크 리드보다 외부 인그레스를 먼저 순위화하며, 선언된 헬퍼/형제 바이너리를 발견하고, 사실, 구조적 추론, 입증되지 않은 가설로 나뉜 압축 보고서를 작성합니다. 이후 Frida 관찰, 퍼즈 크래시 증거, 명시적 Z3 검사, 바이너리 디프가 더 강한 증거를 추가할 수 있습니다. RAPTOR는 또한 경계가 정해진 인그레스-투-파서 후보를 복구하는 데 필요한 내부 호출 그래프를 유지하므로, 앱 콜백이 실제로 `XML_Parse`, `d2i_X509`, `jpeg_read_header` 또는 다른 실제 파서 표면을 호출하는 내부 함수로 좁혀질 수 있으며, 그것이 오염 증명인 척하지는 않습니다. `/binary trace-parser <run-dir>`는 명시적인 동적 후속 단계입니다: 좁은 Frida 파서 트레이스를 실행한 다음, 동일한 컨텍스트 맵, 핸드오프, 그래프, 조사 보고서를 제자리에서 갱신합니다. `/binary investigate --active`는 먼저 매핑하고 구체적인 하네스 경계가 존재할 때만 실제 퍼즈 캠페인을 시작합니다; 앱, DLL, 드라이버 대상은 대신 하네스 또는 스냅샷 단계를 거칩니다. `/binary harness`는 선택된 인그레스에 대해 증거 기반 하네스 스펙을 작성하고, ABI 또는 IOCTL 계약이 명시적일 때만 후보 소스를 출력합니다. 그것은 "`memcpy`가 존재한다"에서 "이것은 익스플로잇 가능하다"로 얼렁뚱땅 넘어가지 않습니다: 임포트, 셀렉터, 호출 엣지는 무언가 기계적인 것이 더 많은 것을 증명할 때까지 후보로 남습니다. `docs/binary-analysis.md`를 참조하세요.

---

## 소프트웨어 구성 분석

`/sca`는 프로젝트의 의존성 및 공급망 측면을 분석합니다. 단순한 requirements 파일 CVE 조회가 아닙니다: RAPTOR는 매니페스트, 락파일, 인라인 설치 명령, 워크플로 의존성, 컨테이너/베이스 이미지 패키지 소스를 발견한 다음, 이를 단일 의존성 뷰로 정규화합니다.

스캔은 의존성을 OSV 권고, CISA KEV, EPSS, CISA Vulnrichment/SSVC, 도달 가능성, 익스플로잇 증거 신호, 위생 검사, 공급망 휴리스틱, 라이선스 정책 발견 사항, 선택적 LLM 검토/트리아지로 보강합니다. RAPTOR 네이티브 발견 사항과 SBOM 및 CI 친화적 출력을 생성합니다:

- `findings.json` - 표준 RAPTOR 발견 사항
- `report.md` - 사람이 읽을 수 있는 요약
- `sbom.cdx.json` - VEX 데이터가 포함된 CycloneDX SBOM
- `findings.sarif` - GitHub/GitLab 코드 스캐닝 출력

일반적인 명령:```bash
python3 raptor.py sca --repo /path/to/project
python3 raptor.py sca --repo /path/to/project --no-llm
python3 raptor.py sca --repo /path/to/project --fail-on-severity high --fail-on-kev
python3 raptor.py sca --repo /path/to/project fix
python3 raptor.py sca check PyPI django 4.2.10

캐시가 채워지면 스캐너는 팩 ID를 로컬 파일로 해석하며 네트워크 호출이 발생하지 않습니다. 캐시가 없으면 RAPTOR는 스캔 시점에 semgrep.dev에서 레지스트리 팩을 가져오려고 시도합니다. 오프라인인 경우 캐시되지 않은 팩을 우아하게 건너뛰고 사용자 정의 규칙만으로 실행합니다.

CodeQL은 CLI와 쿼리 팩을 다운로드하기 위한 초기 설정 중에만 네트워크 액세스가 필요합니다. 설치가 완료되면 오프라인으로 실행됩니다.

---

## 사용자 정의 규칙

RAPTOR는 200개 이상의 사용자 정의 정적 분석 규칙을 제공하며, 오탐을 제거하기 위해 적대적으로 테스트되었습니다:

- **Semgrep (~150개 규칙)** — Python, Go, Java, JS/TS를 위한 오염 추적(taint-tracking) 및 패턴 규칙. SQLi, XSS, SSRF, SSTI, 명령 주입, 역직렬화, XXE, LDAP/NoSQL 주입, 경로 순회, 오픈 리다이렉트, 로그/헤더 주입, eval 주입, ReDoS, 프로토타입 오염, JWT 잘못된 구성, 취약한 암호화, 안전하지 않은 TLS, 하드코딩된 비밀을 다룹니다.
- **Coccinelle (68개 규칙)** — C/C++를 위한 구조적 매칭. 메모리 안전성(double free, use-after-free, 비기반 포인터 해제, 스택 배열 해제, mmap된 메모리, use-after-close), 정수 버그(오버플로, 부호 확장, 이중 sizeof), 리소스 누수(popen/fclose 불일치, fdopendir 이중 닫기), 버퍼 처리(NUL 없는 strncpy, copy_user 크기 불일치, malloc/strlen 오프바이원), 시그널 핸들러 안전성, API 오용(fcntl 플래그 도메인, SIGKILL/SIGSTOP, 이중 바이트 스왑, inet_ntoa 정적 버퍼), 컴파일러 데드 스토어 제거, 커널 IS_ERR/PTR_ERR 혼동, 포맷 문자열 주입, TOCTOU 경쟁 조건 등.
- **CodeQL (8개 쿼리)** — C++(포맷 문자열 주입, 정수 잘림, use-after-move, 반복자 무효화)와 Java(XXE, 안전하지 않은 역직렬화, 로그 주입, Spring SSRF)를 위한 절차 간 오염 추적.

규칙을 직접 살펴보세요: `engine/semgrep/rules/`, `engine/coccinelle/rules/`, `engine/codeql/queries/`. 이들은 RAPTOR가 가져오는 Semgrep 레지스트리 팩(`p/security-audit`, `p/owasp-top-ten`, `p/secrets`는 항상, `p/command-injection`, `p/jwt`, `p/xss` 같은 정책 그룹별 팩은 추가로)을 보완합니다 — 중복은 최소합니다.

---

## RAPTOR가 스스로를 검사하는 방법

RAPTOR는 자체 보안 도구 상당 부분을 도그푸딩(dogfood)하지만, 실제로 PR을 차단하는 것과 우리를 정직하게 유지하기 위해 백그라운드에서 실행되는 것을 솔직히 구분할 가치가 있습니다. 이 중 일부는 하드 게이트이고, 일부는 예약된 검사이며, 일부는 우리가 상황을 악화시켰을 때를 알 수 있도록 유지하는 벤치마크일 뿐입니다. 실제 매개변수와 검사 재현 방법을 포함한 더 자세한 분석은 `docs/ci-controls.md`에 있습니다.

| 제어 | 검사 내용 | 트리거 | 구성 / 증거 |
|---|---|---|---|
| Ruff | Python 정확성 린팅(`F401`, `F811`, `F821`, `F841`) | PR diff 게이트, 주간 전체 트리 감사 | `pyproject.toml`, `.github/workflows/lint.yml` |
| Pytest | 빠른 단위/통합 경계, 하위 시스템별 계층(임포트 그래프 디스패치 경유), 프롬프트 엔벨로프 감사 | PR, `main` 푸시, 머지 큐, 예약된 전체 스위트 | `pytest.ini`, `.github/workflows/tests.yml`, `.github/workflows/nightly.yml` |
| CodeQL Advanced | 임포트 그래프 범위 축소를 통한 Python, C/C++, GitHub Actions 코드 스캐닝 | PR, `main` 푸시, 머지 큐, 주간 스케줄 | `.github/workflows/codeql.yml`, `.github/codeql/codeql-config.yml` |
| 워크플로 강화 | SHA 고정 서드파티 Actions, 최소 권한 권한, 명령 메타데이터 린팅 | 모든 워크플로 변경 및 모든 린트 실행 | `.github/workflows/`, `.github/scripts/check_command_metadata.py` |
| 코퍼스 레이블 린트 | 감사 코퍼스 레이블 스키마 검증 및 업스트림 핀 검증 | PR(변경된 레이블), 주간 전체 스윕 | `.github/workflows/corpus-labels.yml` |
| RAPTOR SCA PR 게이트 | PR로 인해 도입된 의존성 및 공급망 회귀 | 매니페스트 / 잠금 파일 / 워크플로 변경 | `.github/workflows/sca-pr-gate.yml` |
| RAPTOR SCA 자체 범프 | 기계적 의존성 강화 및 안전한 업그레이드 제안 | 주간 스케줄, 수동 실행 | `.github/workflows/sca-self-bump.yml` |
| SCA 침해 코퍼스 | 알려진 의존성 침해가 여전히 예상 신호를 트리거하는지 여부 | 주간 스케줄, 관련 PR 변경 | `test/data/sca-e2e/compromise-corpus/`, `.github/workflows/sca-compromise-check.yml` |
| 저장소 불변식 탐지기 | 데드 코드 / 잘못된 호출 탐지, 환경 변수 문서 드리프트, 어휘 목록 가드레일, 정규 JSON 바이트 형식, 선택적 의존성 임포트 린트 | PR 게이트(`lint.yml` `repo-invariants` 작업), 일일 스윕 | `.github/workflows/lint.yml`, `.github/workflows/miswiring-scan.yml`, `.github/scripts/*_baseline.json` |
| SCA 캘리브레이션 + 스트레스 코퍼스 | 위험 점수 및 파서 커버리지가 시간이 지남에 따라 드리프트하는지 여부 | 주간 / 월간 예약 작업 | `packages/sca/data/calibration/`, `.github/workflows/refresh-sca-calibration.yml`, `.github/workflows/sca-stress-sweep.yml` |
| 데이터플로우 코퍼스 | 검증기 동작에 대한 정밀도 / 재현율 / FP 범주 추적 | 개발자 실행 벤치마크 및 코퍼스 테스트 | `core/dataflow/corpus/`, `core/dataflow/scripts/corpus-metrics` |
| CI 제어 문서 가드 | 문서화된 경로 존재, ruff 구성 일치, README가 문서로 연결 | PR | `.github/tests/test_ci_controls_docs.py` |

현재 강제되지 않음: `mypy`는 `pyproject.toml`에 고정되어 있지만 아무것도 차단하지 않습니다. Ruff 포맷팅은 강제되지 않습니다. Semgrep은 RAPTOR의 스캐너 표면의 일부이지만, 아직 "RAPTOR로 RAPTOR를 스캔"하는 전용 Semgrep 워크플로가 없습니다.

---

## 다른 LLM 사용하기

RAPTOR에는 두 개의 별도 모델 계층이 있으며, 무엇이든 변경하기 전에 두 계층이 어떻게 작동하는지 아는 것이 좋습니다.

**오케스트레이션 계층**은 Claude Code입니다 — 하지만 대화형 `raptor` 셸(이 대화형, 슬래시 명령 계층)에만 해당합니다. CLAUDE.md, 스킬, 명령은 모두 거기서 Claude Code 지침으로 실행됩니다. 해당 계층을 오케스트레이션하는 Claude 모델을 변경하려면 Claude Code의 `--model` 플래그나 세션 내 `/model` 명령을 사용하세요. 이 계층을 전혀 원하지 않으면 아래의 [완전 독립 실행](#running-fully-standalone-no-claude-code)을 참조하세요.

**분석 디스패치 계층**은 개별 취약점 발견을 분석하는 LLM입니다. 이는 오케스트레이션 계층과 별개이며 지원되는 모든 제공자가 될 수 있습니다. `~/.config/raptor/models.json`에서 구성하세요:```json
{
  "models": [
    {
      "provider": "anthropic",
      "model": "claude-opus-4-6",
      "api_key": "sk-ant-...",
      "role": "analysis"
    },
    {
      "provider": "openai",
      "model": "gpt-5.4",
      "api_key": "sk-...",
      "role": "analysis"
    },
    {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "api_key": "sk-ant-...",
      "role": "aggregate"
    }
  ]
}

모델 역할을 사용하면 서로 다른 작업에 서로 다른 모델을 할당할 수 있습니다:

| 역할 | 수행하는 작업 |
|------|-------------|
| `analysis` | 각 발견 사항을 검증하고 분석합니다 (단계 A-F) |
| `code` | 익스플로잇 PoC와 패치 코드를 작성합니다 |
| `consensus` | 진양성에 대한 제2의 의견 투표 |
| `aggregate` | 선택 사항. 결정론적 다중 모델 상관관계 위에 LLM이 작성한 서술형 종합을 추가하여 `aggregation.json`과 최종 `agentic-report.md`에 기록합니다 |
| `fallback` | 기본 모델이 실패하거나 속도 제한에 도달할 경우 사용됩니다 |

역할이 설정되지 않은 경우 목록의 첫 번째 모델이 모든 것을 처리합니다. 다중 모델
소스 코드 분석의 경우 두 개 이상의 `analysis` 모델을 구성하세요 — 기본적으로
결정론적 상관관계를 얻게 됩니다. `aggregate` 역할은 선택 사항이며 그 위에
LLM이 작성한 요약을 추가합니다:```bash
python3 raptor.py agentic --repo /code \
  --model claude-opus-4-6 \
  --model gpt-5.4 \
  --aggregate claude-sonnet-4-6

Ollama는 분석에 적합합니다. 익스플로잇/패치 코드 생성의 신뢰성은 로컬 모델의 고정된 속성이라기보다 모델 규모와 양자화에 따라 달라집니다. LLM 가이드의 [Quality Tradeoffs](https://github.com/gadievron/raptor/blob/main/llm.md#quality-tradeoffs)를 참고하고, `/scorecard`에서 특정 모델이 실제로 무엇을 측정하는지 확인하세요.

### 완전 독립 실행 (Claude Code 없이)

`bin/raptor` -- 배너와 슬래시 명령이 있는 대화형 셸, 즉 이 대화 계층 -- 은 Claude Code CLI로 바로 exec되며 항상 자체 로그인이 필요합니다. 그 아래의 실제 메커니즘은 그렇지 않습니다. `python3 raptor.py <mode>`는 Claude Code 의존성이 전혀 없는 순수 Python CLI입니다.```bash
# No `claude` process involved at any point
python3 raptor.py doctor                        # status check -- explicitly "no claude needed"
python3 raptor.py agentic --repo /path/to/code   # scan -> dedup -> analysis
python3 raptor.py scan --repo /path/to/code

`models.json` / `OLLAMA_HOST`를 로컬 Ollama 인스턴스로 지정하면(위 참조) 이 전체 경로는 Anthropic과 전혀 통신하지 않습니다 -- 에어갭 환경이나 로컬 전용 하드웨어에 유용합니다. 대화형 슬래시 명령 계층(이 채팅)은 잃게 되지만, 스캔/분석/익스플로잇 파이프라인 자체는 영향을 받지 않습니다.

### Fast-tier 단락 평가 + 모델 스코어카드

분석 계층 모델에 동일 제공자의 더 저렴한 형제 모델이 있을 때(Anthropic Opus → Haiku, OpenAI 5.x → 4o-mini, Gemini Pro → Flash-Lite, Mistral Large → Small), RAPTOR는 이를 서브스트레이트에 연결된 소비자들(현재는 codeql; SCA 및 기타는 후속 작업으로 추가 예정)에 대한 사전 필터로 사용합니다. 저렴한 모델은 **확신 있는 오탐**에 대해서만 단락 평가를 수행하며, 모호한 사례와 확신 있는 진탐은 항상 전체 분석을 실행합니다. 신뢰는 `(model, decision_class)` 셀 단위로 누적됩니다 — RAPTOR는 저렴한 모델과 전체 분석 간의 일치 여부를 기록하고, 해당 셀의 미탐률에 대한 Wilson 95% 상한이 5% 이하로 떨어질 때만 단락 평가를 수행합니다.

모델이 어떤 부분에 강한지 확인하려면 `/scorecard`를 사용하세요(또는 직접: `libexec/raptor-llm-scorecard list`). 스코어카드는 전역적이며(교훈이 프로젝트 간에 유지됨) `out/llm_scorecard.json`에 저장됩니다.

---

## 프로젝트

프로젝트가 없으면 각 실행은 `out/` 아래에 자체 타임스탬프 디렉터리를 갖습니다. 프로젝트가 있으면 모든 것이 한 곳에 모이고, 병합된 발견 사항, 커버리지 추적, 실행 간 diff를 얻을 수 있습니다.```bash
/project create myapp --target /path/to/code -d "Short description"
/project use myapp

/scan
/understand --map
/validate

/project status                # all runs, pass/fail, timestamps
/project findings              # merged findings across all runs
/project findings --detailed   # per-finding detail
/project coverage --detailed   # which files were reviewed
/project diff myapp run1 run2  # compare two runs
/project report                # full merged report
/project clean --keep 3        # remove old runs, keep the last 3
/project export myapp /tmp/myapp.zip
/project none                  # clear active project

이 분리는 Python 계층을 CI 파이프라인(`python3 raptor.py scan --repo ...`)에서 실행하여 Claude Code 없이 구조화된 SARIF 출력을 얻거나, 전체 에이전트 워크플로와 함께 대화식으로 실행할 수 있다는 것을 의미합니다.

---

## OSS 포렌식

`/oss-forensics`는 GitHub API, GH Archive(BigQuery를 통한 불변 이벤트 이력), Wayback Machine, 로컬 git 이력 등 여러 소스의 증거를 사용하여 공개 GitHub 저장소를 조사합니다. 증거 수집부터 가설 형성, 최종 포렌식 보고서에 이르기까지 구조화된 파이프라인을 실행합니다.

BigQuery 접근을 위해 `GOOGLE_APPLICATION_CREDENTIALS`가 필요합니다. 자세한 내용은 `.claude/commands/oss-forensics.md`를 참조하세요.

---

## 전문가 페르소나

여덟 가지 전문가 페르소나를 필요할 때 사용할 수 있습니다. 발견 사항에 대해 다른 관점이나 특정 기법을 원할 때 하나를 로드하세요:```
Exploit Developer (Mark Dowd)                  Exploit PoC generation
Crash Analyst (Charlie Miller / Halvar Flake)  Crash analysis and exploitability assessment
Security Researcher                            General adversarial code review
Patch Engineer                                 Secure fix generation
Penetration Tester                             Realistic attack scenario assessment
Web Researcher (James Kettle)                  Web endpoint research (smuggling, cache poisoning, SSRF)
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption

`/web`, Z3, SAGE 및 클라우드 제공자 SDK를 선택적 추가 기능으로 유지하면 기본 RAPTOR 설치가 필요 이상으로 무겁고 취약해지는 것을 방지할 수 있습니다.