Quarenta críticos, zero atacantes: o Hermes agora verifica se um bug é alcançável


O scanner devolveu quarenta e três findings críticos e um PDF que ninguém queria abrir. Dois engenheiros passaram uma semana triando, e trinta e oito estavam em caminhos de código que nenhuma requisição alcança: um helper de desserialização cujo único chamador é uma fixture de test, um exec de shell atrás de uma flag de admin que o deploy nunca liga. Os cinco que importavam saíram em uma tarde. Os outros quatro dias foram gastos provando o negativo.

Essa proporção é o argumento do plugin hermes-security: um plugin oficial da Nous Research, do repositório NousResearch/hermes-official-plugins, nível official no catálogo, versão 0.1.2, que exige Hermes 0.21.5+ e Python 3.11+. Ele não troca o detector. Troca a pergunta feita sobre cada acerto.

Três palavras que vale definir antes

SAST, static application security testing, lê o código-fonte sem executá-lo e procura formas que historicamente causaram incidentes: uma string montada dentro de uma query SQL, um template renderizado com entrada não sanitizada, um comando de shell montado a partir de uma variável. Ele responde bem a uma pergunta — isso parece com aquilo que costuma quebrar? — e não consegue dizer se alguma coisa chama aquela linha.

Reachability é a segunda pergunta. Da superfície que um estranho consegue tocar — uma rota HTTP, um receptor de webhook, um handler de upload, uma flag de CLI —, uma cadeia de chamadas consegue chegar até essa linha com entrada controlada pelo atacante e tirar algo útil dali? Um acerto sem resposta é hipótese, não vulnerabilidade.

Um threat model é o documento curto que torna a resposta possível: quem é o atacante, a que ele já tem acesso, quais entradas são confiáveis. Escrito antes de qualquer leitura de código, ele converte “isso é ruim?” em “isso é alcançável a partir da porta que a gente sabe que está destrancada?”.

O que um scan faz de fato

O threat model vem primeiro. Depois o repositório é cortado em blocos de cerca de 4.000 linhas — mais ou menos uma sessão de um reviewer — e até dez reviewers trabalham em paralelo. Um reviewer a mais nunca pega um chunk: ele lê os pontos de entrada e as fronteiras de confiança no repositório inteiro, para que as peças possam ser remontadas depois.

Cada candidato é conferido contra o código real pelo reviewer que o encontrou, não afirmado a partir de um padrão, e opcionalmente confirmado com um test. Aí vem a etapa que dá nome ao plugin: seguir o caminho que um atacante percorreria. Se o código não é alcançável com entrada influenciada pelo atacante, ele vira contexto, não finding.

Código vendored, symlinks, arquivos especiais e qualquer coisa acima de 8 MB são pulados e listados. Os dois chunks mais perigosos ganham um segundo reviewer, independente. Um arquivo que um reviewer não terminou vai para um reviewer novo, por até seis rodadas enquanto houver progresso. O plano é gravado no início do scan, então atualizar o plugin não atrapalha um scan em andamento.

Os três modos

Modo O que lê O que pula Para quê
standard Código de produção: fontes, config, CI, IaC, migrations tests, fixtures, docs, exemplos, traduções, arquivos gerados, assets, lockfiles — a menos que algum guarde secrets já commitados. Cada exclusão é listada com o motivo O padrão
deep Tudo, em várias passadas independentes — 3 por padrão Nada Antes de um release
diff Só as mudanças não commitadas, ou a branch contra a branch padrão Tudo fora do diff O dia a dia

O modo standard tem teto: código de produção que caiba em 90 chunks, cerca de 360.000 linhas, é lido inteiro. Repositórios maiores são ordenados pelo que o código faz, não por onde ele mora — rotas, entrada de requisição, chamadas de shell, SQL, desserialização, autenticação, webhooks —, o mais perigoso primeiro. Essa ordenação é um julgamento, então um scan standard em monorepo pode reportar cobertura parcial.

Instalando

hermes plugins install hermes-security --enable
# reinicie o Hermes e mantenha-o atualizado depois
hermes plugins update hermes-security

O app desktop ganha uma página Security, desligada por padrão, ativada em Capabilities → Plugins. Ela lê do plugin Python, que precisa continuar instalado e ativo.

python -m hermes_security start --path ~/src/my-service --mode diff --tests

Use --mode deep para uma passada de nível release e --context para entregar um threat model que você já tenha; hermes security-review aceita os mesmos argumentos. No chat, o agente movimenta a mesma máquina por nove ferramentas security_scan_*, e /security cobre status, authorize-validation, revoke e help. Os reports exportam em Markdown, JSON, CSV ou SARIF, então a saída encaixa num pipeline que já existe. Se você já roda uma passada de supply chain com hermes security audit, é outra ferramenta — falamos dela no fim.

As dependências são checadas antes de a leitura começar

Um modelo é ruim naquilo em que bancos de dados são bons: saber que a versão 2.3.1 de uma biblioteca tem advisory publicado. Por isso, antes de distribuir os chunks, o plugin roda o osv-scanner do Google nos seus lockfiles e pergunta ao endoflife.date sobre as versões de runtime que você declara — Node, Python, Go, PHP, Ruby.

