## Instalação

### Requisitos

- Python 3.8+
- pip

### Instalar a partir do código-fonte

```bash
git clone https://github.com/example/kitploit-tool.git
cd kitploit-tool
pip install -r requirements.txt

pip install kitploit-tool

python kitploit.py --target example.com

python kitploit.py -t example.com -o results.txt

python kitploit.py -t example.com -v

timeout: 30
threads: 10
user_agent: "KitploitTool/1.0"

Examine o contexto recuperado antes que ele chegue ao modelo:```python
res = shield.protect(user_prompt, my_llm, context=retrieved_docs)
if res.action == "block":
    ...   # a poisoned document was caught before the model saw it

Integre as decisões no seu logging uma vez e cada chamada é registada:```python
from reasongate import Shield, log_sink, file_sink

shield = Shield(audit_hook=log_sink)                    # -> "reasongate.audit" logger
shield = Shield(audit_hook=file_sink("audit.jsonl"))    # -> JSON-Lines, SIEM-ready

- Shield desligado, registro envenenado: o registro é enviado por e-mail ao atacante e uma transferência é disparada.
  Esses são efeitos colaterais reais, gravados em disco.
- Shield ligado, registro envenenado: a varredura indireta captura o payload antes que o modelo seja
  chamado. Nenhum efeito colateral.
- Shield ligado, registro limpo: o agente responde normalmente.
- Shield ligado, ataque **reformulado**: o payload é reescrito como uma nota comercial comum para
  que a camada de assinatura *não* o reconheça — e ainda assim nenhum efeito colateral acontece, porque o
  portão de ação (abaixo) bloqueia a chamada de ferramenta: seu destino (o endereço de exfiltração, a conta)
  é citado a partir de conteúdo não confiável, o que nenhuma reformulação consegue esconder.

Seja claro sobre o que cada camada faz. A correspondência de assinaturas tem um limite real: reformule a
injeção para que ela não corresponda mais a um padrão conhecido e o núcleo de regras não a capturará — é
por isso que o núcleo é um primeiro filtro, não uma fronteira. A quarta execução é a resposta honesta a
esse limite: ela não finge que a detecção melhorou; a detecção ainda perde o ataque reformulado. O que
impede a violação é uma camada *diferente* que raciocina sobre a confiança dos dados
por trás de uma ação, em vez da redação do texto. Todas as quatro condições são aplicadas como invariantes de CI
para que a demonstração não possa regredir silenciosamente.

Há também um playground ao vivo: <https://reasongate-demo-nvgo.onrender.com>. Ele executa o
núcleo sem dependências, não precisa de chave de API e não envia dados para fora do servidor.

## Detectores no núcleo

- **Normalização / desofuscação.** Remove caracteres de largura zero, homoglifos cirílicos,
  leetspeak (`1gn0re`), letras espaçadas e pontuadas (`i.g.n.o.r.e`) e payloads em base64, para que
  uma frase conhecida disfarçada seja normalizada de volta para algo que a camada de padrões possa reconhecer.
- **Padrões de injeção / jailbreak.** Uma camada de regras para frases conhecidas.
- **Injeção indireta.** Executa a mesma varredura em documentos recuperados e na saída de ferramentas antes
  que cheguem ao modelo.
- **Vazamento de saída e canário.** Sinaliza segredos e PII na saída. Um token canário
  plantado no prompt do sistema torna um vazamento do prompt do sistema comprovável em vez de suposto.

O motor de políticas funde esses sinais com um noisy-OR calibrado, para que vários sinais fracos
possam somar-se a um bloqueio, enquanto ruído isolado de um prompt legítimo não o faça.

## O portão de ação (chamadas de ferramentas do agente)

Os detectores perguntam "este texto é uma injeção?" — uma pergunta que você pode perder reformulando. O
portão de ação faz uma pergunta diferente, independente da redação: *esta ação pode prosseguir, dada
a confiança dos dados que a produziram?* É a defesa baseada em capacidade contra injeção indireta —
quebrando a "tríade letal" de conteúdo não confiável, uma capacidade sensível e
uma via de saída — e captura os ataques reformulados que a camada de assinaturas perde.```python
from reasongate import ToolGate, ToolPolicy, Segment

gate = ToolGate([
    ToolPolicy("transfer_funds", sensitive=True, destination_args=("to_account",)),
    ToolPolicy("send_email",     sensitive=True, destination_args=("to",)),
])

