domains(redteam): add admina-redteam detection-efficacy suite

[lorenzofradeani]

Summary

admina-redteam: una suite riproducibile di efficacia di detection che misura quanto
i detector di Admina riconoscono gli attacchi (recall / precision / F1 / FPR), non solo
quanto sono veloci. Esegue il firewall anti-injection, il redattore PII e il loop-breaker su
corpora originali multilingue (EN/IT/FR/ES/DE) sigillati con hash, su entrambi i motori
(Python e Rust), e produce uno scorecard JSON + Markdown con la matrice Python-vs-Rust per
classe. Un gate CI "soft" fa fallire la build su regressioni di recall o nuovi falsi
positivi rispetto a un baseline committato. È solo misurazione: nessun detector viene
modificato. Risponde al gap dichiarato in MODEL_CARD.md ("Admina non spedisce una suite di
benchmark di accuratezza… i contributi sono benvenuti e prioritari").

Type

• Bug fix
• New feature
• Documentation
• CI / tooling
• Refactor / cleanup

Primo baseline misurato (corpus proprio di Admina, non un punteggio PINT di terze parti)

Detector	Recall Python	Recall Rust	Falsi positivi (py · rust)
injection	57%	35%	0/27 · 0/27
pii	100%	66%	6/16 · 0/16
loop	82%	91%	0/11 · 0/11

Gap reali emersi (matrice completa per classe: python scripts/redteam.py --format md):

• Firewall Rust 0% sugli attacchi offuscati (base64 / homoglyph / leetspeak / ROT13 /
  hyphenation) che il Python cattura al 100%: al motore Rust manca il passaggio
  normalize_text(), quindi il path "veloce" è anche il meno accurato.
• PII Rust 0% su IBAN / codice fiscale / DNI (è solo-regex, con meno pattern del Python).
• Loop-breaker Python si perde i loop "counter-reset" (finestra sugli ultimi 5 messaggi)
  che il motore Rust (finestra piena) invece cattura.
• I 6 falsi positivi PII del Python sono lo spaCy NER che etichetta erroneamente
  PERSON/ORG su frasi negative non inglesi (il Rust, solo-regex, non li produce).

Come si usa

python scripts/redteam.py                                    # scorecard completo, entrambi i motori
python scripts/redteam.py --corpus injection --engine python --format md

Il gate CI è in tests/test_redteam_efficacy.py e confronta l'esecuzione live con il
committato admina/redteam/baselines/baseline.json.

Design

• Libreria admina/redteam/ (metriche → loader corpora → adapter dei detector → runner →
  report), CLI sottile scripts/redteam.py, e un test pytest che gira dentro il job
  python-tests esistente (nessun nuovo workflow CI).
• Corpora originali, Apache-2.0, sigillati con SHA-256; il loader verifica gli hash al
  caricamento (e li dichiara in [tool.setuptools.package-data] così finiscono nel wheel).
• Nessuna nuova dipendenza runtime (stdlib + i detector già presenti in admina.domains).
• Metriche con denominatore zero → null (saltate dal gate, non trattate come regressioni);
  il motore Rust viene saltato se admina_core è assente (come in test_firewall_parity.py).

Note tecniche

• Il loop-breaker Python dipende da numpy/scikit-learn (extra [proxy], già esistente):
  l'adapter del loop fa degradare con grazia (motore Python segnato non disponibile) se non
  sono installati, invece di andare in errore.
• Il baseline Rust è misurato con admina_core 0.9.3 (wheel PyPI). Il gate salta il Rust
  se l'engine è assente; non gestisce un eventuale drift di versione del wheel — felice di
  vincolare la versione o rendere il confronto Rust "advisory" se preferite.

Fuori scope

Classificatore ML/semantico per injection; adapter per dataset esterni
(garak/PromptInject); chiusura del gap di parità del firewall Rust (questa suite ne è il
criterio d'accettazione); corpora più ampi e con più lingue.

Domande

• Nome del package: admina/redteam/ o admina/bench/efficacy/?
• Posizione dello scorecard: MODEL_CARD.md (attuale) o un docs/efficacy.md dedicato?
• Scope del commit: ho usato domains(redteam): (CONTRIBUTING non ha uno scope bench/test).

Checklist

• I test passano in locale (26 test della suite redteam); ruff e bandit puliti
• Header Apache-2.0 su tutti i nuovi file; commit con scope domains(redteam):
• Nessuna nuova dipendenza runtime; nessun nuovo workflow CI
• Solo misurazione: nessun detector è stato modificato
• Corpora originali (nessuna riga copiata da dataset di terze parti), sigillati con hash

[stefanoferi]

Reviewed across metrics, detector integration, gate/methodology, corpus integrity, and packaging. Ran the suite locally, recomputed the corpus hashes, and tested it against current main. Requesting changes on the items below before merge.

Verified

• No eval/exec/subprocess/network/pickle; corpora SHA-256-verified before load (digests recomputed, match).
• Metrics math correct: recall/precision/FPR/F1, zero-denominator → None, recall over positives / FPR over negatives; baseline reduces to exact integer TP counts.
• Measurement-only: git diff over admina/domains|core|proxy|sdk is empty.
• run_suite() runs against main's post-refactor detectors; injection 21/37, loop 9/11 match the baseline.
• No new runtime deps; package-data globs ship corpora in the wheel; tests cover tamper-detection, metric guards, bucketing, CLI e2e. RUST_CAVEAT emitted with every scorecard.

Blocking

1. Gate can pass vacuously if a Python detector stops running. tests/test_redteam_efficacy.py:42-43 if cur is None: continue is meant for the absent Rust engine but also skips a dropped Python engine (LoopAdapter.engines() omits python when the [proxy] extra is missing) → green build on the worst-case regression. Treat Python as mandatory and Rust optional; assert the run covered every Python entry the baseline declares.
2. PII recall is a type-level micro-average (metrics.py:47, runner.py:45-52) reported under the same "recall" key as the binary sample-level recall. Rename (type_recall) and document the averaging.
3. PII baseline is environment-dependent. The 100% Python recall was measured with spaCy; without en_core_web_sm the redactor falls back to regex-only and diverges, which can trip the gate as a false regression. Pin the PII env (regex-only vs nlp) in the baseline metadata.

Process

• Rebase onto main (~88 commits behind; no CI has run on this branch). main's MODEL_CARD §1 already states the engines are not behaviorally equivalent, so the equivalence mismatch resolves on rebase — verify §9 aligns with §1 and watch for a pyproject.toml overlap.

Non-blocking follow-ups (corpus size/denominators, label provenance, CLI entry point, fp-rate invariant, corpus edge cases) tracked in #37.

[lorenzofradeani]

Perfetto grazie mille, mi metto al lavoro.

[lorenzofradeani]

Sistemato tutto come richiesto.

[stefanoferi]

All three blocking items verified fixed (gate.py Python-mandatory + reverse coverage, type_recall, env-pinned baseline mode) — confirmed both statically and behaviorally: the gate fails actionably without the pinned spaCy model and reproduces the baseline with it. Full suite green locally (1113 passed) and on CI. Non-blocking follow-ups tracked in #37. Thanks for the quick turnaround.

[lorenzofradeani]

Thanks for the merge