Perfil de pentest agêntico para Hermes: 31 playbooks para reconhecimento autorizado, ataques web/de controle de acesso, validação segura de exploits e relatórios baseados em evidências com portões de proteção.
<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 Hermes Agêntico Supervisionado</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 referências · 14 templates · guarda de execução obrigatória · nativo do Hermes</b>
</p>
Violin é um **perfil de pentest agêntico nativo do Hermes** para testes de penetração supervisionados e autorizados — desde o reconhecimento, passando pela validação segura de exploits, até o relatório. Ele utiliza os conjuntos de ferramentas integrados do Hermes, sete skills roteadas e o plugin obrigatório `violin_guard` na fronteira de execução no alvo. A CLI autônoma oferece verificações de release, diagnósticos e recuperação administrativa; os comandos no alvo são executados através do plugin. Violin não adiciona credenciais específicas do perfil e herda os backends de provedor e de ferramentas já configurados no Hermes.
<p align="center">
<a href="#quick-start">Início rápido</a> ·
<a href="#engagement-lifecycle">Fluxo de trabalho</a> ·
<a href="#guard-tools">Ferramentas de guarda</a> ·
<a href="#benchmarks">Benchmarks</a> ·
<a href="https://strategic-automation.github.io/violin/">Landing page</a> ·
<a href="https://github.com/Strategic-Automation/violin/discussions">Discussões</a> ·
<a href="#development">Desenvolvimento</a>
</p>
<p align="center">
<strong>Acompanhando o Violin?</strong>
<a href="https://github.com/Strategic-Automation/violin/stargazers">Dê uma estrela ao repositório</a>
para mantê-lo fácil de encontrar e ajudar outros engenheiros de segurança a descobrir o pentest agêntico supervisionado.
</p>
### Descoberta pela comunidade
Violin está listado em coleções curadas pela comunidade, incluindo
[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) e
[awesome-infosec](https://github.com/onlurking/awesome-infosec).
Cobertura de terceiros:
[análise técnica do Starlog](https://starlog.is/articles/cybersecurity/strategic-automation-violin) e
[“Violin: Supervised Agentic Penetration Testing Profile for Hermes Agent”](https://hamradio.my/violin-supervised-agentic-pentest-profile-hermes/).
Para avaliação independente, utilize o
[kit do revisor](https://strategic-automation.github.io/violin/review.html), que
reúne o caminho de benchmark, os limites conhecidos, o contexto de revisão e uma
comparação factual com designs autônomos de agentes de pentest.
---
<table>
<tr><td width="240"><strong>Execução de alvo protegida</strong></td><td>Verificações de escopo, fase, PTT, skill, hipótese, histórico e sincronização são executadas antes de um comando de alvo iniciar.</td></tr>
<tr><td><strong>Estado de engajamento persistente</strong></td><td>Tarefas de PTT, hipóteses, histórico de comandos, checkpoints, evidências e relatórios sobrevivem à compressão de contexto.</td></tr>
<tr><td><strong>Descobertas respaldadas por evidências</strong></td><td>Uma submissão tipada vincula cada descoberta validada a recibos de execução autenticados.</td></tr>
<tr><td><strong>Metodologia roteada</strong></td><td>Um orquestrador de pentest seleciona playbooks focados em web, identidade, API, lógica de negócio, segurança de LLM e configuração incorreta.</td></tr>
<tr><td><strong>Execução limitada</strong></td><td>Comandos únicos, rajadas de comandos, processos em segundo plano, revisão em lote, verificações de heartbeat e cancelamento compartilham um único modelo de estado.</td></tr>
<tr><td><strong>Lançamentos verificáveis</strong></td><td>Registro de plugins, esquemas, snapshots de skills, contratos de documentação, lint, formatação e a suíte de testes completa são condicionados ao lançamento.</td></tr>
</table>
## Início rápido
### Instalar o 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
```
As dependências do guard são declaradas em `plugins/violin_guard/plugin.yaml`. O nome do plugin, o diretório e a configuração de ativação usam todos `violin_guard`, para que o Hermes possa resolver suas dependências sem um workaround de diretório. Instalar as dependências no `.venv` de desenvolvimento não as instala no Hermes. O ciclo de desativação/ativação acima força a admissão de dependências mesmo quando a configuração do perfil já ativa o plugin. Verifique o registro após a instalação:
```bash
hermes -p violin plugins doctor ~/.hermes/profiles/violin/plugins/violin_guard --ci
hermes -p violin tools list
```
O Plugin Doctor deve reportar 12 ferramentas e 5 hooks, e `violin_guard` deve aparecer
como um toolset habilitado. Reinicie o Hermes após a instalação antes de iniciar um
engajamento. Reinstale o perfil para migrar uma instalação mais antiga do `violin-guard`.
Em seguida, comece com um alvo autorizado e deixe o Violin coletar o escopo antes
de qualquer interação com o alvo:
```text
Run an authorized penetration test against example.com.
```
### Requisitos
- [Hermes Agent](https://hermes-agent.nousresearch.com/) 0.21.5 ou mais recente (o contêiner fixa o commit de release `v2026.9.24`)
- Python 3.11 e `uv` para desenvolvimento local
- Kali Linux ou Parrot OS para o ambiente esperado de ferramentas de segurança
- Autorização por escrito e um escopo aprovado
O Violin não seleciona um modelo ou provedor. Configure-os no Hermes. Para um
padrão capaz, use **Qwen3.8 27B** localmente ou **DeepSeek V4 Flash** por meio de
um provedor hospedado.
## Ciclo de vida do engajamento
```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. Inicialize o engajamento e aprove `scope/scope.yaml`.
2. Selecione uma tarefa PTT ativa e sua skill roteada com
`violin_record_ptt`.
3. Execute comandos de destino com `violin_exec` ou `violin_exec_burst`.
4. Atualize as hipóteses conforme as evidências alterarem seu status.
5. Revise cada lote de comandos delimitado com `violin_review_batch`.
6. Envie os achados validados e gere o relatório final.
7. Conclua a retrospectiva.
O modelo completo de fases é:
```text
SCOPING → RECON → VULN_RESEARCH → EXPLOITATION
→ POST_EXPLOITATION / PRIVESC / FLAGS
→ REPORTING → RETROSPECTIVE
```
Iniciar trabalho em uma nova fase requer uma tarefa PTT sob essa fase. As tarefas
existentes não são movidas entre seções de fase.
## Ferramentas de proteção
O plugin registra doze ferramentas Hermes a partir de um único registro tipado:
| Ferramenta | Finalidade |
|---|---|
| `violin_record_ptt` | Criar, iniciar, atualizar, encerrar ou cancelar uma tarefa PTT |
| `violin_record_hypothesis` | Criar ou atualizar uma hipótese com escopo definido |
| `violin_submit_finding` | Enviar um achado validado vinculado aos seus recibos de execução assinados |
| `violin_exec` | Executar um comando protegido |
| `violin_exec_burst` | Executar um arquivo de comandos limitado |
| `violin_exec_status` | Ler o status de execução em segundo plano |
| `violin_exec_cancel` | Cancelar a execução em segundo plano rastreada |
| `violin_review_batch` | Revisar um lote concluído e definir o estado |
| `violin_rebind_pending_batch` | Revincular um lote pendente após confirmação |
| `violin_heartbeat_done` | Limpar uma revisão de heartbeat concluída |
| `violin_target` | Resolver o alvo de avaliação aprovado |
| `violin_status` | Explicar as tarefas, habilidades e bloqueios atuais |
`violin_exec` é a fronteira genérica de comandos de alvo. Não existem
adaptadores de execução específicos por ferramenta nem listas de permissão de binários. Ferramentas
não interativas instaladas só podem ser executadas após a aprovação dos portões de engajamento.
O hook de terminal bruto é uma rede de segurança de melhor esforço, não um confinamento de rede.
Use `terminal` apenas para preparação e administração locais ao host.
## Modelo de segurança
```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]
```
- Nenhuma interação com o alvo antes da aprovação do escopo e da validação do bootstrap.
- Nenhuma execução de shell bruta para comandos do alvo.
- Nenhuma ação destrutiva, disruptiva, de credenciais, de persistência, de furtividade ou
de terceiros sem autorização escrita explícita.
- Evidências brutas permanecem em `$ENG_DIR/evidence/<phase>/`.
- Segredos, dumps e saída de provas ficam fora de `$ENG_DIR/state/`.
- A compactação de contexto é retomada a partir dos arquivos de engajamento na conversa
atual do Hermes.
A política detalhada está em
[`skills/pentest/references/standards.md`](https://github.com/strategic-automation/violin/blob/master/skills/pentest/references/standards.md).
## Estado do engajamento
`init-engagement` cria a estrutura de trabalho canônica:
```text
$ENG_DIR/
├── scope/
│ └── scope.yaml
├── state/
│ ├── ptt.md
│ ├── history.md
│ └── checkpoint.json
├── hypotheses.md
├── evidence/
├── reporting/
└── retrospective/
```
### Atualização a partir do Violin 3.3
O Violin 4.0 armazena o estado do executor em `state/runtime.json` e não migra
os arquivos `sync.json`, `counts.json` ou `heartbeat.json` da versão 3.3. Inicie um novo
engajamento em um novo diretório; mantenha o diretório da versão 3.3 como registro histórico.
Reutilizar seu diretório deixa os arquivos de estado legados no lugar, então o Violin 4.0
os rejeitará.
### Entrega de skills
As skills são carregadas sob demanda. A primeira chamada de `violin_record_ptt` para uma skill
roteada pode retornar `skill_prepared` sem alterar o PTT. Depois que o Hermes
entrega o conteúdo da skill, repita a transição para vincular o recibo e aplicar
a mudança de tarefa. `violin_status` informa a ação de recuperação exata.
Arquivos marcadores como `.skill-loaded-*` não comprovam a entrega da skill.
## Skills roteadas
| Skill | Cobertura |
|---|---|
| `pentest` | Escopo, ciclo de vida, reconhecimento, exploração, relatórios, encerramento |
| `web-app` | Injeção, SSRF, travessia de diretórios, desserialização, falhas do lado do cliente |
| `identity-auth` | Autenticação, autorização, IDOR, JWT, CSRF, criptografia |
| `api-testing` | REST, SOAP, GraphQL, WebSocket |
| `business-logic` | Fluxo de trabalho, precificação, cupom, cota, indicação, condições de corrida |
| `llm-security` | Injeção de prompt, MCP, JSON-RPC |
| `misconfig` | Implantação, tratamento de erros, observabilidade, obscuridade |
O orquestrador carrega apenas o material da fase e o playbook especializado necessários
para a tarefa atual.
## CLI administrativa
A CLI não substitui a execução protegida de alvos.
```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` expõe verificações de admissão para fins de diagnóstico e não executa
o comando fornecido.
## Arquitetura
```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
O repositório inclui a definição do Escape Duck Store, além de fixtures de scorer conhecidas como boas e conhecidas como ruins. A calibração comprova que o scorer lida com essas fixtures; ela não estabelece a recall de agentes em execução, a conclusão do fluxo de trabalho ou a qualidade do relatório.
```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>
```
Leia a [metodologia de benchmark](https://github.com/strategic-automation/violin/blob/master/docs/BENCHMARKS.md) antes de publicar uma pontuação.
Ela define os requisitos de prova, reprodutibilidade, avaliação privada e divulgação
para um resultado credível.
## Desenvolvimento
```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
```
O gate de release verifica as superfícies de versão, a importação isolada de plugins, as ferramentas registradas, os esquemas gerados, os snapshots de skills, os contratos de documentação, o Ruff e a suíte de testes completa.
Testes de fumaça por plataforma:
- `scripts/smoke-test.sh` — teste de fumaça de release para Linux e Kali/Parrot
- `scripts/smoke-test.ps1` — teste de fumaça de bootstrap, escopo e resolução de alvos no Windows; a entrega de skills e a execução de alvos exigem o Hermes
Consulte [CONTRIBUTING.md](https://github.com/strategic-automation/violin/blob/master/CONTRIBUTING.md) para as regras de contribuição e
[SECURITY.md](https://github.com/strategic-automation/violin/blob/master/SECURITY.md) para o relato privado de vulnerabilidades.
## Uso responsável
O Violin destina-se a avaliações de segurança autorizadas. Os operadores são responsáveis pelo escopo, pelas aprovações, pela propriedade dos alvos, pelo tratamento de dados e pela legislação local.
## Apoie o Violin
O Violin é um projeto de código aberto mantido pela Strategic Automation Ltd.
Se o Violin for útil para você ou para sua organização, você pode
[patrocinar seu desenvolvimento contínuo](https://github.com/sponsors/Strategic-Automation).
O patrocínio apoia o desenvolvimento contínuo, os testes, a documentação, o trabalho de compatibilidade e as releases.
O Violin permanece disponível sob a licença MIT. O patrocínio não inclui suporte garantido, prioridade de funcionalidades ou influência sobre a política de segurança.
## Licença
MIT — consulte [LICENSE](https://github.com/strategic-automation/violin/blob/master/LICENSE).