Architettura di Sicurezza Completa
In questa pagina
Aggiornato il 3 novembre 2026. Il livello di generazione utilizzava in precedenza un formato di guardrail inventato (
enabled) e la policy di produzione impiegava categorie inesistenti (hate,violence,unpredictable). Il codice ora segue il formato ufficialemoderation_llm_v2e le undici chiavi dimistral-moderation-2603. I punteggi, opzionali nell’SDK, vengono letti con un valore di fallback. Codice verificato rispetto ai tipi dell’SDKmistralaiversione 3.7.0. Fonti: Moderation & Guardrailing · Python SDK mistralai.
Assemblaggio di tutti i pezzi
Durante questo corso, hai esplorato i guardrail, le API di Moderation, le 11 categorie, le soglie, il rilevamento dei jailbreak, la conformità al GDPR e le policy sui contenuti. Questa lezione finale assembla tutti questi mattoni in un’architettura di sicurezza completa, pronta per la produzione.
Panoramica dell’architettura
Esistono cinque livelli, guidati da un principio: nessuno di essi è affidabile da solo. Un guardrail può essere aggirato da una formulazione inaspettata, un modello di moderation produce falsi negativi e una policy sui contenuti non copre mai ogni caso. L’impilamento funziona perché le lacune non si sovrappongono: ciò che sfugge al primo livello ha buone probabilità di essere catturato dal secondo.
La conseguenza pratica è un ordine rigoroso: ogni livello deve essere il più economico possibile prima che venga eseguito il successivo. Validi il formato prima di chiamare un guardrail e chiami il guardrail prima di generare, perché i contenuti rifiutati al passaggio 1 consumano zero token.
Utente
↓
[1. Validazione Input] → Regex, pattern, rate limiting
↓
[2. Mistral Guardrails] → Blocco pre-generazione (403)
↓
[3. Generazione LLM] → safe_prompt + istruzioni sicure
↓
[4. Moderation Output] → API Moderation post-generazione
↓
[5. Logging & Audit] → Punteggi, decisioni, traccia audit GDPR
↓
Risposta Utente
Implementazione Completa
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import os
import re
import json
import logging
from datetime import datetime, timezone
from enum import Enum
# Configurazione
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("moderation")
class Decision(Enum):
ALLOWED = "allowed"
BLOCKED_INPUT = "blocked_input"
BLOCKED_GUARDRAIL = "blocked_guardrail"
BLOCKED_OUTPUT = "blocked_output"
ERROR = "error"
class SecureArchitecture:
"""Architettura di sicurezza completa per applicazioni AI."""
def __init__(self, policy: dict, model: str = "mistral-large-latest"):
self.policy = policy
self.model = model
self.stats = {d.value: 0 for d in Decision}
# --- Livello 1: Validazione Input ---
def validate_input(self, text: str) -> dict:
"""Validazione rapida prima di qualsiasi chiamata API."""
# Lunghezza massima
if len(text) > 10000:
return {"valid": False, "reason": "Messaggio troppo lungo"}
# Caratteri sospetti (injection Unicode)
if re.search(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", text):
return {"valid": False, "reason": "Caratteri non validi"}
# Pattern di jailbreak evidenti
patterns = [
r"ignore\s+(all\s+)?(previous|prior|above)",
r"you\s+are\s+now\s+(DAN|unfiltered)",
r"oublie\s+(toutes?\s+)?(tes|vos)\s+instructions",
r"system\s*prompt",
]
for pattern in patterns:
if re.search(pattern, text, re.IGNORECASE):
return {
"valid": False,
"reason": "Pattern di injection rilevato"
}
return {"valid": True}
# --- Livello 2: Moderation Input ---
def moderate_input(self, text: str) -> dict:
"""Moderation del prompt tramite API."""
response = client.classifiers.moderate(
model="mistral-moderation-2603",
inputs=[text]
)
scores = response.results[0].category_scores or {}
violations = self._check_thresholds(scores)
return {
"allowed": len(violations) == 0,
"scores": scores,
"violations": violations
}
# --- Livello 3: Generazione Sicura ---
def generate(self, messages: list) -> str:
"""Generazione con guardrail e safe_prompt."""
response = client.chat.complete(
model=self.model,
messages=messages,
safe_prompt=True,
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": self.policy["thresholds"],
"action": "block",
},
}
],
)
content = response.choices[0].message.content
return content if isinstance(content, str) else ""
# --- Livello 4: Moderation Output ---
def moderate_output(self, prompt: str, response_text: str) -> dict:
"""Moderation della risposta nel contesto."""
response = client.classifiers.moderate_chat(
model="mistral-moderation-2603",
inputs=[[
{"role": "user", "content": prompt},
{"role": "assistant", "content": response_text}
]]
)
scores = response.results[0].category_scores or {}
violations = self._check_thresholds(scores)
return {
"allowed": len(violations) == 0,
"scores": scores,
"violations": violations
}
# --- Livello 5: Logging ---
def log_decision(self, decision: Decision, data: dict):
"""Registra la decisione per l'audit."""
self.stats[decision.value] += 1
entry = {
"timestamp": datetime.now(timezone.utc).isoformat(),
"decision": decision.value,
"policy": self.policy["name"],
**data
}
logger.info(json.dumps(entry, ensure_ascii=False))
# --- Pipeline Principale ---
def process(self, user_message: str,
system_prompt: str | None = None) -> dict:
"""Pipeline di elaborazione sicura completa."""
# Livello 1: Validazione
validation = self.validate_input(user_message)
if not validation["valid"]:
self.log_decision(Decision.BLOCKED_INPUT, {
"reason": validation["reason"]
})
return {
"status": Decision.BLOCKED_INPUT.value,
"message": "Il tuo messaggio non può essere elaborato."
}
# Livello 2: Moderation Input
check_input = self.moderate_input(user_message)
if not check_input["allowed"]:
self.log_decision(Decision.BLOCKED_INPUT, {
"violations": check_input["violations"]
})
return {
"status": Decision.BLOCKED_INPUT.value,
"message": "Questo contenuto viola la nostra policy."
}
# Livello 3: Generazione
messages = []
if system_prompt:
messages.append({"role": "system",
"content": system_prompt})
messages.append({"role": "user",
"content": user_message})
try:
response_text = self.generate(messages)
except SDKError as e:
if e.status_code == 403:
self.log_decision(Decision.BLOCKED_GUARDRAIL, {})
return {
"status": Decision.BLOCKED_GUARDRAIL.value,
"message": "Richiesta bloccata dai guardrail."
}
raise
# Livello 4: Moderation Output
check_output = self.moderate_output(user_message, response_text)
if not check_output["allowed"]:
self.log_decision(Decision.BLOCKED_OUTPUT, {
"violations": check_output["violations"]
})
return {
"status": Decision.BLOCKED_OUTPUT.value,
"message": "La risposta è stata filtrata."
}
# Successo
self.log_decision(Decision.ALLOWED, {
"input_max_score": max(check_input["scores"].values(), default=0.0),
"output_max_score": max(check_output["scores"].values(), default=0.0),
})
return {
"status": Decision.ALLOWED.value,
"content": response_text,
"moderation": {
"input": check_input["scores"],
"output": check_output["scores"]
}
}
# --- Utilità ---
def _check_thresholds(self, scores: dict) -> list:
"""Controlla i punteggi rispetto alle soglie della policy."""
violations = []
for cat, threshold in self.policy["thresholds"].items():
score = scores.get(cat, 0)
if score > threshold:
violations.append({
"category": cat,
"score": round(score, 3),
"threshold": threshold
})
return violations
def report(self) -> dict:
"""Genera un report statistico."""
total = sum(self.stats.values())
return {
"policy": self.policy["name"],
"total_requests": total,
"decisions": self.stats,
"block_rate": round(
(self.stats["blocked_input"] +
self.stats["blocked_guardrail"] +
self.stats["blocked_output"]) / max(total, 1),
3
)
}
Utilizzo in Produzione
# Definisci la policy
prod_policy = {
"name": "Production v1.2",
"thresholds": {
"sexual": 0.15, "hate_and_discrimination": 0.1, "violence_and_threats": 0.2,
"dangerous": 0.1, "criminal": 0.1, "selfharm": 0.1, "health": 0.4,
"financial": 0.4, "law": 0.4, "pii": 0.15,
"jailbreaking": 0.1
}
}
# Istanzia l'architettura
arch = SecureArchitecture(prod_policy)
# Elabora le richieste
result = arch.process(
"Spiega come funzionano i transformer",
system_prompt="Sei un istruttore AI."
)
print(result["status"]) # atteso: "allowed"
print(result["content"])
# Consulta le statistiche
print(arch.report())
Monitoraggio e Avvisi
Due metriche sono sufficienti per guidare un sistema di moderation e devi osservarle in direzioni opposte. Il tasso di blocco deve rimanere stabile: un picco improvviso segnala o un attacco o una soglia troppo rigida che inizia a ostacolare gli utenti legittimi. Anche la distribuzione dei punteggi conta altrettanto: se i tuoi contenuti si raggruppano appena sotto la soglia, la soglia è mal posizionata e la prossima modifica da parte dei tuoi utenti la infrangerà.
def configure_alerts(arch: SecureArchitecture):
"""Configura gli avvisi per il monitoraggio."""
report = arch.report()
# Avviso se il tasso di blocco è anomalo
if report["block_rate"] > 0.15:
logger.warning(
f"Tasso di blocco elevato: "
f"{report['block_rate']:.1%}"
)
# Avviso se si verificano picchi di jailbreak
# Integra con Prometheus, Grafana, Datadog, ecc.
Riepilogo del Corso
Alla fine di questo corso, hai padroneggiato:
- Guardrail Personalizzati: Blocca i prompt pericolosi prima della generazione, configura le soglie per categoria, applica agli agent
- API Moderation: Classifica i contenuti con Mistral Moderation 2, interpreta i punteggi nelle 11 categorie, prendi decisioni automatizzate
- Sicurezza in Produzione: Definisci policy sui contenuti, rileva le injection di prompt, garantisci la conformità al GDPR
- Architettura Completa: Assembla guardrail + moderation + monitoraggio in una pipeline robusta
Ora hai tutto il codice necessario per distribuire un sistema completo di moderation AI con le API Mistral.
Punti chiave
- L’architettura di sicurezza include 5 livelli: validazione, guardrail, generazione, moderation, logging
- Ogni livello compensa le debolezze degli altri: questa è la difesa in profondità
- Monitora il tasso di blocco e i punteggi in produzione
- Mantieni la tua policy aggiornata con revisioni regolari
- Il codice completo in questa lezione è un punto di partenza: adattalo al tuo contesto
Metti alla prova le tue conoscenze
Guardrail, moderation, injection: l’architettura difensiva è chiara?
1. Dove intervengono i guardrail personalizzati?
Risposta: Prima del modello: filtrano gli input secondo le tue regole (argomenti vietati, formati) — il primo livello, che evita persino di effettuare la chiamata quando la richiesta è fuori scope.
2. Cosa copre l'API Mistral Moderation?
Risposta: Undici categorie di contenuti rischiosi, con un punteggio per categoria: le tue soglie decidono se bloccare, segnalare o consentire, trasformando la policy sui contenuti in codice.
3. Come si definisce una buona policy sui contenuti?
Risposta: Per caso d’uso: cosa è accettabile per l’applicazione, soglie per categoria, azioni associate (blocco, riscrittura, escalation) — documentate e testate, non implicite.
4. Come rilevi i tentativi di prompt injection?
Risposta: Trattando tutti i contenuti esterni come sospetti: rilevando pattern di istruzioni nei dati, isolando le istruzioni dai dati, validando gli output ed eseguendo test offensivi regolari.
5. Com'è fatta l'architettura di sicurezza completa?
Risposta: Livelli: guardrail input, moderation contenuti, controlli output, conformità GDPR (minimizzazione, diritti) e tracciabilità — nessun singolo livello è perfetto, ma impilarli compensa le carenze.
La difesa in profondità non è uno slogan: ogni livello in questo corso cattura ciò che il precedente ha lasciato passare.