## Funzionalità

- **Scansione di rete**: Scansiona reti e host per identificare servizi e vulnerabilità.
- **Rilevamento delle vulnerabilità**: Rileva vulnerabilità comuni come SQL injection, XSS e altro.
- **Report**: Genera report dettagliati in vari formati (HTML, PDF, JSON).
- **Integrazione**: Si integra con altri strumenti e API per migliorare le capacità di scansione.
- **Interfaccia utente**: Interfaccia web user-friendly per una facile gestione delle scansioni.

## Installazione

Per installare lo strumento, segui questi passaggi:

1. Clona il repository:
   ```bash
   git clone https://github.com/example/tool.git
   cd tool

python tool.py --target example.com --scan-type full

python tool.py --target 192.168.1.1 --scan-type basic --output json

Esegui la scansione del contesto recuperato prima che raggiunga il modello:```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

Collega le decisioni al tuo logging una volta sola e ogni chiamata viene registrata:```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 disattivato, record avvelenato: il record viene inviato via email all'attaccante e parte un trasferimento.
  Questi sono effetti collaterali reali, scritti su disco.
- Shield attivato, record avvelenato: la scansione indiretta intercetta il payload prima che il modello venga
  chiamato. Nessun effetto collaterale.
- Shield attivato, record pulito: l'agente risponde normalmente.
- Shield attivato, attacco **riformulato**: il payload viene riformulato come una normale nota aziendale, così
  il livello di firma *non* lo rileva — eppure nessun effetto collaterale si verifica, perché il
  gate delle azioni (sotto) blocca la chiamata allo strumento: la sua destinazione (l'indirizzo di esfiltrazione, l'account)
  è citata da contenuto non attendibile, cosa che nessuna riformulazione può nascondere.

Sii chiaro su cosa fa ogni livello. Il matching delle firme ha un limite reale: riformula
l'iniezione in modo che non corrisponda più a un pattern noto e il nucleo di regole non la intercetterà — ecco
perché il nucleo è un primo filtro, non un confine. La quarta esecuzione è la risposta onesta a
quel limite: non finge che il rilevamento sia migliorato; il rilevamento continua a mancare l'attacco
riformulato. Ciò che ferma la violazione è un livello *diverso* che ragiona sull'affidabilità dei dati
dietro un'azione piuttosto che sulla formulazione del testo. Tutte e quattro le condizioni sono applicate come invarianti
CI, così la demo non può regredire silenziosamente.

C'è anche un playground live: <https://reasongate-demo-nvgo.onrender.com>. Esegue il
nucleo a zero dipendenze, non richiede alcuna chiave API e non invia dati fuori dal server.

## Rilevatori nel nucleo

- **Normalizzazione / de-offuscamento.** Rimuove caratteri a larghezza zero, omoglifi cirillici,
  leetspeak (`1gn0re`), lettere spaziate e puntate (`i.g.n.o.r.e`) e payload base64, così
  una formulazione nota camuffata viene normalizzata di nuovo in qualcosa che il livello di pattern può rilevare.
- **Pattern di iniezione / jailbreak.** Un livello di regole per formulazioni note.
- **Iniezione indiretta.** Esegue la stessa scansione sui documenti recuperati e sull'output degli strumenti prima
  che raggiungano il modello.
- **Perdita di output e canary.** Segnala segreti e PII in uscita. Un token canary
  inserito nel prompt di sistema rende una fuga del prompt di sistema dimostrabile anziché ipotizzata.

Il motore di policy fonde questi segnali con un noisy-OR calibrato, così diversi segnali deboli
possono sommarsi fino a un blocco, mentre il rumore isolato da un prompt legittimo no.

## Il gate delle azioni (chiamate agli strumenti dell'agente)

I rilevatori chiedono "questo testo è un'iniezione?" — una domanda che puoi perdere riformulando. Il
gate delle azioni pone una domanda diversa, indipendente dalla formulazione: *questa azione può procedere, data
l'affidabilità dei dati che l'hanno prodotta?* È la difesa basata sulle capacità contro l'iniezione
indiretta — rompe la "trifecta letale" di contenuto non attendibile, una capacità sensibile e
una via d'uscita — e intercetta gli attacchi riformulati che il livello di firma manca.```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())

L'autorizzazione non ripulisce una destinazione contaminata: `authorized=True` cancella
la co-presenza, perché il principale ha richiesto l'azione — non cancella un valore di
argomento che risale a contenuto non attendibile, perché il principale non l'ha scelto.

### Integrarlo in un agente esistente```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))

**Nessun model judge è incluso in questo pacchetto.** Decidere se una frase è in conflitto con una
prose policy richiede un modello; se non configurato, il gate restituisce *"not evaluated"* anziché
un allow, perché una richiesta non verificata non deve mai sembrare una richiesta autorizzata. Un model judge
è anch'esso un bersaglio di injection, e questo è advisory — il layer che non si può contestare
è `ToolGate`, che vincola ciò che l'agente può *fare*.

### Misurato su AgentDojo