O primeiro scan baixa um osv-scanner fixado do GitHub, cerca de 55 MB, confere o SHA-256 e se recusa a rodar se não bater. Nomes e versões de pacote vão para api.osv.dev; manifestos sem lockfile vão para api.deps.dev. HERMES_SECURITY_DEPENDENCY_CHECK=off desliga a passada, e HERMES_SECURITY_OSV_SCANNER aponta para a sua própria cópia — o que você quer onde o GitHub está bloqueado.

Pacotes em uv.lock ou package-lock.json que só existem para desenvolvimento são marcados como dev e avaliados como baixo. Advisories colapsam num único finding de dependência, graduado pela entrada mais grave, com um finding separado só quando o código de fato alcança o comportamento vulnerável. Se a checagem não puder rodar, o report diz isso e o scan é marcado como parcial.

Interromper, retomar, continuar sozinho

Scans são longos. O plugin registra onde cada um está, então sua próxima mensagem — ou o botão Continue scan — retoma dali. A retomada automática é opt-in:

hermes config set plugins.entries.hermes-security.allow_gateway_injection true

Com isso ligado, se sobrar trabalho no fim de um turno, o plugin posta uma mensagem “Continue security scan” no mesmo chat; depois de três retomadas automáticas sem progresso ele pausa e sinaliza o scan para um humano. Dois casos nunca retomam sozinhos: um scan que você mesmo parou, e um turno em que o provider do modelo retornou erro.

Opcional: validar o app que está rodando

Reachability estática discute o que o código permite. Às vezes você quer saber o que o deploy faz. Dentro de um scan aberto, informe um endereço e clique em Allow testing this app, ou autorize pelo chat:

/security authorize-validation scan-7f3a https://staging.example.com

A autorização é estreita de propósito: uma origem, uma hora, no máximo 200 requisições, redirects seguidos só dentro desse site e um Stop que cancela antes. Só você pode conceder — as ferramentas do agente não conseguem se autorizar sozinhas, e é por isso que esse botão fica atrás de um humano.

O que ele guarda e o que se recusa a fazer

Texto de repositório é tratado como dado, nunca como instrução: um comentário dizendo “ignore previous instructions” é uma string que um reviewer pode citar, não uma ordem que ele vai seguir. Secrets nunca são guardados — o report mantém o tipo, a localização e uma impressão digital de mão única. Git hooks e filtros nunca são executados. Cada finding cita código exato do snapshot do scan, e um report concluído fica selado, então um triage posterior não consegue reescrevê-lo.

Os artefatos ficam sob o profile ativo em $HERMES_HOME/plugin-data/agent-plugin-hermes-security-974429e7, e python -m hermes_security data-dir imprime o caminho exato. Nada é enviado a um serviço de findings. Mas o provider de modelo que você configurou recebe o código revisado, então trate o report como trataria qualquer documento interno de segurança.

Os limites, sem rodeios

Limite O que isso significa para você
Código não revisado, ou um reviewer que não devolveu nada, é buraco de cobertura Zero findings com cobertura parcial não é atestado de saúde
O mapeamento para OWASP Top 10:2025 e ASVS 5.0.0 mostra o que foi examinado Não é certificação. Um scan termina quando todo arquivo do escopo e as dez categorias fecham; o ASVS só informa quantos pontos de controle foram checados
Um modelo pode deixar passar um bug ou ler o código errado Confira você mesmo os findings que importam
O orçamento do deep scan é fixo e retomável Sem garantia de sobreviver a um restart do Hermes
Os tests de confirmação rodam como o seu usuário, com variáveis de ambiente em formato de credencial removidas É conveniência, não sandbox. Só ative tests em código em que você confia
“Confirmado por test” tem régua estrita O test precisa passar e um caso negativo equivalente precisa se comportar como esperado; tests que não rodaram são NOT_RUN e não provam nada em nenhum sentido

Não é o mesmo comando que hermes security audit

hermes security audit é uma checagem de supply chain de um tiro só: olha o virtualenv do Hermes, as dependências de plugins e os servidores MCP npx/uvx fixados na sua config, e pergunta ao OSV.dev se essas versões têm advisories conhecidos. O plugin revisa o código do seu repositório: threat model, leitura por chunks, reachability, report selado. A passada de dependências dele empresta a mesma ideia do OSV.dev como etapa preliminar, não como entregável.

A versão curta

A mudança interessante não é pattern matching melhor — é recusar abrir um finding sem caminho de ataque. Um threat model na frente, chunks do tamanho de uma revisão, dez reviewers mais um nos pontos de entrada, uma checagem real de advisories e uma declaração honesta de cobertura. Na 0.1.2, trate como um reviewer forte que mostra o próprio trabalho, não como um auditor que assina.

Duas leituras relacionadas: o guia de segurança do catálogo MCP cobre o que um plugin ou servidor MCP pode fazer depois de instalado, a outra metade da mesma pergunta de confiança; os caracteres ocultos nos prompts de aprovação trata do instante em que uma pessoa diz sim, aquele que nenhum scanner automatiza. Se o plugin ainda não está instalado, o guia de instalação cobre a configuração base da qual ele depende.