Como testar a robustez de prompts contra jailbreak com o Garak

O Garak é um scanner de vulnerabilidades de modelos de linguagem mantido pela NVIDIA, de código aberto (licença Apache 2.0). Ele dispara contra o seu modelo ou endpoint uma bateria de ataques conhecidos, como jailbreaks do tipo DAN, injeção de prompt, codificações que tentam driblar filtros e extração do prompt de sistema, e usa detectores automáticos para marcar quais respostas indicam falha. Na prática, funciona como um teste de intrusão automatizado para o seu assistente de IA.

Para testar a robustez do seu prompt, e não só do modelo cru, você aponta o Garak para o endpoint da sua aplicação (via REST) ou passa o seu prompt de sistema na configuração. O resultado é um relatório JSONL e um resumo em HTML com taxa de falha por probe. Este guia mostra a instalação, as três formas mais comuns de conectar o alvo, a leitura do relatório, a integração no CI e os limites, especialmente para aplicações em português.

Resumo rápido

• Instale com python -m pip install -U garak (Python 3.11 ou superior).
• Escolha o alvo com --target_type e --target_name (openai, ollama, rest e outros) e os ataques com --spec.
• Para testar o prompt da sua aplicação, use o gerador REST apontando para a sua API ou defina run.system_prompt num arquivo de configuração.
• Leia o relatório pelas entradas eval e confira as respostas marcadas no hit log antes de concluir qualquer coisa.
• Os probes e vários detectores são em inglês: em assistentes em português, espere falsos positivos e revise manualmente.

O que o Garak testa e como ele funciona

O Garak organiza os testes em quatro tipos de componente:

• Generators: o conector com o alvo (OpenAI, Ollama, Hugging Face, REST genérico, Bedrock, NIM e outros).
• Probes: os ataques. Exemplos de famílias: dan (jailbreaks no estilo “Do Anything Now”), promptinject, latentinjection (instruções escondidas em documentos), encoding (injeção via Base64 e outras codificações), sysprompt_extraction, leakreplay, packagehallucination e xss.
• Detectors: analisam cada resposta e decidem se houve “hit”, isto é, se o ataque funcionou.
• Harness: orquestra a execução. O padrão, probewise, roda cada probe com os detectores que ele recomenda.

Por padrão, cada prompt é enviado 5 vezes (generations: 5), porque um modelo pode resistir na primeira tentativa e ceder na terceira. Se você já tem testes manuais de injeção, o Garak complementa o que mostramos em testes de segurança contra injeção de prompt com um catálogo pronto de ataques.

Instalação

A documentação oficial pede Python 3.11 ou mais recente. Use um ambiente isolado:

python -m venv .venv && source .venv/bin/activate
python -m pip install -U garak
garak --version
garak --list_probes --spec probes.dan

Para a versão de desenvolvimento, o repositório indica python -m pip install -U git+https://github.com/NVIDIA/garak.git@main. O comando --list_probes aceita -v para mostrar uma tabela com tier e descrição de cada probe, e --plugin_info probes.dan.Dan_11_0 mostra os detalhes de um probe específico.

Rodando contra um endpoint: OpenAI, Ollama ou REST

OpenAI

Defina a chave na variável OPENAI_API_KEY e indique o modelo. O exemplo do próprio README usa o probe de codificação; aqui, um jailbreak DAN:

export OPENAI_API_KEY="..."
garak --target_type openai --target_name gpt-5-nano --spec probes.dan.Dan_11_0

Antes de escolher o modelo, confira a lista atual na documentação da OpenAI; nossa página de integrações com OpenAI e ChatGPT reúne os recursos disponíveis.

Ollama (modelo local)

O gerador ollama conecta por padrão em 127.0.0.1:11434 e aceita o nome curto do modelo que você baixou:

garak --target_type ollama --target_name llama3.2 --spec probes.promptinject

É uma boa forma de testar sem custo de API antes de escolher um modelo aberto; veja guardrails com NeMo e Llama Guard para as defesas que você pode colocar na frente dele.

REST: o jeito de testar a sua aplicação

Testar o modelo cru mede o modelo. Testar a sua API mede o que o cliente realmente recebe: prompt de sistema, RAG, filtros e guardrails juntos. O gerador rest recebe um JSON de configuração em que $INPUT vira o prompt de ataque e $KEY vira o valor da variável REST_API_KEY:

{
  "rest": {
    "RestGenerator": {
      "name": "assistente-loja",
      "uri": "https://staging.minhaloja.com.br/api/chat",
      "method": "post",
      "headers": { "Authorization": "Bearer $KEY" },
      "req_template_json_object": { "mensagem": "$INPUT" },
      "response_json": true,
      "response_json_field": "resposta"
    }
  }
}

garak --target_type rest -G assistente.json --spec probes.dan,probes.sysprompt_extraction

Se a resposta vier aninhada, response_json_field aceita JSONPath quando começa com $. Rode sempre contra homologação, nunca contra produção com clientes reais.

Testando o seu prompt de sistema com arquivo de configuração

Se você quer comparar versões do prompt de sistema sem subir a aplicação, use um YAML. A chave run.system_prompt é enviada pelos probes aos geradores que suportam chat, e run.spec seleciona os ataques com listas de inclusão e exclusão:

run:
  system_prompt: "Você é o assistente da Loja X. Responda só sobre pedidos e trocas."
  generations: 5
  spec:
    include:
      - tag: owasp:llm01
      - probes.dan
    exclude:
      - probes.dan.DanInTheWild
plugins:
  target_type: openai
  target_name: gpt-5-nano

garak --config prompt_v2.yaml --report_prefix prompt_v2

Com --report_prefix, os arquivos saem com nome previsível (prompt_v2.report.jsonl), o que facilita comparar a versão 1 com a 2. O seletor tag:owasp:llm01 pega todos os probes marcados como injeção de prompt; tier:1 limita aos probes classificados como mais críticos.

Como ler o relatório

Ao final, o Garak informa onde gravou três arquivos, por padrão na pasta garak_runs dentro do diretório de dados do usuário ($XDG_DATA_HOME/garak):

Cada entrada eval traz probe, detector, passed, fails e total_evaluated. A documentação também descreve a métrica hit@k: com 5 gerações, hit@5 indica se cada prompt quebrou o alvo pelo menos uma vez, o que reflete melhor um atacante insistente do que a média simples. Intervalos de confiança aparecem quando a amostra tem pelo menos 30 itens.

A regra de leitura é simples: o número aponta onde olhar, o hit log diz se é real. Abra as respostas marcadas antes de concluir que o prompt falhou.

Integrando no CI

O Garak não falha o processo quando encontra hits; ele termina normalmente e grava o relatório. Para bloquear um deploy, leia as entradas eval e decida o critério. Um exemplo com GitHub Actions:

jobs:
  garak:
    runs-on: ubuntu-latest
    env:
      XDG_DATA_HOME: ${{ github.workspace }}/.xdg
      REST_API_KEY: ${{ secrets.STAGING_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: python -m pip install -U garak
      - run: garak --target_type rest -G assistente.json --spec tag:owasp:llm01 --report_prefix ci
      - run: python checar_garak.py .xdg/garak/garak_runs/ci.report.jsonl

import json, sys
falhas = [e for e in map(json.loads, open(sys.argv[1], encoding="utf-8"))
          if e.get("entry_type") == "eval" and e.get("fails", 0) > 0]
for e in falhas:
    print(f'{e["probe"]} / {e["detector"]}: {e["fails"]} de {e["total_evaluated"]}')
sys.exit(1 if falhas else 0)

Comece em modo informativo (publicando o HTML como artefato) e só torne o job bloqueante depois de calibrar quais probes fazem sentido para a sua aplicação. Rodar a bateria completa a cada commit é lento e caro; um subconjunto por tag no pull request e a bateria maior em agendamento noturno costuma equilibrar melhor. É a mesma lógica dos testes de regressão para agentes.

Relação com o OWASP Top 10 para LLM

Os probes do Garak carregam tags owasp:llm01 a owasp:llm10, e você pode agrupar o relatório com --taxonomy owasp. Há uma pegadinha: as descrições dessas tags no Garak seguem a numeração da primeira versão da lista (por exemplo, owasp:llm02 é “Insecure Output Handling”), enquanto a edição 2025 do OWASP renumerou os itens (LLM02:2025 é “Sensitive Information Disclosure” e “Improper Output Handling” virou LLM05). Ao montar relatórios de conformidade, mapeie pelo nome do risco, não só pelo número.

LLM01 (Prompt Injection) é o mesmo nas duas versões e é onde o Garak tem mais cobertura. A própria documentação avisa que suportar uma taxonomia não significa cobrir todos os seus itens. Riscos como agência excessiva (LLM06:2025) ou fraquezas de vetores e embeddings (LLM08:2025) dependem da arquitetura da sua aplicação e pedem revisão de desenho, não só scanner.

Limitações: português e falsos positivos

• Ataques em inglês. Os prompts dos probes foram escritos em inglês. Um assistente que só responde em português pode resistir por motivos que não têm a ver com segurança, ou ceder a ataques em português que o catálogo não tem.
• Detectores em inglês. O detector mitigation.MitigationBypass, usado como detector estendido dos probes DAN, procura frases de recusa em inglês. Uma recusa correta como “Não posso ajudar com isso” pode ser contada como falha. O detector dan.DAN procura marcadores como “[DAN]” e “DAN Mode enabled”, que podem aparecer quando o modelo apenas explica o que é o ataque.
• Tradução existe, com limites. O Garak permite traduzir prompts e gatilhos de probes e detectores com run.target_lang e langproviders (modelos Hugging Face, DeepL, Riva ou Google Cloud Translation). A documentação avisa que o recurso ainda é fortemente acoplado ao inglês e que detectores baseados em modelos Hugging Face carregam majoritariamente modelos em inglês.
• Cobertura não é garantia. Passar em todos os probes mostra resistência a ataques conhecidos, não a ataques novos.

Exemplo: assistente de atendimento de um e-commerce em Recife

Imagine uma loja online de eletrodomésticos em Recife (PE) com um assistente no site e no WhatsApp que consulta pedidos e explica a política de trocas. O prompt de sistema proíbe falar de outros clientes, inventar descontos e revelar as próprias instruções.

O time sobe a versão nova do prompt em homologação, configura o gerador REST apontando para a API de chat e roda probes.dan, probes.sysprompt_extraction e a tag owasp:llm01. No hit log, separa três grupos: respostas em que o assistente realmente revelou trechos do prompt (falha real, corrigir antes do deploy), recusas em português marcadas como falha pelo detector em inglês (falso positivo, documentar) e casos ambíguos (revisar com o responsável pelo produto). Depois, cria meia dúzia de ataques próprios em português com base nos casos reais do atendimento e mantém os dois conjuntos no CI. Dados de pedidos usados nos testes devem ser fictícios, seguindo o que explicamos sobre LGPD na implantação de IA.

Erros comuns

• Testar só o modelo cru. O cliente conversa com a sua aplicação inteira; teste o endpoint dela.
• Confiar no número sem ler o hit log. Em português, parte das falhas pode ser recusa não reconhecida.
• Rodar todos os probes em todo commit. Fica lento e caro; selecione por tag ou tier.
• Apontar para produção. Os ataques geram conteúdo indesejado e consomem cota. Use homologação.
• Usar flags antigas. --model_type e --model_name foram substituídos por --target_type e --target_name, e --probes está marcado como obsoleto em favor de --spec.
• Tratar o scanner como auditoria completa. Ele cobre ataques conhecidos; arquitetura, permissões e ferramentas do agente precisam de revisão própria.

Perguntas frequentes

O Garak é gratuito?

Sim, é open source sob licença Apache 2.0. O custo vem das chamadas ao modelo testado: cada probe envia vários prompts, cada um repetido pelo número de gerações.

Funciona com Claude, Gemini ou outros provedores?

O repositório inclui geradores para vários provedores e um gerador LiteLLM, além do REST genérico, que cobre qualquer API HTTP. Use garak --list_generators para ver o que a sua versão traz.

Quanto tempo leva uma varredura?

Depende do número de probes, das gerações e da latência do alvo. Para acelerar com APIs remotas, a documentação recomenda aumentar --parallel_attempts.

Posso escrever probes em português?

Sim. A documentação tem um guia para criar probes próprios, e é o caminho recomendado para cobrir ataques no idioma da sua aplicação.

Garak substitui guardrails?

Não. O Garak mede; guardrails e boas práticas de prompt defendem. Use o scanner para verificar se as defesas funcionam.

Fontes e leitura recomendada

• NVIDIA/garak: repositório oficial
• Garak: documentação de referência
• Garak: gerador REST
• Garak no PyPI
• OWASP Top 10 for LLM Applications 2025
• OWASP: LLM01 Prompt Injection