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

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

Если добавить `bin/` в `PATH` (или создать симлинк `bin/raptor` где-нибудь в `PATH`), вы сможете запускать `raptor` из любого каталога — лаунчер определяет расположение установки RAPTOR и автоматически настраивает рабочую директорию.

**Важно:** RAPTOR загружает свою конфигурацию из директории репозитория. Если вы запустите `claude` из другого каталога, вы получите обычный Claude Code, а не RAPTOR. Либо сначала перейдите в репозиторий (`cd`), либо используйте лаунчер `raptor`.

### Вариант 2: Devcontainer (рекомендуется)

Всё предустановлено. Откройте в VS Code через **Dev Containers: Open Folder in Container** или потяните предсобранный образ:```bash
docker pull danielcuthbert/raptor:latest
docker run --privileged -it -v "$(pwd):/workspaces/raptor" danielcuthbert/raptor:latest

Флаг `--privileged` требуется для детерминированного отладчика `rr`. Образ большой (около 6 ГБ). Он основан на devcontainer Microsoft Python 3.12 и добавляет инструменты статического анализа, фаззинга и автоматизации браузера.

Попав внутрь, просто скажите "hi", чтобы начать, или переходите сразу к команде.

---

## Что ожидать при первом запуске

Самое простое, что вы можете сделать:```
/scan /path/to/code

Это запускает полный конвейер: сканирование, дедупликация, затем отправка каждого найденного через этапы валидации (A-F). На кодовой базе среднего размера с ~50 находками ожидайте 10-30 минут и 2-8 долларов затрат на уровне анализа LLM (в зависимости от модели). Лимит стоимости по умолчанию — $10 за запуск; настройте с помощью `--max-cost-usd`.

**Примечание о стоимости:** Оркестрационный слой Claude Code использует вашу подписку Claude. Слой диспетчеризации анализа совершает отдельные вызовы API LLM, которые оплачиваются за токен. Если вы используете только 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` | Исследование бинарников методом чёрного ящика, данные времени выполнения, графовые запросы и передача | Бета |
| `/validate` | Многоэтапный конвейер валидации эксплуатируемости (этапы 0-F) | Стабильный |
| `/codeql` | Углублённый анализ только с помощью CodeQL с предварительной фильтрацией потоков данных на основе SMT | Стабильный |
| `/sca` | Анализ состава ПО: зависимости, рекомендации, сигналы цепочки поставок, SBOM и исправления | Бета |
| `/exploit` | Генерация кода эксплойта для подтверждения концепции | Бета |
| `/patch` | Генерация безопасных исправлений для подтверждённых уязвимостей | Бета |
| `/fuzz` | Фаззинг бинарников с помощью AFL++ и анализ сбоев | Стабильный |
| `/crash-analysis` | Автономный анализ первопричин сбоев C/C++ | Стабильный |
| `/oss-forensics` | Форензика на основе доказательств для репозиториев GitHub | Стабильный |
| `/project` | Именованные рабочие пространства для организации запусков и отслеживания находок с течением времени | Стабильный |
| `/threat-model` | Создание, просмотр и поддержка моделей угроз для каждого проекта | Стабильный |
| `/sage` | Постоянный слой памяти (сохранение, извлечение, связывание, подтверждение) | Стабильный |
| `/frida` | Динамическая инструментация через Frida | Альфа |
| `/web` | Сканирование веб-приложений | Альфа/заглушка |

---

## Как работает конвейер

Начните с создания проекта, чтобы все ваши запуски попадали в одно место:```
/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` строит карту контекста точек входа, границ доверия и стоков (sinks) до того, как начнется сканирование. `/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`.

- Стадия A: действительно ли шаблон является уязвимостью, или это шум от сопоставления шаблонов инструмента?
- Стадия B: что нужно атакующему для её достижения, и что стоит на пути?
- Стадия C: существует ли путь выполнения на самом деле? Можно ли его достичь извне?
- Стадия D: окончательное решение — это тестовый код, требуются ли нереалистичные предусловия, уклоняется ли модель?
- Стадия E: возможность эксплуатации бинарного файла (при наличии скомпилированного артефакта)
- Стадия F: саморецензирование — не уклонялась ли какая-либо из предыдущих стадий или не противоречила ли себе?

Находки, прошедшие проверку, получают сгенерированные PoC эксплойтов и патчи. В конце выполняется межнаходочный анализ для поиска общих корневых причин и цепочек атак.

`/validate` запускает этот же конвейер как отдельный шаг, если у вас уже есть находки из предыдущего сканирования.

Для скомпилированного артефакта `/binary <path>` теперь выполняет исследование, основанное на доказательствах, а не выгружает кучу необработанных артефактов обратной разработки оператору. Под капотом он по-прежнему строит манифест, привязанный к SHA-256, реестр доказательств, карту контекста, контрольный список и граф SQLite из метаданных файла, импортов и перекрёстных ссылок radare2. Приложения Mach-O также получают инвентаризацию срезов, метаданные пакета и селекторы классов Objective-C / Swift; псевдокод высокой ценности сохраняется, а не исчезает внутри выполнения. Экспорты DLL PE, диспетчеры драйверов Windows и обработчики ioctl модулей ядра Linux также обрабатываются как свои собственные кандидаты на вход, при этом архитектура 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` анализирует зависимости и сторону цепочки поставок проекта. Это не просто поиск CVE по файлу requirements: RAPTOR обнаруживает манифесты, файлы блокировок, встроенные команды установки, зависимости рабочих процессов и источники пакетов контейнеров/базовых образов, затем нормализует их в единое представление зависимостей.

Сканирование обогащает зависимости консультациями OSV, CISA KEV, EPSS, CISA Vulnrichment/SSVC, достижимостью, сигналами доказательств эксплуатации, проверками гигиены, эвристиками цепочки поставок, выводами о политике лицензирования и опциональным обзором/сортировкой LLM. Оно выдаёт собственные находки RAPTOR, а также SBOM и вывод, удобный для CI:

- `findings.json` — канонические находки RAPTOR
- `report.md` — читаемая человеком сводка
- `sbom.cdx.json` — CycloneDX SBOM с данными VEX
- `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

После заполнения сканер сопоставляет идентификаторы пакетов с локальными файлами, и сетевые вызовы не выполняются. Без кеша RAPTOR попытается загрузить пакеты реестра с semgrep.dev во время сканирования; при отсутствии сети он корректно отбрасывает некэшированные пакеты и запускается только с пользовательскими правилами.

CodeQL требует доступ к сети только во время начальной настройки для загрузки CLI и пакетов запросов. После установки он работает в офлайн-режиме.

---

## Пользовательские правила

RAPTOR включает 185 пользовательских правил статического анализа, проверенных на ложные срабатывания методом состязательного тестирования:

- **Semgrep (123 правила)** — правила отслеживания и поиска уязвимостей для Python, Go, Java и JS/TS. Охватывают SQLi, XSS, SSRF, SSTI, внедрение команд, десериализацию, XXE, внедрение LDAP/NoSQL, path traversal, open redirect, внедрение в логи/заголовки, eval-инъекцию, ReDoS, загрязнение прототипа, неправильную конфигурацию JWT, слабую криптографию, небезопасный TLS и жестко закодированные секреты.
- **Coccinelle (54 правила)** — структурное сопоставление для C/C++. Безопасность памяти (двойное освобождение, использование после освобождения, освобождение небазового указателя, освобождение стекового массива, mmap-память, использование после закрытия), ошибки целых чисел (переполнение, расширение знака, двойной sizeof), утечки ресурсов (несовпадение popen/fclose, двойное закрытие fdopendir), обработка буферов (strncpy без NUL, несоответствие размера copy_user, off-by-one в malloc/strlen), безопасность обработчиков сигналов, неправильное использование API (область флагов fcntl, SIGKILL/SIGSTOP, двойная перестановка байтов, статический буфер inet_ntoa), удаление мертвых переменных компилятором, путаница IS_ERR/PTR_ERR в ядре, внедрение строки формата, гонки TOCTOU и другое.
- **CodeQL (8 запросов)** — межпроцедурное отслеживание для C++ (внедрение строки формата, усечение целых чисел, использование после перемещения, инвалидация итератора) и Java (XXE, небезопасная десериализация, внедрение в логи, Spring SSRF).

Просматривайте правила напрямую: `engine/semgrep/rules/`, `engine/coccinelle/rules/`, `engine/codeql/queries/`. Они дополняют пакеты реестра (`p/security-audit`, `p/owasp-top-ten`, `p/0xdea`, `p/trailofbits`), которые предоставляют ещё около 950 правил — пересечение минимально.

---

## Использование другой LLM

В RAPTOR есть два отдельных уровня моделей, и важно понимать, как работают оба, прежде чем что-то менять.

**Уровень оркестрации** — это всегда Claude Code. Файл CLAUDE.md, навыки и команды работают как инструкции Claude Code. Чтобы изменить модель Claude, которая оркестрирует RAPTOR, используйте флаг `--model` Claude Code или команду `/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"
    }
  ]
}

| Role | What it does |
|------|-------------|
| `analysis` | Проверяет и анализирует каждое обнаружение (этапы A-F) |
| `code` | Пишет PoC-эксплойты и код исправлений |
| `consensus` | Голосование второго мнения по истинно-положительным результатам |
| `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 подходит для анализа, но генерирует ненадёжный код эксплойтов и исправлений. Для задач генерации кода используйте frontier-модель.

### Быстрый уровень короткого замыкания + оценочная карта модели

Когда ваша модель уровня анализа имеет более дешёвую модель того же провайдера (Anthropic Opus → Haiku, OpenAI 5.x → 4o-mini, Gemini Pro → Flash-Lite, Mistral Large → Small), RAPTOR будет использовать её в качестве предварительного фильтра для потребителей, которые подключаются к субстрату (сегодня codeql; SCA и другие доработки появятся позже). Дешёвая модель всегда срабатывает только на **уверенных ложных срабатываниях**; неоднозначные случаи и уверенные истинные срабатывания всегда проходят полный анализ. Доверие накапливается по каждой ячейке `(model, decision_class)` — RAPTOR записывает согласованность дешёвого и полного анализа и срабатывает только тогда, когда верхняя граница 95% Уилсона для доли пропусков в ячейке опускается до 5% или ниже.

Чтобы посмотреть, в чём хороши ваши модели, используйте `/scorecard` (или напрямую: `libexec/raptor-llm-scorecard list`). Оценочная карта глобальна (уроки переносятся между проектами) и сохраняется в `out/llm_scorecard.json`.

---

## Проекты

Без проекта каждый запуск получает собственную папку с временной меткой в `out/`. С проектом всё помещается в одно место, и вы получаете объединённые результаты, отслеживание покрытия и различия между запусками.```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 ...`) и получать структурированный вывод SARIF без Claude Code, либо запускать его интерактивно с полным агентным рабочим процессом.

---

## OSS-форензика

`/oss-forensics` исследует публичные репозитории GitHub, используя доказательства из нескольких источников: GitHub API, GH Archive (неизменяемая история событий через BigQuery), Wayback Machine и локальная история git. Он выполняет структурированный конвейер от сбора доказательств через формирование гипотез до финального отчета по форензике.

Требуется `GOOGLE_APPLICATION_CREDENTIALS` для доступа к BigQuery. Подробности см. в `.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
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption