gadievron/raptor

저자: Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake), Michael Bargury, John Cartwright
(@gadievron, @danielcuthbert, @thomasdullien, @mbrg, @grokjc)

라이선스: MIT. LICENSE 참조. CodeQL은 자체 라이선스를 가지며 상업적 사용을 허가하지 않음에 유의하십시오.

리포지토리: https://github.com/gadievron/raptor

RAPTOR는 Claude Code를 기반으로 구축된 자율 보안 연구 프레임워크입니다 (하지만 이에 종속되지는 않습니다. 자체 분석 레이어를 플러그인 할 수도 있습니다). 정적 분석, 바이너리 분석, LLM 기반 취약점 검증, 익스플로잇 생성, 패치 작성 등을 단일 워크플로우로 연결하여 코드베이스 또는 바이너리에 대해 실행할 수 있습니다.

이것은 완성된 소프트웨어가 아닙니다. 여가 시간에 만들어졌으며, 열정과 임시방편으로 유지되고 있지만, 충분히 잘 작동하기 때문에 사용을 멈출 수 없습니다. 더 개선하고 싶다면 PR을 열어주십시오.

RAPTOR는 Recursive Autonomous Penetration Testing and Observation Robot의 약자입니다. 저희는 정말로 이것을 RAPTOR라고 부르고 싶었습니다.

RAPTOR는 주로 AI가 생성한 코드입니다. 인간은 방향을 설정하고, 출력을 검토하며, 설계 결정을 내리고; AI가 구현을 작성합니다. 기계적 검증(테스트, 정적 분석, 코퍼스 보정)은 누가—또는 무엇이—코드를 작성했는지와 관계없이 품질 기준을 유지합니다.

Claude Code (활성 구독자: Max, Pro, Team 또는 Enterprise) 또는 Anthropic API 키가 필요합니다. 이것이 대화형 raptor 셸의 오케스트레이션 레이어입니다 -- 독립 실행형 CLI만 필요한 경우 선택 사항이며, 아래 '완전히 독립적으로 실행하기'를 참조하십시오.**Python 3.12+**와 **Node.js 18+**가 필요합니다. 정적 분석을 위해 Semgrep(pip install semgrep)이 필요합니다. CodeQL은 선택 사항이지만 권장됩니다.

분석 디스패치 레이어(개별 발견 사항을 분석하는 LLM)의 경우, Claude Code 자체가 기본적으로 모든 것을 처리합니다. 추가 API 키가 필요하지 않습니다. 만약 다중 모델 분석(예: Claude + GPT + Gemini)이나 완전히 로컬 환경 설정을 원한다면 다른 제공업체(provider)를 구성해야 합니다. 아래 '다른 LLM 사용하기' 섹션을 참조하십시오.

# 레포지토리 클론
git clone https://github.com/gadievron/raptor.git
cd raptor
...

raptor 런처는 세션을 시작하는 권장 방식이며, 어느 디렉토리에서든 작동합니다. 이는 RAPTOR 설치를 해결하고(이전에 실행했던 디렉토리를 기억하여 /scan과 같은 명령어가 해당 디렉토리를 기본값으로 사용하게 함), 사전 비행 신뢰 및 프로젝트 검사를 수행하고, 커버리지 추적 플러그인을 로드하며, Claude Code에 전달하기 전에 환경을 정리합니다. 또한 선택적인 대상 경로와 --project, --continue, --model과 같은 플래그도 받습니다. 자세한 내용은 raptor --help를 참조하십시오.

레포지토리 디렉토리 내부에서 단순히 claude를 실행하는 것도 작동합니다. Claude Code는 체크아웃된 곳에서 RAPTOR의 구성을 가져오지만, 런처가 수행하는 모든 것(사전 비행 검사, 커버리지 추적 등)은 건너뛰게 됩니다. 또한

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

컨테이너를 시작하려면:

docker run -it \
-v "$(pwd):/workspaces/raptor" \
raptor:latest

대상 폴더도 마운트하려면:

docker run -it \
-v "$(pwd):/workspaces/raptor" \
-v "/path/to/target-folder:/workspaces/target" \
...

rr 결정론적 디버거가 필요한 경우 --privileged를 추가하세요.

VS Code devcontainers도 지원됩니다. 대상 폴더를 마운트하려면 .devcontainer/devcontainer.json의 mounts 섹션에 추가하세요:

"mounts": [
// ...기존 항목...
"source=/path/to/target-folder,target=/workspaces/target,type=bind,consistency=cached"
...

그런 다음 VS Code에서 저장소를 열면 컨테이너에서 다시 열도록 요청할 것입니다:

cd /path/to/raptor
code .

어느 쪽이든, 컨테이너 내부에 들어가면 raptor를 실행하여 시작하세요.
가장 간단한 방법은 다음과 같습니다:

/scan /path/to/code

이 명령어는 대상에 대해 Semgrep(그리고 spatch가 설치된 경우 Coccinelle; CodeQL의 경우 --codeql 추가)을 실행하고, 발견 사항을 중복 제거하며, SARIF 보고서를 작성합니다. LLM 분석은 없으며, Claude Code를 넘어서는 API 키도 필요하지 않습니다. 일반적인 저장소에서는 몇 분 정도 걸립니다.

LLM 기반 검증을 추가하려면:

/agentic /path/to/code

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

비용 참고 사항: Claude Code 오케스트레이션 레이어는 사용자의 Claude 구독을 이용합니다. 분석 디스패치 레이어는 토큰당 과금이 발생하는 별도의 LLM API 호출을 수행합니다. 만약 Claude Code를 분석 모델로만 사용할 경우(기본 설정), 구독 외 추가 비용은 없습니다. 외부 모델(OpenAI, Gemini 등)을 구성할 경우, 해당 API 호출에 대한 비용은 각 제공업체에 청구됩니다.

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

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

| 분석(Analyze) |
기존 SARIF 결과를 LLM을 사용하여 재스캔 없이 분석
| 안정(Stable) |
/openant |
OpenAnt LLM 소스 코드 스캔: AST 분석 및 함수별 LLM 추론
| 베타(Beta) |
/sca |
소프트웨어 구성 분석: 의존성, 권고 사항, 공급망 신호, SBOM, 그리고 수정 패치
| 베타(Beta) |
/cve-diff |
OSV, NVD, GitHub, GitLab 전반에 걸쳐 CVE의 수정 커밋을 발견하고 비교
| 베타(Beta) |
/cve-env |
CVE가 영향을 미치는 애플리케이션이 패치 전 버전으로 실행되는 Docker 환경 구축 및 검증
| 실험적(Experimental) |
/exploit |
개념 증명(PoC) 익스플로잇 코드 생성
| 베타(Beta) |
/patch |
확인된 취약점에 대한 안전한 패치 생성
| 베타(Beta) |
/fuzz |
AFL++를 사용한 바이너리 퍼징 및 충돌 분석
| 안정(Stable) |
/crash-analysis |
C/C++ 충돌에 대한 자율적인 근본 원인 분석
| 안정(Stable) |
/oss-forensics |
GitHub 리포지토리에 대한 증거 기반 포렌식 조사
| 안정(Stable) |
/project |
실행을 구성하고 시간 경과에 따른 발견 사항을 추적하기 위한 명명된 작업 공간
| 안정(Stable) |
/describe |
대상 설명: 언어 혼합, 빌드 시스템, 도구 격차, 비용 추정치 (읽기 전용)
| 안정(Stable) |
/threat-model |
프로젝트별 위협 모델 생성, 검사 및 유지
| 안정(Stable) |
/sage |
영속 메모리 계층 (저장, 회상, 연결, 확증)
| 안정(Stable) |
/ask |
구성된 모든 LLM 모델에 자유 형식 프롬프트 전송
| 안정(Stable) |
/scorecard |
결정 클래스별 모델 신뢰성 검사
| 안정(Stable) |
/frida |
Frida를 통한 동적 계측
| 알파(Alpha) |
/web |
웹 애플리케이션 스캐닝: 크롤링, ffuf/nuclei 통합, 오라클 검증 주입, 블라인드 SSRF 콜백
| 베타(Beta) |

프로젝트를 생성하여 모든 실행 결과를 한 곳에 모으는 것부터 시작하세요:

/project create myapp --target /path/to/code # 프로젝트 먼저 생성
/project use myapp # 활성 프로젝트로 설정
/understand --map # 공격 표면 매핑
...

컴파일된 아티팩트의 경우, 동등한 시작 지점은 다음과 같습니다:

컴파일된 아티팩트의 경우, 동등한 시작 지점은 다음과 같습니다:

/binary investigate /path/to/binary # 증거 기반 바이너리 맵 구축
/binary graph <run-dir> --edges --json # 영속화된 그래프 질의
/binary trace-parser <run-dir> # 런타임 파서 증거 수집
...

/understand

라인 스캐닝이 시작되기 전에 진입점(entry points), 신뢰 경계(trust boundaries), 싱크(sinks)의 컨텍스트 맵을 구축합니다. /agentic

그런 다음 Semgrep과 CodeQL을 실행하고, 발견된 내용을 중복 제거하며, 각 항목을 익스플로잇 검증자 방법론(exploitation-validator methodology)을 사용하여 검증하기 위해 전송합니다:

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

• 단계 A: 패턴 자체가 취약점인지, 아니면 도구의 패턴 매칭 노이즈인지?
• 단계 B: 공격자가 그것에 도달하기 위해 무엇이 필요한지, 그리고 어떤 것이 방해하는가?
• 단계 C: 코드 경로가 실제로 존재하는가? 외부에서 도달할 수 있는가?
• 단계 D: 최종 호출 -- 이것은 테스트 코드인가, 비현실적인 전제 조건이 필요한가, 모델이 헤징(hedging)하고 있는가?
• 단계 E: 바이너리 익스플로잇 가능성 (컴파일된 아티팩트가 사용 가능한 경우)
• 단계 F: 자체 검토 -- 이전 단계에서 어떤 것이 헤징하거나 스스로 모순되었는가?

검증을 통과한 발견 사항은 익스플로잇 PoC(Proof-of-Concept)와 패치를 생성합니다. 마지막에는 교차 발견 분석이 실행되어 공유된 근본 원인 및 공격 체인을 찾습니다.

/validate

이전 스캔에서 이미 발견 사항을 가지고 있다면, 이 동일한 파이프라인을 독립적인 단계로 실행합니다.

컴파일된 아티팩트의 경우, /binary <경로>