exfil-scan

Analise saídas de LLM e conteúdo gerado por IA para sinais de exfiltração de dados antes que eles cheguem a usuários, logs ou sistemas a jusante.

1) Por que o exfil-scan existe

Aplicações modernas de LLM processam rotineiramente prompts sensíveis, documentos internos, respostas de API e dados de usuários. Isso cria uma nova fronteira de segurança: a camada de saída.

A família de ataques EchoLeak (incluindo CVE-2025-32711) demonstrou como payloads ocultos ou ofuscados podem ser embutidos em texto gerado e usados para exfiltrar dados por meio de ferramentas, links ou cadeias de parsing.

Scanners tradicionais focam em arquivos, dependências e tráfego em runtime. Eles não inspecionam a saída gerada pelo modelo de uma forma especificamente projetada para isso.

exfil-scan fornece um "scanner de vírus para respostas de LLM":

• inspeciona texto simples, JSON, markdown e logs
• identifica seis classes de padrões suspeitos de exfiltração
• reporta achados com severidade e localização
• integra-se de forma limpa a fluxos de trabalho de CI/CD e desenvolvimento local

2) O que ele detecta

3) Destaques do recurso

• Três perfis de sensibilidade: low, medium, high
• Suporte a override de configuração via YAML
• Entrada de stdin, arquivo único ou diretório
• Saída em text, json, markdown ou html
• Códigos de saída estáveis para automação
• API Python limpa para incorporação em outras ferramentas

4) Instalação

Instalar a partir do código-fonte

git clone https://github.com/your-org/exfil-scan.git
cd exfil-scan
pip install -e .

Instalação padrão via pip (quando publicada)

pip install exfil-scan

Instalação para desenvolvimento

pip install -e ".[dev]"
pytest

5) Início rápido

Escanear saída de LLM via pipe

echo 'api_key: sk-ABCDEFGHIJKLMNOPQRSTUVWXYZ123456' | exfil-scan

Escanear um único arquivo

exfil-scan --input output.txt

Escanear um diretório recursivamente

exfil-scan --directory ./model-logs --recursive

6) Referência de opções da CLI

Notas:

• Use --input ou --directory, não ambos.
• Se nenhum caminho for fornecido, a ferramenta lê de stdin.
• Se houver achados, o processo encerra com o código 1.

7) Exemplos de uso por formato de saída

Saída em texto simples

exfil-scan --input suspicious.txt --format text

Estilo esperado:

exfil-scan report
=================
Scanned targets: 1
Total findings: 2

1. [HIGH] metadata_leaks/known_token_format:openai_key
   Location: suspicious.txt:1:10
   Description: Matched known credential/token format (openai_key).

Saída JSON

exfil-scan --input suspicious.txt --format json

Forma esperada:

{
  "finding_count": 2,
  "scanned_targets": ["suspicious.txt"],
  "findings": [
    {
      "category": "metadata_leaks",
      "rule": "known_token_format:openai_key",
      "severity": "HIGH",
      "description": "Matched known credential/token format (openai_key).",
      "location": "suspicious.txt:1:10",
      "snippet": "..."
    }
  ]
}

Saída HTML

exfil-scan --directory ./outputs --recursive --format html --output report.html

Comportamento esperado:

• Gera uma página HTML independente com tabela de achados
• Escapa o conteúdo para renderização segura
• Inclui severidade, categoria, regra, localização, descrição

Saída Markdown

exfil-scan --input suspicious.txt --format markdown --output report.md

Estilo esperado:

# exfil-scan Report

- Scanned targets: 1
- Total findings: 2

8) Configuração e sensibilidade

O repositório acompanha o arquivo default-config.yaml. Você pode passar seu próprio arquivo com --config.

Ajuste de sensibilidade:

• low: menos falsos positivos, limites maiores
• medium: padrões equilibrados
• high: captura padrões mais sutis

Substituição de sensibilidade pela CLI:

exfil-scan --input out.txt --sensitivity high

9) Padrões personalizados e ajuste de política

Você pode adicionar seus próprios formatos de token e chaves de metadados:

sensitivity: medium
rules:
  metadata_keys:
    - api_key
    - db_password
    - internal_token
  token_patterns:
    custom_jwt: "\\beyJ[A-Za-z0-9_\\-]{10,}\\.[A-Za-z0-9_\\-]{10,}\\.[A-Za-z0-9_\\-]{10,}\\b"
    corp_secret: "\\bcorp_[A-Za-z0-9]{24,}\\b"

Em seguida, execute:

exfil-scan --input response.log --config ./my-config.yaml

10) Visão geral da arquitetura

Responsabilidades dos módulos:

• exfil_scan/cli.py: parsing de argumentos, seleção de entrada, renderização de saída, tratamento de saída
• exfil_scan/config.py: padrões, carregamento de YAML, merge recursivo, normalização de perfis
• exfil_scan/scanner.py: seis mecanismos de detecção, dataclasses de achados, formatação de relatórios
• tests/test_scan.py: testes de regressão de detecção e de formatos de saída

Fluxo de execução:

1. A CLI faz o parsing dos argumentos.
2. A configuração carrega padrões + overrides opcionais.
3. O scanner lê texto de stdin/arquivo/diretório.
4. Cada categoria habilitada é executada de forma independente.
5. Os achados são ordenados por severidade e renderizados.
6. O código de saída comunica sucesso/falha/erro para automação.

11) Códigos de saída

Isso torna a integração com CI direta:

exfil-scan --directory ./artifacts --recursive --format json --output exfil-report.json

Se qualquer detecção for encontrada, sua tarefa pode falhar rapidamente com base no código de saída 1.

12) Testes

Execute os testes:

pytest

A cobertura inclui:

• todas as seis categorias de detecção
• formatação de relatório nos quatro modos de saída
• asserções no nível de regra para comportamento estável

13) Notas de segurança

exfil-scan é um scanner heurístico. Ele foi projetado para reduzir riscos e expor saídas suspeitas, não para comprovar a segurança do conteúdo.

Padrão de implantação recomendado:

1. execute o scanner no CI em prompts de teste e saídas de fixtures
2. execute o scanner em guardrails de produção sobre respostas geradas
3. encaminhe os achados para triagem de analistas e telemetria
4. ajuste continuamente os limites de configuração com base na revisão de falsos positivos

14) Licença

Este projeto está licenciado sob a Licença MIT. Consulte LICENSE para os termos completos.

15) Contribuição

Contribuições são bem-vindas. Ao abrir um PR, inclua:

• etapas claras de reprodução
• comportamento esperado e real
• testes para a nova lógica de detecção
• atualizações de documentação ao introduzir novas regras