record = Segment(text=retrieved_doc, source="crm", trust="untrusted")
decision = gate.authorize(
    {"name": "transfer_funds", "args": {"to_account": "9900", "amount": "$84,200"}},
    context=[record],
)
decision.allowed       # False — the destination account is quoted from untrusted content
print(decision.explain())

A autorização não legitima um destino contaminado: `authorized=True` limpa a
co-presença, porque o principal solicitou a ação — não limpa um valor de argumento
que remonta a conteúdo não confiável, porque o principal não o escolheu.

### Integrando-o a um agente existente```python
from reasongate.adapters.toolcalls import from_anthropic, refusal_result
from reasongate.catalog import infer_policies, describe

print(describe(infer_policies([t["name"] for t in tools])))   # draft policies, then correct them

for call in from_anthropic(response.content):
    decision = session.authorize(call)
    if not decision.allowed:
        results.append(refusal_result(call, decision))        # the model is told why
    else:
        results.append(run(call))

**Nenhum juiz de modelo acompanha este pacote.** Decidir se uma frase entra em conflito com uma
política em prosa exige um modelo; sem configuração, o gate retorna *"não avaliado"* em vez de
uma permissão, porque uma requisição não verificada nunca deve parecer uma requisição liberada. Um juiz de modelo
é também, ele próprio, um alvo de injeção, e isto é consultivo — a camada com a qual não se pode argumentar
é o `ToolGate`, que restringe o que o agente pode *fazer*.

### Medido no AgentDojo

