Perfil de pentest agéntico para Hermes: 31 playbooks para reconocimiento autorizado, ataques web/de control de acceso, validación segura de exploits e informes basados en evidencias con compuertas de seguridad.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/50022/55f1c11f1fa53cb32838b487d5b5b6f1745b609c7123ce0a2b28ff21108c765b.png" alt="Violin" width="256"/>
</p>
<h1 align="center">Violin ☤ — Perfil de pentest agéntico supervisado para 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 playbooks · 19 referencias · 14 plantillas · guard de ejecución obligatorio · nativo de Hermes</b>
</p>
Violin es un **perfil de pentest agéntico nativo de Hermes** para pruebas de penetración supervisadas y autorizadas — desde el reconocimiento, pasando por la validación segura de exploits, hasta la elaboración de informes. Utiliza los conjuntos de herramientas integrados de Hermes, siete skills enrutadas y el plugin obligatorio `violin_guard` en la frontera de ejecución contra objetivos. La CLI independiente admite comprobaciones de versión, diagnósticos y recuperación administrativa; los comandos contra objetivos se ejecutan a través del plugin. Violin no añade credenciales específicas del perfil y hereda los backends de proveedor y de herramientas ya configurados en Hermes.
<p align="center">
<a href="#quick-start">Inicio rápido</a> ·
<a href="#engagement-lifecycle">Flujo de trabajo</a> ·
<a href="#guard-tools">Herramientas del guard</a> ·
<a href="#benchmarks">Benchmarks</a> ·
<a href="https://strategic-automation.github.io/violin/">Página de inicio</a> ·
<a href="https://github.com/Strategic-Automation/violin/discussions">Debates</a> ·
<a href="#development">Desarrollo</a>
</p>
<p align="center">
<strong>¿Sigues Violin?</strong>
<a href="https://github.com/Strategic-Automation/violin/stargazers">Marca el repositorio con una estrella</a>
para que siga siendo fácil de encontrar y ayudes a otros ingenieros de seguridad a descubrir el pentesting agéntico supervisado.
</p>
### Descubrimiento en la comunidad
Violin aparece en colecciones seleccionadas por la comunidad, entre ellas
[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) y
[awesome-infosec](https://github.com/onlurking/awesome-infosec).
Cobertura de terceros:
[análisis técnico de Starlog](https://starlog.is/articles/cybersecurity/strategic-automation-violin) y
[«Violin: Supervised Agentic Penetration Testing Profile for Hermes Agent»](https://hamradio.my/violin-supervised-agentic-pentest-profile-hermes/).
Para una evaluación independiente, utiliza el
[kit para revisores](https://strategic-automation.github.io/violin/review.html), que
recopila la ruta de benchmarks, los límites conocidos, el contexto de revisión y una
comparación factual con diseños de agentes de pentest autónomos.
---
<table>
<tr><td width="240"><strong>Ejecución de objetivos protegida</strong></td><td>Las comprobaciones de alcance, fase, PTT, habilidad, hipótesis, historial y sincronización se ejecutan antes de que se inicie un comando de objetivo.</td></tr>
<tr><td><strong>Estado de compromiso persistente</strong></td><td>Las tareas de PTT, las hipótesis, el historial de comandos, los puntos de control, la evidencia y los informes sobreviven a la compresión del contexto.</td></tr>
<tr><td><strong>Hallazgos respaldados por evidencia</strong></td><td>Un envío tipado vincula cada hallazgo validado con recibos de ejecución autenticados.</td></tr>
<tr><td><strong>Metodología enrutada</strong></td><td>Un orquestador de pentesting selecciona playbooks enfocados en web, identidad, API, lógica de negocio, seguridad de LLM y configuraciones incorrectas.</td></tr>
<tr><td><strong>Ejecución acotada</strong></td><td>Comandos individuales, ráfagas de comandos, procesos en segundo plano, revisión por lotes, comprobaciones de latido y cancelación comparten un único modelo de estado.</td></tr>
<tr><td><strong>Versiones verificables</strong></td><td>El registro de plugins, los esquemas, las instantáneas de habilidades, los contratos de documentación, el lint, el formateo y la suite de pruebas completa están sujetos a compuertas de versión.</td></tr>
</table>
## Inicio rápido
### Instalar el perfil
```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
```
Las dependencias de guard se declaran en `plugins/violin_guard/plugin.yaml`. El nombre del plugin, el directorio y la configuración de habilitación usan todos `violin_guard`, por lo que Hermes puede resolver sus dependencias sin un workaround de directorio. Instalar las dependencias en el `.venv` de desarrollo no las instala en Hermes. El ciclo de deshabilitar/habilitar anterior fuerza la admisión de dependencias incluso cuando la configuración del perfil ya habilita el plugin. Verifique el registro después de la instalación:
```bash
hermes -p violin plugins doctor ~/.hermes/profiles/violin/plugins/violin_guard --ci
hermes -p violin tools list
```
Plugin Doctor debería reportar 12 herramientas y 5 hooks, y `violin_guard` debería aparecer
como un toolset habilitado. Reinicia Hermes después de la instalación antes de comenzar un
engagement. Reinstala el perfil para migrar una instalación anterior de `violin-guard`.
Luego comienza con un objetivo autorizado y deja que Violin recopile el alcance antes de
cualquier interacción con el objetivo:
```text
Run an authorized penetration test against example.com.
```
### Requisitos
- [Hermes Agent](https://hermes-agent.nousresearch.com/) 0.21.5 o superior (el contenedor fija el commit de la versión `v2026.9.24`)
- Python 3.11 y `uv` para el desarrollo local
- Kali Linux o Parrot OS para el entorno esperado de herramientas de seguridad
- Autorización por escrito y un alcance aprobado
Violin no selecciona un modelo ni un proveedor. Configúrelos en Hermes. Para un
valor predeterminado capaz, use **Qwen3.8 27B** localmente o **DeepSeek V4 Flash** a través de un
proveedor alojado.
## Ciclo de vida del engagement
```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. Inicializar el engagement y aprobar `scope/scope.yaml`.
2. Seleccionar una tarea PTT activa y su skill enrutada con
`violin_record_ptt`.
3. Ejecutar comandos de objetivo con `violin_exec` o `violin_exec_burst`.
4. Actualizar las hipótesis a medida que la evidencia cambie su estado.
5. Revisar cada lote de comandos acotado con `violin_review_batch`.
6. Enviar los hallazgos validados y generar el informe final.
7. Completar la retrospectiva.
El modelo de fases completo es:
```text
SCOPING → RECON → VULN_RESEARCH → EXPLOITATION
→ POST_EXPLOITATION / PRIVESC / FLAGS
→ REPORTING → RETROSPECTIVE
```
Comenzar trabajo en una nueva fase requiere una tarea PTT bajo esa fase. Las
tareas existentes no se mueven entre secciones de fase.
## Herramientas de protección
El plugin registra doce herramientas de Hermes desde un único registro tipado:
| Herramienta | Propósito |
|---|---|
| `violin_record_ptt` | Crear, iniciar, actualizar, cerrar o cancelar una tarea PTT |
| `violin_record_hypothesis` | Crear o actualizar una hipótesis con alcance definido |
| `violin_submit_finding` | Enviar un hallazgo validado vinculado a sus recibos de ejecución firmados |
| `violin_exec` | Ejecutar un comando protegido |
| `violin_exec_burst` | Ejecutar un archivo de comandos acotado |
| `violin_exec_status` | Leer el estado de ejecución en segundo plano |
| `violin_exec_cancel` | Cancelar la ejecución en segundo plano rastreada |
| `violin_review_batch` | Revisar un lote completado y resolver el estado |
| `violin_rebind_pending_batch` | Revincular un lote pendiente tras la confirmación |
| `violin_heartbeat_done` | Limpiar una revisión de latido completada |
| `violin_target` | Resolver el objetivo de evaluación aprobado |
| `violin_status` | Explicar las tareas, habilidades y bloqueos actuales |
`violin_exec` es el límite genérico para comandos sobre el objetivo. No existen
adaptadores de ejecución específicos por herramienta ni listas de binarios permitidos. Las herramientas
no interactivas instaladas pueden ejecutarse solo después de que pasen las compuertas del compromiso.
El hook de terminal sin procesar es una red de seguridad de mejor esfuerzo, no un aislamiento de red.
Use `terminal` solo para preparación y administración local del host.
## Modelo de seguridad
```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]
```
- Ninguna interacción con el objetivo antes de la aprobación del alcance y la validación del arranque.
- Ninguna ejecución de shell sin procesar para comandos del objetivo.
- Ninguna acción destructiva, disruptiva, de obtención de credenciales, de persistencia, sigilosa o contra terceros sin autorización escrita explícita.
- La evidencia sin procesar permanece bajo `$ENG_DIR/evidence/<phase>/`.
- Los secretos, volcados y la salida de pruebas quedan fuera de `$ENG_DIR/state/`.
- La compresión de contexto se reanuda a partir de los archivos del engagement en la conversación actual de Hermes.
La política detallada está en
[`skills/pentest/references/standards.md`](https://github.com/strategic-automation/violin/blob/master/skills/pentest/references/standards.md).
## Estado del engagement
`init-engagement` crea la estructura de trabajo canónica:
```text
$ENG_DIR/
├── scope/
│ └── scope.yaml
├── state/
│ ├── ptt.md
│ ├── history.md
│ └── checkpoint.json
├── hypotheses.md
├── evidence/
├── reporting/
└── retrospective/
```
### Actualización desde Violin 3.3
Violin 4.0 almacena el estado del ejecutor en `state/runtime.json` y no migra
los archivos `sync.json`, `counts.json` ni `heartbeat.json` de la versión 3.3. Inicie un nuevo
engagement en un directorio nuevo; conserve el directorio de la versión 3.3 como registro histórico.
Reutilizar su directorio deja los archivos de estado heredados en su lugar, por lo que Violin 4.0
lo rechazará.
### Entrega de skills
Las skills se cargan bajo demanda. La primera llamada a `violin_record_ptt` para una skill
enrutada puede devolver `skill_prepared` sin cambiar el PTT. Después de que Hermes
entregue el contenido de la skill, repita la transición para vincular el recibo y aplicar
el cambio de tarea. `violin_status` informa la acción de recuperación exacta.
Los archivos marcador como `.skill-loaded-*` no demuestran la entrega de la skill.
## Skills enrutadas
| Skill | Cobertura |
|---|---|
| `pentest` | Alcance, ciclo de vida, reconocimiento, explotación, informes, cierre |
| `web-app` | Inyección, SSRF, traversal, deserialización, fallos del lado del cliente |
| `identity-auth` | Autenticación, autorización, IDOR, JWT, CSRF, criptografía |
| `api-testing` | REST, SOAP, GraphQL, WebSocket |
| `business-logic` | Flujo de trabajo, precios, cupones, cuotas, referidos, condiciones de carrera |
| `llm-security` | Inyección de prompts, MCP, JSON-RPC |
| `misconfig` | Despliegue, manejo de errores, observabilidad, seguridad por ocultación |
El orquestador carga únicamente el material de fase y el playbook de especialista necesarios
para la tarea actual.
## CLI administrativa
La CLI no reemplaza la ejecución protegida de objetivos.
```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` expone comprobaciones de admisión para diagnósticos y no ejecuta el comando proporcionado.
## Arquitectura
```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
```
## Benchmarks
El repositorio incluye la definición de Escape Duck Store, además de fixtures del scorer verificados como correctos e incorrectos. La calibración demuestra que el scorer maneja esos fixtures; no establece el recall de agentes en vivo, la finalización del flujo de trabajo ni la calidad del informe.
```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>
```
Lee la [metodología de benchmark](https://github.com/strategic-automation/violin/blob/master/docs/BENCHMARKS.md) antes de publicar una puntuación.
Define la prueba, la reproducibilidad, la evaluación privada y los requisitos
de divulgación para un resultado creíble.
## Desarrollo
```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
```
La puerta de release verifica las superficies de versión, la importación aislada de plugins, las herramientas registradas, los esquemas generados, las instantáneas de skills, los contratos de documentación, Ruff y la suite de pruebas completa.
Pruebas de humo por plataforma:
- `scripts/smoke-test.sh` — prueba de humo de release para Linux y Kali/Parrot
- `scripts/smoke-test.ps1` — prueba de humo de bootstrap, alcance y resolución de objetivos en Windows; la entrega de skills y la ejecución de objetivos requieren Hermes
Consulta [CONTRIBUTING.md](https://github.com/strategic-automation/violin/blob/master/CONTRIBUTING.md) para las reglas de contribución y
[SECURITY.md](https://github.com/strategic-automation/violin/blob/master/SECURITY.md) para el reporte privado de vulnerabilidades.
## Uso responsable
Violin está destinado a la evaluación de seguridad autorizada. Los operadores son responsables del alcance, las aprobaciones, la propiedad de los objetivos, el manejo de datos y la legislación local.
## Apoya a Violin
Violin es un proyecto de código abierto mantenido por Strategic Automation Ltd.
Si Violin te resulta útil a ti o a tu organización, puedes
[patrocinar su desarrollo continuo](https://github.com/sponsors/Strategic-Automation).
El patrocinio apoya el desarrollo continuo, las pruebas, la documentación,
el trabajo de compatibilidad y las releases.
Violin sigue disponible bajo la licencia MIT. El patrocinio no incluye
soporte garantizado, prioridad de funcionalidades ni influencia sobre la política de seguridad.
## Licencia
MIT — consulta [LICENSE](https://github.com/strategic-automation/violin/blob/master/LICENSE).