Агентный пентест-профиль для Hermes: 31 плейбук для авторизованной разведки, веб-атак и атак на контроль доступа, безопасной валидации эксплойтов и отчётности на основе доказательств с защитными шлюзами.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/50022/55f1c11f1fa53cb32838b487d5b5b6f1745b609c7123ce0a2b28ff21108c765b.png" alt="Violin" width="256"/>
</p>
<h1 align="center">Violin ☤ — Профиль контролируемого агентного пентеста для Hermes</h1>
<p align="center">
<a href="https://github.com/Strategic-Automation/violin"><img src="https://img.shields.io/badge/Status-Release%20Ready-2ea44f?style=for-the-badge" alt="Release Ready"></a>
<a href="https://github.com/Strategic-Automation/violin/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="License: MIT"></a>
<a href="https://hermes-agent.nousresearch.com/"><img src="https://img.shields.io/badge/Hermes-%3E=0.21.5-FFD700?style=for-the-badge" alt="Hermes >=0.21.5"></a>
<a href="https://www.kali.org/"><img src="https://img.shields.io/badge/Kali%20Linux-557C94?style=for-the-badge&logo=kali-linux&logoColor=white" alt="Kali Linux"></a>
<a href="https://www.parrotsec.org/"><img src="https://img.shields.io/badge/Parrot%20OS-2E8B57?style=for-the-badge" alt="Parrot OS"></a>
<a href="https://strategic-automation.github.io/violin/"><img src="https://img.shields.io/badge/Site-Landing%20page-FF3B4A?style=for-the-badge" alt="Landing page"></a>
<a href="https://github.com/Strategic-Automation/violin/stargazers"><img src="https://img.shields.io/github/stars/Strategic-Automation/violin?style=for-the-badge&color=FFD166" alt="GitHub stars"></a>
</p>
<p align="center">
<b>35 плейбуков · 19 справочников · 14 шаблонов · обязательный защитный механизм исполнения · нативный для Hermes</b>
</p>
Violin — это **нативный для Hermes агентный профиль пентеста** для контролируемых, авторизованных тестов на проникновение: от разведки через безопасную проверку эксплойтов до составления отчёта. Он использует встроенные наборы инструментов Hermes, семь маршрутизируемых навыков и обязательный плагин `violin_guard` на границе исполнения команд на целевой системе. Автономный CLI поддерживает проверки релиза, диагностику и административное восстановление; команды на целевой системе выполняются через плагин. Violin не добавляет собственных учётных данных и наследует провайдеров и инструментальные бэкенды, уже настроенные в Hermes.
<p align="center">
<a href="#quick-start">Быстрый старт</a> ·
<a href="#engagement-lifecycle">Рабочий процесс</a> ·
<a href="#guard-tools">Инструменты защиты</a> ·
<a href="#benchmarks">Бенчмарки</a> ·
<a href="https://strategic-automation.github.io/violin/">Лендинг</a> ·
<a href="https://github.com/Strategic-Automation/violin/discussions">Обсуждения</a> ·
<a href="#development">Разработка</a>
</p>
<p align="center">
<strong>Следите за Violin?</strong>
<a href="https://github.com/Strategic-Automation/violin/stargazers">Поставьте звезду репозиторию</a>,
чтобы его было проще найти и чтобы помочь другим инженерам по безопасности открыть для себя контролируемый агентный пентест.
</p>
### Упоминания в сообществе
Violin включён в подборки, составляемые сообществом, в том числе
[awesome-ai-security](https://github.com/gmh5225/awesome-ai-security),
[awesome-hermes-skills](https://github.com/ZeroPointRepo/awesome-hermes-skills),
[awesome-hermes-agent](https://github.com/Anil-matcha/awesome-hermes-agent) и
[awesome-infosec](https://github.com/onlurking/awesome-infosec).
Публикации третьих сторон:
[технический анализ Starlog](https://starlog.is/articles/cybersecurity/strategic-automation-violin) и
[«Violin: Supervised Agentic Penetration Testing Profile for Hermes Agent»](https://hamradio.my/violin-supervised-agentic-pentest-profile-hermes/).
Для независимой оценки используйте
[набор для рецензентов](https://strategic-automation.github.io/violin/review.html), который
содержит путь к бенчмаркам, известные ограничения, контекст рецензирования и фактическое
сравнение с автономными архитектурами пентест-агентов.
---
<table>
<tr><td width="240"><strong>Защищённое выполнение целевых команд</strong></td><td>Проверки области действия, фазы, PTT, навыков, гипотез, истории и синхронизации выполняются до запуска целевой команды.</td></tr>
<tr><td><strong>Постоянное состояние взаимодействия</strong></td><td>Задачи PTT, гипотезы, история команд, контрольные точки, доказательства и отчёты сохраняются при сжатии контекста.</td></tr>
<tr><td><strong>Выводы, подкреплённые доказательствами</strong></td><td>Типизированная отправка привязывает каждый подтверждённый вывод к аутентифицированным квитанциям выполнения.</td></tr>
<tr><td><strong>Маршрутизированная методология</strong></td><td>Оркестратор пентеста выбирает специализированные плейбуки для веб-, идентификационных, API-, бизнес-логических, LLM-безопасностных и конфигурационных проверок.</td></tr>
<tr><td><strong>Ограниченное выполнение</strong></td><td>Отдельные команды, серии команд, фоновые процессы, пакетная проверка, проверки heartbeat и отмена используют единую модель состояний.</td></tr>
<tr><td><strong>Проверяемые релизы</strong></td><td>Регистрация плагинов, схемы, снимки навыков, контракты документации, линтинг, форматирование и полный набор тестов проходят контроль при выпуске.</td></tr>
</table>
## Быстрый старт
### Установка профиля
```bash
hermes profile install https://github.com/Strategic-Automation/violin
hermes -p violin plugins disable violin_guard
hermes -p violin plugins enable violin_guard --no-allow-tool-override
hermes -p violin
```
Зависимости Guard объявляются в `plugins/violin_guard/plugin.yaml`. Имя плагина, каталог и конфигурация включения используют `violin_guard`, поэтому Hermes может разрешить его зависимости без обходного пути через каталог. Установка зависимостей в development-окружение `.venv` не устанавливает их в Hermes. Цикл отключения/включения, описанный выше, принудительно запускает приём зависимостей, даже если конфигурация профиля уже включает плагин. Проверьте регистрацию после установки:
```bash
hermes -p violin plugins doctor ~/.hermes/profiles/violin/plugins/violin_guard --ci
hermes -p violin tools list
```
Plugin Doctor должен показать 12 инструментов и 5 хуков, а `violin_guard` должен отображаться
как включённый набор инструментов. Перезапустите Hermes после установки, прежде чем начинать
работу. Переустановите профиль, чтобы перенести старую установку `violin-guard`.
Затем начните с авторизованной цели и позвольте Violin собрать область действия до
любого взаимодействия с целью:
```text
Run an authorized penetration test against example.com.
```
### Требования
- [Hermes Agent](https://hermes-agent.nousresearch.com/) 0.21.5 или новее (контейнер закрепляет коммит релиза `v2026.9.24`)
- Python 3.11 и `uv` для локальной разработки
- Kali Linux или Parrot OS для ожидаемой среды с инструментами безопасности
- Письменное разрешение и утверждённая область действия
Violin не выбирает модель или провайдера. Настройте их в Hermes. Для
подходящего варианта по умолчанию используйте **Qwen3.8 27B** локально или **DeepSeek V4 Flash** через
размещённого провайдера.
## Жизненный цикл взаимодействия
```mermaid
flowchart LR
S[Scope] --> R[Recon]
R --> V[Vulnerability research]
V --> E[Exploit validation]
E --> P[Reporting]
P --> X[Retrospective]
G[Violin Guard] -. validates .-> R
G -. validates .-> V
G -. validates .-> E
```
1. Инициализируйте работу и утвердите `scope/scope.yaml`.
2. Выберите одну активную задачу PTT и связанный с ней навык с помощью
`violin_record_ptt`.
3. Выполняйте целевые команды с помощью `violin_exec` или `violin_exec_burst`.
4. Обновляйте гипотезы по мере изменения их статуса на основании свидетельств.
5. Проверяйте каждый ограниченный пакет команд с помощью `violin_review_batch`.
6. Отправляйте подтверждённые находки и формируйте итоговый отчёт.
7. Проведите ретроспективу.
Полная модель фаз:
```text
SCOPING → RECON → VULN_RESEARCH → EXPLOITATION
→ POST_EXPLOITATION / PRIVESC / FLAGS
→ REPORTING → RETROSPECTIVE
```
Начало работы в новой фазе требует задачи PTT в рамках этой фазы. Существующие
задачи не перемещаются между разделами фаз.
## Инструменты защиты
Плагин регистрирует двенадцать инструментов Hermes из единого типизированного реестра:
| Инструмент | Назначение |
|---|---|
| `violin_record_ptt` | Создать, запустить, обновить, закрыть или отменить задачу PTT |
| `violin_record_hypothesis` | Создать или обновить ограниченную гипотезу |
| `violin_submit_finding` | Отправить подтверждённую находку, привязанную к её подписанным квитанциям выполнения |
| `violin_exec` | Выполнить одну защищённую команду |
| `violin_exec_burst` | Выполнить ограниченный файл команд |
| `violin_exec_status` | Прочитать статус фонового выполнения |
| `violin_exec_cancel` | Отменить отслеживаемое фоновое выполнение |
| `violin_review_batch` | Проверить завершённый пакет и зафиксировать состояние |
| `violin_rebind_pending_batch` | Перепривязать ожидающий пакет после подтверждения |
| `violin_heartbeat_done` | Очистить завершённую проверку heartbeat |
| `violin_target` | Определить утверждённую цель оценки |
| `violin_status` | Объяснить текущие задачи, навыки и блокировки |
`violin_exec` — это универсальная граница целевых команд. Здесь нет
специфичных для инструментов адаптеров выполнения или списков разрешённых бинарников. Установленные
неинтерактивные инструменты могут запускаться только после прохождения проверок вовлечения.
Хук необработанного терминала — это защитная сеть по мере возможности, а не сетевая изоляция.
Используйте `terminal` только для локальной подготовки и администрирования хоста.
## Модель безопасности
```mermaid
flowchart LR
A[Written authorization] --> B[Approved scope]
B --> C[Active phase task]
C --> D[Skill and hypothesis gates]
D --> E[Guarded execution]
E --> F[Evidence receipt]
F --> G[Batch review]
```
- Никакого взаимодействия с целью до утверждения объёма работ и проверки начальной загрузки.
- Никакого прямого выполнения shell-команд для команд цели.
- Никаких деструктивных, нарушающих работу, связанных с учётными данными, закреплением, скрытностью или
действий третьих лиц без явного письменного разрешения.
- Необработанные доказательства хранятся в `$ENG_DIR/evidence/<phase>/`.
- Секреты, дампы и вывод доказательств не попадают в `$ENG_DIR/state/`.
- Сжатие контекста возобновляется из файлов взаимодействия в текущей беседе Hermes.
Подробная политика описана в
[`skills/pentest/references/standards.md`](https://github.com/strategic-automation/violin/blob/master/skills/pentest/references/standards.md).
## Состояние взаимодействия
`init-engagement` создаёт каноническую рабочую структуру:
```text
$ENG_DIR/
├── scope/
│ └── scope.yaml
├── state/
│ ├── ptt.md
│ ├── history.md
│ └── checkpoint.json
├── hypotheses.md
├── evidence/
├── reporting/
└── retrospective/
```
### Обновление с Violin 3.3
Violin 4.0 хранит состояние исполнителя в `state/runtime.json` и не переносит
файлы `sync.json`, `counts.json` или `heartbeat.json` из версии 3.3. Начните новое
взаимодействие в новом каталоге; сохраните каталог 3.3 как историческую запись.
При повторном использовании его каталога устаревшие файлы состояния остаются на месте, поэтому Violin 4.0
отклонит его.
### Доставка навыков
Навыки загружаются по требованию. Первый вызов `violin_record_ptt` для маршрутизированного
навыка может вернуть `skill_prepared` без изменения PTT. После того как Hermes
доставит содержимое навыка, повторите переход, чтобы привязать подтверждение и применить
изменение задачи. `violin_status` сообщает точное действие для восстановления.
Файлы-маркеры, такие как `.skill-loaded-*`, не доказывают доставку навыка.
## Маршрутизированные навыки
| Навык | Охват |
|---|---|
| `pentest` | Область действия, жизненный цикл, разведка, эксплуатация, отчётность, закрытие |
| `web-app` | Инъекции, SSRF, обход каталогов, десериализация, уязвимости на стороне клиента |
| `identity-auth` | Аутентификация, авторизация, IDOR, JWT, CSRF, криптография |
| `api-testing` | REST, SOAP, GraphQL, WebSocket |
| `business-logic` | Рабочие процессы, ценообразование, купоны, квоты, рефералы, состояния гонки |
| `llm-security` | Инъекция промптов, MCP, JSON-RPC |
| `misconfig` | Развёртывание, обработка ошибок, наблюдаемость, безопасность через сокрытие |
Оркестратор загружает только материалы текущей фазы и специализированный плейбук, необходимые
для текущей задачи.
## Административный CLI
CLI не заменяет защищённое выполнение на целевой системе.
```bash
python scripts/violin_guard.py --help
python scripts/violin_guard.py init-engagement engagements/example --host example.com
python scripts/violin_guard.py check-bootstrap --eng-dir engagements/example
python scripts/violin_guard.py status --eng-dir engagements/example
python scripts/violin_guard.py generate-closeout --eng-dir engagements/example
python scripts/violin_guard.py check-release
```
`check-command` предоставляет проверки допуска для диагностики и не выполняет
переданную команду.
## Архитектура
```text
plugins/violin_guard/
├── core/
│ ├── commands/ shell parsing, targets, HTTP proof
│ ├── engagement/ state, PTT, phases, hypotheses, bootstrap
│ ├── evidence/ findings, history, receipts, redaction
│ └── skills/ skill policy and receipts
├── gates/ command, scope, hypothesis, terminal policies
├── engine/ execution, runtime backend, code audit, release checks
├── handlers/ public Hermes tool handlers
├── hooks.py Hermes lifecycle hooks
└── registry.py registered tool definitions
skills/ orchestrator, routed skills, playbooks, references
benchmark/ runner, scorer, proof checks, calibration fixtures
scripts/ administrative CLI and platform smoke tests
tests/ runtime, integration, documentation, release tests
```
## Бенчмарки
Репозиторий включает определение Escape Duck Store, а также эталонные фикстуры скорера для заведомо хороших и заведомо плохих случаев. Калибровка доказывает, что скорер корректно обрабатывает эти фикстуры; она не устанавливает полноту обнаружения живым агентом, завершённость рабочего процесса или качество отчёта.
```bash
uv run python -m benchmark.score --calibrate known-good
uv run python -m benchmark.score --calibrate known-bad
uv run python -m benchmark.run \
--target http://localhost:<published-port> \
--provider <provider> \
--api-base <openai-compatible-base-url> \
--model <model-id> \
--target-isolation-id escape-duck-store-2026-04:<image-digest-or-reset-id>
```
Перед публикацией результата прочитайте [методологию бенчмарков](https://github.com/strategic-automation/violin/blob/master/docs/BENCHMARKS.md).
В ней определены требования к доказательствам, воспроизводимости, приватной оценке и раскрытию информации для достоверного результата.
## Разработка
```bash
uv sync --dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run python scripts/violin_guard.py check-release
```
Релизный шлюз проверяет версии, изолированный импорт плагинов, зарегистрированные
инструменты, сгенерированные схемы, снимки навыков, контракты документации, Ruff и
полный набор тестов.
Дымовые тесты платформ:
- `scripts/smoke-test.sh` — дымовой тест релиза для Linux и Kali/Parrot
- `scripts/smoke-test.ps1` — дымовой тест начальной загрузки, области действия и
разрешения целей в Windows; доставка навыков и выполнение целей требуют Hermes
Правила участия см. в [CONTRIBUTING.md](https://github.com/strategic-automation/violin/blob/master/CONTRIBUTING.md), а порядок приватного
сообщения об уязвимостях — в [SECURITY.md](https://github.com/strategic-automation/violin/blob/master/SECURITY.md).
## Ответственное использование
Violin предназначен для авторизованной оценки безопасности. Операторы несут
ответственность за область действия, согласования, владение целями, обработку
данных и соблюдение местного законодательства.
## Поддержка Violin
Violin — проект с открытым исходным кодом, поддерживаемый Strategic Automation Ltd.
Если Violin полезен вам или вашей организации, вы можете
[спонсировать его дальнейшую разработку](https://github.com/sponsors/Strategic-Automation).
Спонсорство поддерживает дальнейшую разработку, тестирование, документацию,
работы по совместимости и выпуски.
Violin остаётся доступным под лицензией MIT. Спонсорство не включает
гарантированную поддержку, приоритет функций или влияние на политику безопасности.
## Лицензия
MIT — см. [LICENSE](https://github.com/strategic-automation/violin/blob/master/LICENSE).