O gate tem agora números próprios, no benchmark construído para esta ameaça
([AgentDojo](https://github.com/ethz-spylab/agentdojo): quatro suítes de agentes que usam ferramentas,
atacadas através dos dados que o agente lê). Sem modelo no loop — as próprias
sequências de ferramentas ground-truth do benchmark são reproduzidas através do gate como um agente totalmente sequestrado, e
os próprios checkers do AgentDojo pontuam o resultado:

| | Sucesso do ataque | Utilidade em tráfego limpo |
|---|---:|---:|
| Sem gate | 97,4% | 100% |
| Apenas taint de argumento | **12,6%** | 64,9% |
| Estrito (co-presença) | 3,4% | 41,2% |

Com um modelo no loop (Claude Haiku 4.5, banking) o quadro é ainda mais nítido: o
modelo recusou todas as injeções por conta própria, então o gate não acrescentou segurança e custou 12,5
pontos de utilidade — seguro contra o caso em que o julgamento do modelo falha, com preço.
Leia ambas as colunas. Os 35 pontos de utilidade que o gate custa são destinos legítimos que o
agente leu de uma loja — o IBAN na fatura que lhe foi pedido para pagar — que o taint não consegue distinguir
do IBAN de um atacante no mesmo arquivo, porque não olha para as palavras. O que passa
são três formas documentadas: objetivos que são leituras, destinos consultados
em vez de citados, e dano num campo que não é de destino. Método, números por suíte e ressalvas:
[RESULTS.md → The gate on AgentDojo](https://github.com/cgrtml/reasongate/blob/main/RESULTS.md#the-gate-on-agentdojo).

O raciocínio por trás desta camada — o modelo de ameaça, por que a detecção de texto é estruturalmente
insuficiente, e as garantias *e não-garantias* do gate — está escrito em
[docs/threat-model.md](https://github.com/cgrtml/reasongate/blob/main/docs/threat-model.md). O que ele ainda deixa passar, medido e citado
de um corpus real, está em [docs/coverage-gaps.md](https://github.com/cgrtml/reasongate/blob/main/docs/coverage-gaps.md).

## Benchmarks

Metodologia completa, o harness e os resultados negativos estão em [RESULTS.md](https://github.com/cgrtml/reasongate/blob/main/RESULTS.md).
Três números valem a pena ser lidos em conjunto: o que ele bloqueia em excesso, o que ele apanha e o que ele
custa por requisição.

**Over-defense.** Muitos guards bloqueiam em excesso prompts benignos que apenas contêm palavras-gatilho
como *ignore*, *system* ou *bypass*. No [NotInject](https://huggingface.co/datasets/leolee99/NotInject)
(339 prompts benignos mas carregados de palavras-gatilho) o núcleo de regras tem uma **taxa de falsos positivos de 0,0%**
e 100% de precisão benigna offline.

**Recall de evasão em padrões conhecidos.** Quando um ataque conhecido é ofuscado, a normalização
recupera a maior parte dele:

| | Recall sob evasão | FPR | F1 |
|---|---:|---:|---:|
| Apenas regex | 21,2% | 3,3% | 0,349 |
| Núcleo (normalize + indirect) | 78,1% | 6,7% | 0,871 |

Isto é recall em *variantes ofuscadas de padrões que o núcleo já conhece*. Não é
recall em formulações novas — isso é o valor de 0% indicado acima.

**Custo por requisição.** Medido com `eval/latency.py` (p50/p95 por caminho de chamada, Apple M3 Pro):

| Entrada | p50 | p95 |
|---|---:|---:|
| Prompt de chat (60 chars) | 0,178 ms | 0,202 ms |
| Documento de 2 KB, limpo | 8,51 ms | 8,94 ms |
| Documento de 50 KB, limpo (o teto de entrada) | 211 ms | 216 ms |
| `ToolGate.authorize` (uma chamada de ferramenta, qualquer tamanho) | 0,020 ms | 0,021 ms |

Um processo trata ~5.400 prompts de chat/s e o núcleo não mantém estado, por isso escala com
processos. A parte que vale a pena saber antes de o implementar: **o caminho de entrada é linear no
comprimento da entrada — cerca de 4,2 ms por KB para um documento limpo, 1,7 ms assim que um padrão já
correspondeu.** No tamanho de chat isso é ~650x mais barato do que um guard baseado em modelo (ProtectAI
deberta-v3, ~116 ms); a 50 KB é *pior*, porque um transformer trunca a 512 tokens
e nós analisamos tudo. O ponto de cruzamento é por volta dos 25 KB — faça o gate de documentos inteiros e paga
por eles. O gate de ação não tem esta propriedade: lê argumentos de ferramentas e confiança de segmento,
não prosa, por isso é gratuito em qualquer tamanho.

**O detector de ML (add-on separado).** Um classificador baseado em embeddings trata os
ataques com formulação natural que o núcleo de regras não consegue. Estes são os seus números, não os do núcleo:

| Configuração | Recall | FPR | F1 |
|---|---:|---:|---:|
| Teste held-out (~5,5k, dados reais combinados) | 96,1% | 0,3% | 0,978 |
| Validação cruzada de 5 folds | 95,5% ± 0,8 | 2,5% ± 1,3 | 0,963 ± 0,010 |
| Fora da distribuição (treino A+B, teste C não visto) | 87,6% | 10,9% | 0,882 |

Dados: `deepset/prompt-injections`, `jackhhao/jailbreak-classification`,
`xTRam1/safe-guard-prompt-injection`. Um resultado negativo que vale a pena declarar: um modelo anterior
treinado em dados sintéticos obteve 0,98 de F1, mas uma ablação mostrou que apenas a pontuação e as maiúsculas/minúsculas
alcançavam 0,96 — a pontuação era um artefacto do gerador de dados. O classificador explicável
foi o que revelou isso. A queda fora da distribuição de 0,97 para 0,88 é o
número real de generalização: degrada-se, não colapsa.

Reproduza qualquer parte disto — agrupado pelo que cada script realmente precisa, porque desde 0.2.0
o modelo treinado vive no add-on e apenas os benchmarks do núcleo de regras correm contra este
repositório isoladamente:```bash
# Offline, no key, no add-on — runs against this repo as-is:
python eval/public_bench.py     # over-defense on NotInject (339 benign)
python eval/adversarial.py      # evasion robustness of the rule core
python eval/latency.py          # cost per request: p50/p95/p99 and throughput

# Needs `pip install reasongate[eval]` and a VOYAGE_API_KEY (embeddings):
python eval/pipeline_real.py    # train/val/test with a validation-tuned threshold
python eval/validate.py         # leakage check, trivial baselines, 5-fold CV, 5x2cv

# Needs the enterprise add-on (the trained model moved there in 0.2.0):
python eval/ood_test.py         # out-of-distribution generalization
python eval/head_to_head.py     # vs ProtectAI deberta-v3

# Needs `pip install agentdojo` (Python 3.10+), no key — the action gate on AgentDojo:
python eval/agentdojo_gate.py   # ASR and utility, gate off / taint / strict