Il gate ha ora un proprio numero, sul benchmark costruito per questa minaccia
([AgentDojo](https://github.com/ethz-spylab/agentdojo): quattro suite di agenti che usano tool,
attaccate attraverso i dati che l'agente legge). Nessun modello nel loop — le ground-truth tool sequences
del benchmark stesso vengono riprodotte attraverso il gate come un agente completamente dirottato, e
i checker di AgentDojo valutano il risultato:

| | Attack success | Utility su traffico pulito |
|---|---:|---:|
| No gate | 97.4% | 100% |
| Argument taint only | **12.6%** | 64.9% |
| Strict (co-presence) | 3.4% | 41.2% |

Con un modello nel loop (Claude Haiku 4.5, banking) il quadro è ancora più netto: il
modello ha rifiutato ogni injection da solo, quindi il gate non ha aggiunto sicurezza ed è costato 12.5
punti di utility — un'assicurazione contro il caso in cui il giudizio del modello fallisce, con un prezzo.
Leggi entrambe le colonne. I 35 punti di utility che il gate costa sono destinazioni legittime che
l'agente ha letto da uno store — l'IBAN sulla fattura che gli è stato chiesto di pagare — che il taint non riesce a distinguere
dall'IBAN di un attaccante nello stesso file, perché non guarda le parole. Ciò che passa
sono tre forme documentate: obiettivi che sono letture, destinazioni cercate anziché citate,
e danno in un campo non-destinazione. Metodo, numeri per suite e avvertenze:
[RESULTS.md → The gate on AgentDojo](https://github.com/cgrtml/reasongate/blob/main/RESULTS.md#the-gate-on-agentdojo).

Il ragionamento dietro questo layer — il threat model, perché il text-detection è strutturalmente
insufficiente, e le garanzie *e non-garanzie* del gate — è documentato in
[docs/threat-model.md](https://github.com/cgrtml/reasongate/blob/main/docs/threat-model.md). Ciò che ancora manca, misurato e citato
da un corpus reale, è in [docs/coverage-gaps.md](https://github.com/cgrtml/reasongate/blob/main/docs/coverage-gaps.md).

## Benchmarks

Metodologia completa, l'harness e i risultati negativi sono in [RESULTS.md](https://github.com/cgrtml/reasongate/blob/main/RESULTS.md).
Tre numeri vale la pena leggerli insieme: cosa blocca in eccesso, cosa intercetta e quanto
ti costa per richiesta.

**Over-defense.** Molte guardie bloccano in eccesso prompt benigni che contengono semplicemente trigger word
come *ignore*, *system* o *bypass*. Su [NotInject](https://huggingface.co/datasets/leolee99/NotInject)
(339 prompt benigni ma pieni di trigger word) il rule core ha un **tasso di falsi positivi dello 0.0%**
e un'accuratezza benigna del 100% offline.

**Evasion recall su pattern noti.** Quando un attacco noto viene offuscato, la normalizzazione
ne recupera la maggior parte:

| | Recall sotto evasion | FPR | F1 |
|---|---:|---:|---:|
| Regex only | 21.2% | 3.3% | 0.349 |
| Core (normalize + indirect) | 78.1% | 6.7% | 0.871 |

Questo è il recall su *varianti offuscate di pattern che il core già conosce*. Non è
il recall su formulazioni nuove — quello è il valore 0% notato sopra.

**Costo per richiesta.** Misurato con `eval/latency.py` (p50/p95 per call path, Apple M3 Pro):

| Input | p50 | p95 |
|---|---:|---:|
| Chat prompt (60 chars) | 0.178 ms | 0.202 ms |
| 2 KB document, clean | 8.51 ms | 8.94 ms |
| 50 KB document, clean (the input ceiling) | 211 ms | 216 ms |
| `ToolGate.authorize` (a tool call, any size) | 0.020 ms | 0.021 ms |

Un processo gestisce ~5,400 chat prompt/s e il core non mantiene stato, quindi scala con
i processi. La parte che vale la pena sapere prima di distribuirlo: **l'input path è lineare nella
lunghezza dell'input — circa 4.2 ms per KB per un documento pulito, 1.7 ms una volta che un pattern ha già
matchato.** Alla dimensione di una chat è ~650x più economico di una guardia basata su modello (ProtectAI
deberta-v3, ~116 ms); a 50 KB è *peggio*, perché un transformer tronca a 512 token
e noi scansioniamo tutto. Il crossover è intorno ai 25 KB — fai passare documenti interi dal gate e li paghi.
L'action gate non ha questa proprietà: legge gli argomenti dei tool e la segment trust, non la prosa, quindi è gratuito a qualsiasi dimensione.

**L'ML detector (add-on separato).** Un classificatore basato su embedding gestisce gli
attacchi formulati in linguaggio naturale che il rule core non riesce a gestire. Questi sono i suoi numeri, non quelli del core:

| Setting | Recall | FPR | F1 |
|---|---:|---:|---:|
| Held-out test (~5.5k, combined real data) | 96.1% | 0.3% | 0.978 |
| 5-fold cross-validation | 95.5% ± 0.8 | 2.5% ± 1.3 | 0.963 ± 0.010 |
| Out-of-distribution (train A+B, test unseen C) | 87.6% | 10.9% | 0.882 |

Dati: `deepset/prompt-injections`, `jackhhao/jailbreak-classification`,
`xTRam1/safe-guard-prompt-injection`. Un risultato negativo che vale la pena dichiarare: un modello precedente
addestrato su dati sintetici ha ottenuto 0.98 di F1, ma un'ablazione ha mostrato che punteggiatura e casing
da soli raggiungevano 0.96 — il punteggio era un artefatto del generatore di dati. Il classificatore
spiegabile è ciò che ha fatto emergere questo. Il calo out-of-distribution da 0.97 a 0.88 è il
vero numero di generalizzazione: degrada, non collassa.

Riproduci qualsiasi parte — raggruppata per ciò di cui ogni script ha effettivamente bisogno, perché dalla 0.2.0
il modello addestrato vive nell'add-on e solo i benchmark del rule-core girano contro questo
repository da solo:```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