Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Architettura di Sicurezza Completa

Lezione 12 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Assemblaggio di tutti i pezzi
  2. Panoramica dell’architettura
  3. Implementazione Completa
  4. Utilizzo in Produzione
  5. Monitoraggio e Avvisi
  6. Riepilogo del Corso
  7. Punti chiave
  8. Metti alla prova le tue conoscenze

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 ufficiale moderation_llm_v2 e le undici chiavi di mistral-moderation-2603. I punteggi, opzionali nell’SDK, vengono letti con un valore di fallback. Codice verificato rispetto ai tipi dell’SDK mistralai versione 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.