╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║
║                                                                           ║
║             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: 컨테이너에서 실행 (권장)

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

사전 빌드된 이미지를 내려받을 수 있습니다:```bash
docker pull danielcuthbert/raptor:latest

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

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

`--privileged`를 추가하면 `rr` 결정적 디버거가 필요할 때 사용할 수 있습니다.

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 발견 사항 분석 | 안정 |
| `/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 xrefs에서 SHA-256 바인딩 매니페스트, 증거 원장, 컨텍스트 맵, 체크리스트, SQLite 그래프를 구축합니다. Mach-O 앱은 슬라이스 인벤토리, 번들 메타데이터, Objective-C / Swift 클래스 셀렉터도 얻으며, 고가치 의사 코드는 실행 중에 사라지지 않고 유지됩니다. PE DLL 내보내기, Windows 드라이버 디스패처, Linux 커널 모듈 ioctl 핸들러도 각각 자체 수신 후보로 처리되며, PE 아키텍처는 추측이 아닌 COFF 헤더에서 읽습니다. 조사 레이어는 그런 다음 해당 그래프를 쿼리하고, 일반 싱크 리드보다 외부 수신을 우선순위로 지정하며, 선언된 헬퍼/형제 바이너리를 발견하고, 사실, 구조적 추론, 입증되지 않은 가설로 나뉜 간결한 보고서를 작성합니다. Frida 관찰, 퍼즈 크래시 증인, 명시적 Z3 검사, 바이너리 diff는 나중에 더 강력한 증거를 추가할 수 있습니다. 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는 오탐(false positive)을 제거하기 위해 적대적으로 테스트된 200개 이상의 사용자 정의 정적 분석 규칙을 제공합니다:

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

규칙을 직접 살펴보세요: `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는 자체 보안 도구를 상당 부분 자체적으로 사용(dogfooding)하지만, 실제로 PR을 차단하는 것과 단지 우리를 정직하게 유지하기 위해 백그라운드에서 실행되는 것에 대해 솔직하게 설명할 가치가 있습니다. 일부는 엄격한 게이트이고, 일부는 예약된 검사이며, 일부는 상황이 악화되었을 때를 알 수 있도록 유지하는 벤치마크에 불과합니다. 실제 매개변수와 검사 재현 방법을 포함한 더 자세한 내용은 `docs/ci-controls.md`에 있습니다.

| 제어 항목 | 검사 내용 | 트리거 | 구성 / 증거 |
|---|---|---|---|
| Ruff | Python 정확성 린팅(`F401`, `F811`, `F821`, `F841`) | PR diff 게이트 + 주간 전체 트리 감사 | `pyproject.toml`, `.github/workflows/lint.yml` |
| Pytest | 빠른 단위/통합 경계, 하위 시스템별 계층(import-graph 디스패치 기반), 프롬프트 봉투 감사 | PR, `main` 푸시, 병합 대기열, 예약된 전체 스위트 | `pytest.ini`, `.github/workflows/tests.yml`, `.github/workflows/nightly.yml` |
| CodeQL Advanced | import-graph 범위 축소를 통한 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` |
| 오배선 스캔 | 죽은 코드 / 잘못된 호출 감지, 환경 변수 문서 드리프트, 어휘 목록 가드레일, 선택적 종속성 import 린트 | 일일 일정 | `.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`는 `requirements-dev.txt`에 설치되어 있지만 아무것도 차단하지 않습니다. Ruff 포맷팅은 적용되지 않습니다. Semgrep은 RAPTOR의 스캐너 표면의 일부이지만, 아직 전용 "RAPTOR로 RAPTOR 스캔" Semgrep 워크플로는 없습니다.

---

## 다른 LLM 사용하기

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

**오케스트레이션 계층**은 항상 Claude Code입니다. CLAUDE.md, 스킬, 명령은 모두 Claude Code 지침으로 실행됩니다. RAPTOR를 오케스트레이션하는 Claude 모델을 변경하려면 Claude Code의 `--model` 플래그 또는 세션 내 `/model` 명령을 사용하세요.

**분석 디스패치 계층**은 개별 취약점 발견 사항을 분석하는 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` | 실제 양성(true positive)에 대한 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는 분석에는 적합하지만 신뢰할 수 없는 익스플로잇 및 패치 코드를 생성합니다. 코드 생성 작업에는 프론티어 모델을 사용하세요.

### Fast-tier 단락 회로 + 모델 스코어카드

분석 계층 모델에 동일 공급업체의 더 저렴한 형제 모델(Anthropic Opus → Haiku, OpenAI 5.x → 4o-mini, Gemini Pro → Flash-Lite, Mistral Large → Small)이 있는 경우, RAPTOR는 이를 서브스트레이트에 연결되는 컨슈머(codeql 현재, SCA 및 기타는 후속 업데이트로 추가 예정)의 사전 필터로 사용합니다. 저렴한 모델은 **확실한 false positive**에서만 단락 회로를 수행하며, 모호한 사례와 확실한 TP는 항상 전체 분석을 실행합니다. 신뢰도는 `(model, decision_class)` 셀별로 누적됩니다. RAPTOR는 저렴한 모델과 전체 분석 간의 일치 여부를 기록하고, 셀의 miss-rate에 대한 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`를 참조하세요.

---

## 전문가 페르소나

필요할 때마다 7가지 전문가 페르소나를 사용할 수 있습니다. 발견 사항이나 특정 기법에 대해 다른 관점이 필요할 때 하나를 로드하세요.```
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
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption