Первое автономное тестирование веб-безопасности на основе доказательств для контролируемых, авторизованных целей. С воспроизводимыми лабораториями, аудиторскими следами, отчетами и эталонным тестированием XBEN.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7171/c6015851ea85c8a14cf1ecf4737ff05aaafe1413ed484c69d433e3700aa1c1b8.png" alt="Ravage logo" width="360">
</p>
# Ravage
Ravage — это CLI-инструмент, ориентированный на доказательства, для оценки работающего веб-приложения, которое принадлежит вам или на тестирование которого у вас есть явное разрешение. Он сочетает детерминированную разведку и валидацию с опциональным модельно-управляемым циклом атаки, сохраняя границы области действия, аутентификации, учёта трафика и доказательств в рамках, контролируемых кодом.
Ravage — это исследовательская альфа-версия до 1.0. Используйте изолированные среды и письменные правила взаимодействия. Тестирование безопасности может изменить состояние приложения; Ravage не устраняет найденные проблемы и не разворачивает исправления.
[Быстрый старт](#пятиминутный-локальный-быстрый-старт) ·
[Аутентификация](#аутентифицированное-тестирование) ·
[Результаты](#понимание-результатов) ·
[Возможности](#возможности) ·
[Документация](#документация)
## Требования
- Python 3.12
- Git
- macOS, Linux или WSL
- Docker только для контейнеризированных инструментов, XBEN и интеграционных тестов
- Ключ API провайдера только для модельно-управляемых команд
Обычное первое сканирование не требует ключа модели, браузера, демона Docker или внешнего сканера.
## Установка из исходного кода
~~~bash
git clone https://github.com/duriantaco/ravage.git
cd ravage
scripts/bootstrap.sh
source .venv/bin/activate
ravage doctor
~~~
Bootstrap создаёт <code>.venv</code> и устанавливает рабочее пространство. Используйте <code>scripts/bootstrap.sh --dev</code> для зависимостей разработки, <code>--browser</code> для поддержки браузера или <code>--install-browser</code> для установки Chromium.
## Пятиминутный локальный быстрый старт
Сначала запустите ваше приложение. В этом примере предполагается, что оно прослушивает <code>http://127.0.0.1:3000</code>.
1. Создайте ограниченный бриф взаимодействия и приватный файл окружения:
~~~bash
ravage init http://127.0.0.1:3000 \
--brief ravage-brief.yaml \
--env-file .env.ravage \
--description "Authorized assessment of my local development app."
~~~
2. Просмотрите <code>ravage-brief.yaml</code>. Проверьте цель, маршруты в области действия, исключения, бюджет запросов, ограничение скорости, цели и критерии успеха.
3. Запустите поверхностное сканирование без модели:
~~~bash
ravage doctor --workflow scan --brief ravage-brief.yaml
ravage scan ravage-brief.yaml --probe surface_map --report
~~~
Команда выводит каталог запуска. Скопируйте этот путь и используйте его как <code>RUN_DIR</code> в командах проверки ниже.
## Запуск модельно-управляемого агента
Добавьте ключ поддерживаемого провайдера, например <code>OPENAI_API_KEY</code>, в <code>.env.ravage</code>. Ravage читает этот файл напрямую; не подключайте его через shell.
~~~bash
ravage doctor --workflow attack --brief ravage-brief.yaml
ravage attack ravage-brief.yaml --allow-paid-models --report
~~~
<code>--allow-paid-models</code> — это явное подтверждение того, что запуск может повлечь расходы провайдера. Выбор моделей, локальные провайдеры и воспроизводимые профили описаны в [Поставщики моделей](https://github.com/duriantaco/ravage/blob/main/docs/model-providers.md).
## Аутентифицированное тестирование
Добавьте выделенную тестовую учётную запись в бриф:
~~~bash
ravage auth add ravage-brief.yaml \
--identity user \
--type form \
--login /login \
--health /account \
--marker Logout \
--env-file .env.ravage
~~~
Заполните сгенерированные ссылки на секреты, проверьте сеанс, затем атакуйте с выбранной учётной записью:
~~~bash
ravage auth check ravage-brief.yaml --identity user
ravage attack ravage-brief.yaml \
--identity user \
--allow-paid-models \
--report
~~~
Поддерживаются вход через форму, токены bearer и фиксированные статические заголовки. Управляемые учётные данные остаются внутри аутентифицированного HTTP-владельца; каналы процесса, Python и команд блокируются при выборе учётной записи. См. [Аутентификация](https://github.com/duriantaco/ravage/blob/main/docs/authentication.md) для настройки и ограничений.
## Авторизованные удалённые цели
Удалённое выполнение закрыто по умолчанию и требует явного флага. Начните с низкорискового поверхностного сканирования:
~~~bash
ravage init https://staging.example.test \
--brief ravage-brief.yaml \
--env-file .env.ravage \
--description "Authorized assessment of my staging application."
ravage doctor --workflow scan \
--brief ravage-brief.yaml \
--authorized-remote-target
ravage scan ravage-brief.yaml \
--probe surface_map \
--authorized-remote-target \
--report
~~~
Для модельно-управляемого удалённого запуска:
~~~bash
ravage attack ravage-brief.yaml \
--authorized-remote-target \
--allow-paid-models \
--report
~~~
Авторизованные удалённые атаки по умолчанию используют политику низкого шума для всего запуска: только нативный тарифицируемый HTTP, темп ниже 1 RPS, потолок физических запросов, консервативное кэширование и дедупликация GET/HEAD, адаптивная задержка, ограниченные повторные попытки и размыкание цепи. Долговечный журнал сохраняется при возобновлении. Подробности в [Архитектура](https://github.com/duriantaco/ravage/blob/main/docs/architecture.md).
## Понимание результатов
Ravage различает наблюдения, кандидатные находки и подтверждённые уязвимости. Флаг CTF — это одно из возможных доказательств, а не требование. В обычном приложении запуск может быть полезным и успешным без обнаружения флага; подтверждённые уязвимости всё равно записываются в отчёт.
После начала атаки её канонический приватный машиночитаемый артефакт — это <code>RUN_DIR/report.json</code>, включая незавершённые запуски. <code>--report</code> также записывает <code>RUN_DIR/report.md</code>.
~~~bash
ravage observe RUN_DIR
ravage audit verify RUN_DIR
ravage report RUN_DIR --brief ravage-brief.yaml
~~~
Для структурированного HTTP, захваченного графом агента:
~~~bash
ravage traffic list RUN_DIR
ravage traffic show RUN_DIR REQUEST_ID
~~~
Отчёт включает ссылки на доказательства, качество учёта запросов, статус завершения и причину остановки незавершённого запуска. Никогда не рассматривайте непроверенное утверждение модели как подтверждённую находку.
## Возможности
| Возможность | Точка входа | Примечания |
| --- | --- | --- |
| Детерминированная разведка и пробы | <code>ravage scan</code> | Модель не требуется |
| Модельно-управляемая оценка | <code>ravage attack</code> | Ограничено доказательствами и областью действия |
| Управляемая аутентификация | <code>ravage auth</code> | Форма, bearer, статический заголовок |
| Проверка и повтор трафика | <code>ravage traffic</code> | Ограниченные артефакты |
| Навыки знаний | <code>ravage skills</code>, <code>ravage code-bug</code> | Консультативные |
| Пассивная проверка SATCOM | <code>ravage satcom inspect</code> | Без передачи |
| Оценка XBEN | <code>ravage xben</code> | Исследовательский стенд на Docker |
| Лаборатория улучшений | <code>scripts/improvement_lab.py</code> | Изолированный архив |
Навыки знаний могут направлять приоритизацию, но не могут добавлять инструменты, расширять область действия или подтверждать находки. Начните с:
~~~bash
ravage skills list builtin
ravage skills validate builtin
~~~
[Лаборатория улучшений](https://github.com/duriantaco/ravage/blob/main/docs/improvement-lab.md) принимает санитизированную структуру предыдущих запусков, оценивает кандидатные патчи в независимых рабочих пространствах, архивирует принятые и отклонённые версии и требует подтверждения отсутствия регрессий перед продвижением. Это вспомогательный компонент: она не изменяет исходный код и не продвигает себя автоматически.
Пассивные орбитальные и пакетные артефакты можно проверять отдельно:
~~~bash
ravage satcom inspect orbit.tle --format tle --output orbit-report.json
ravage satcom inspect capture.bin \
--format ccsds-space-packets \
--direction auto \
--output packet-report.json
~~~
Поддержка SATCOM — это пассивный разбор и анализ, а не радиопередатчик или система управления космическим аппаратом.
## Разработка
~~~bash
scripts/bootstrap.sh --dev
source .venv/bin/activate
python -m pytest -m "not integration" -q
python -m ruff check --select E9,F .
python scripts/qa/check_docs.py
python scripts/qa/check_release.py
~~~
Интеграционные тесты на Docker и замороженные сравнения XBEN — это отдельные шлюзы выпуска. Прочитайте [Бенчмаркинг](https://github.com/duriantaco/ravage/blob/main/docs/benchmarking.md) перед интерпретацией результатов кейсов; один удачный флаг не является доказательством надёжного улучшения.
## Документация
- [Как использовать Ravage](https://github.com/duriantaco/ravage/blob/main/docs/how-to-use.md)
- [Настройка и устранение неполадок](https://github.com/duriantaco/ravage/blob/main/docs/setup.md)
- [Аутентификация](https://github.com/duriantaco/ravage/blob/main/docs/authentication.md)
- [Архитектура](https://github.com/duriantaco/ravage/blob/main/docs/architecture.md)
- [Навыки](https://github.com/duriantaco/ravage/blob/main/docs/skills.md)
- [Пассивный SATCOM](https://github.com/duriantaco/ravage/blob/main/docs/satcom.md)
- [Лаборатория улучшений](https://github.com/duriantaco/ravage/blob/main/docs/improvement-lab.md)
- [Бенчмаркинг](https://github.com/duriantaco/ravage/blob/main/docs/benchmarking.md)
- [Политика безопасности](https://github.com/duriantaco/ravage/blob/main/SECURITY.md)
- [Вклад в проект](https://github.com/duriantaco/ravage/blob/main/CONTRIBUTING.md)
Используйте <code>ravage --help</code> и <code>ravage COMMAND --help</code> для точных опций в вашей версии.
## Лицензия
Apache License 2.0. См. [LICENSE](https://github.com/duriantaco/ravage/blob/main/LICENSE), [DISCLAIMER](https://github.com/duriantaco/ravage/blob/main/DISCLAIMER.md) и [SECURITY.md](https://github.com/duriantaco/ravage/blob/main/SECURITY.md).