Glossario di sicurezza per agent AI
Un indice di riferimento rapido di ogni termine usato nella documentazione Zero Trust. Ogni definizione è circoscritta a ciò che tu, come sviluppatore sul gateway ospitato, puoi osservare e configurare. I termini rimandano alle loro pagine principali per i dettagli completi.Identità e scope
| Termine | Definizione |
|---|---|
| Workspace | Il confine del tenant al livello più alto. Tutte le chiavi, i guardrail, le policy del firewall e gli eventi di audit appartengono a un workspace; nulla attraversa i confini del tenant. Vedi Scope, chiavi e policy. |
| Chiave API (chiave con scope) | Un bearer token che il tuo agent presenta su ogni chiamata. Porta la propria allowlist di modelli, restrizioni IP, tetto di spesa, scadenza, e l’esatto guardrail + policy del firewall che si applica ad essa. Vedi Scope, chiavi e policy. |
model_limits | Il set di modelli (o glob di modelli) che una chiave è autorizzata a chiamare. Le richieste per un modello fuori dalla lista vengono rifiutate prima di qualsiasi chiamata upstream. |
allow_ips | Una allowlist di IP o CIDR sulla chiave. Le richieste provenienti da un indirizzo fuori dalla lista vengono rifiutate all’autenticazione. |
credit_limit_usd (tetto di spesa) | Un tetto di spesa fisso sulla chiave, in USD. Una volta che l’utilizzo accumulato della chiave raggiunge il tetto, le ulteriori richieste vengono rifiutate. Utile per limitare i loop incontrollati degli agent. |
| Tag di ambiente | Un’etichetta free-form (es. production, staging) collegata a una chiave per organizzarla e identificarla per ambiente di deployment. |
is_firewall_gateway | Un flag che dà scope a una chiave per le rotte del gateway Firewall (/api/v1/firewall/*) — gli endpoint di dispatch MCP e evaluate hook. Una chiave normale riceve 403 su quelle rotte. |
| Minima agenzia | Il principio di dare a un agent solo i modelli, la spesa, gli IP e le policy di cui ha effettivamente bisogno — non di più. Implementato combinando model_limits, allow_ips, credit_limit_usd e una policy del firewall restrittiva sulla stessa chiave. Vedi Scope, chiavi e policy. |
Guardrails
| Termine | Definizione |
|---|---|
| Guardrail | Una content policy nominata, con scope a livello di workspace — un elenco ordinato di regole che il gateway esegue sull’input della richiesta e sull’output del modello. Collegalo a una chiave (o impostalo come default del workspace) una volta; ogni chiamata collegata viene filtrata senza redeploy. |
| Regola | Un controllo all’interno di un guardrail: un tipo (cosa rilevare), uno stage (dove cercare) e un’azione (cosa fare). Le regole girano nell’ordine. |
| Stage | input (la richiesta del chiamante), output (la risposta del modello), o both. Una regola scatta solo al suo stage dichiarato. |
| Azione | block — rifiuta l’intera richiesta (HTTP 400); mask — redige il match e lascia passare la chiamata; flag — solo log, nessuna modifica al traffico. |
guardrail_blocked | Il codice di errore restituito quando una regola del guardrail scatta un’azione block. Restituisce HTTP 400. La richiesta non costa quota — i block di stage input scattano prima della misurazione; i block di stage output rimborsano la quota pre-consumata. |
| PII Shield | Una regola di tipo pii che rileva i tipi di entità sensibili integrati (email, telefono, SSN, carta di credito, IP e altri) e li maschera con tag tipizzati. (Il tipo di regola pii supporta anche block per entità quando scrivi la tua.) Il punto di partenza canonico per la prevenzione della perdita di dati. Segreti e credenziali sono coperti dal preset separato Secrets Blocker. |
| Guardrail anti-prompt-injection | Una regola di sicurezza che rileva i tentativi da parte di contenuti non attendibili (pagine web, risultati di tool) di dirottare le istruzioni dell’agent. Viene fornita come preset Prompt-Injection Basics nella categoria template Safety. |
| Filtro parole sensibili | Una regola di tipo keyword che corrisponde a un elenco di termini letterali, senza distinzione tra maiuscole e minuscole. La denylist più semplice. |
| LLM judge | Una regola di tipo llm_judge che esegue un controllo semantico (tossicità, fuori tema, intento di jailbreak) contro un modello nel tuo workspace. Usala per policy sfumate che nessuna regex può catturare. I token sono fatturati come sub-riga del judge. |
| Contextual grounding | Una regola di tipo grounding che punteggia la risposta del modello rispetto alle sorgenti RAG sulla richiesta e segnala o blocca risposte che non vi sono fedeli. |
| Log raw content | Un toggle per guardrail — disattivato di default (conservativo sulla privacy). Quando disattivato, il feed Matches registra che una regola è scattata ma non la sottostringa corrispondente. Attiva per guardrail quando hai bisogno della stringa effettiva per il triage. |
| Feed Matches | Il record a livello di workspace di ogni regola che ha scattato: tipo di regola, azione, stage, stringa di dettaglio e (quando Log raw content è attivo) la sottostringa corrispondente. Filtrabile per guardrail, tipo di regola e azione. |
Agent Firewall
| Termine | Definizione |
|---|---|
| Policy del firewall | Un set ordinato di regole nominato, con scope a livello di workspace, che il gateway valuta su ogni chiamata a tool. Collegalo una volta a una chiave o impostalo come default del workspace; nessuna modifica al codice dell’agent richiesta. |
| Verdetto | Il risultato che una regola (o il default) produce per una chiamata a tool. Uno tra allow, audit, deny, sanitize, pending_approval o cap_cost. |
| Verdetto di default | Il verdetto applicato quando nessuna regola nella policy corrisponde alla chiamata a tool. Ha come default audit — consenti tutto e registralo — finché non sei pronto ad applicare. |
| Superficie di applicazione | Il punto nel ciclo di vita della richiesta in cui il firewall vede una chiamata: inbound (definizioni dei tool che l’agent pubblicizza), response (chiamate a tool che il modello emette), mcp (un tools/call attraverso il gateway MCP), o egress (una destinazione in uscita segnalata da un tool). Vedi Firewall. |
| Allowlist dei tool (glob) | Un tool_name_glob su una regola — una grammatica case-sensitive compatta (shell.*, *.exec, *) che corrisponde a un nome di tool o a una famiglia. First-match-wins rispetto all’elenco ordinato di regole. |
| Validazione degli argomenti | Clausole args_match su una regola — operatori eq, contains, regex, in, cidr_match, gt, lt su campi JSONPath negli argomenti del tool. La differenza tra “blocca shell.exec” e “blocca shell.exec solo quando il comando è rm -rf.” |
| Sanitize | Un verdetto sanitize che redige le sottostringhe corrispondenti (segreti, PII) dagli argomenti del tool e inoltra la chiamata ripulita, invece di bloccare l’intera azione. Escala a un block sulla superficie inbound. |
| Controllo egress | Una regola di superficie egress con una allowlist o denylist di host/CIDR — la difesa primaria contro SSRF e esfiltrazione di dati. Il livello di autonomia tight nega anche i tool di tipo fetch (http_fetch, fetch_url, web_search, request). |
cap_cost | Un verdetto che nega le chiamate a tool una volta che la spesa accumulata dell’esecuzione dell’agent (in centesimi) supera un tetto per regola. Un circuit-breaker per i loop incontrollati degli agent; scritto come regola e risolto in allow o deny negli eventi in base alla spesa accumulata. |
| Regola di sequenza | Una regola con un blocco sequence che corrisponde a una catena multi-step ordinata di chiamate a tool all’interno di una finestra temporale (es. bulk-read → export → egress). Applicata reattivamente da un matcher asincrono; emerge nel feed degli eventi. |
firewall_blocked | Il codice di errore su una chiamata a tool negata. Restituisce HTTP 400 su inbound; un errore di tool su mcp. Marcato skip-retry. |
Approvazione / HITL (pending_approval) | Un verdetto pending_approval trattiene una chiamata a tool per la revisione umana. L’agent riceve una risposta held con un id di approvazione, un revisore approva o rifiuta fuori banda, e l’agent ri-invia con un token di approvazione monouso. Il codice di errore HTTP mentre è trattenuto è firewall_approval_pending. |
| Rilevamento delle anomalie | Layer statistico sopra le regole statiche. Punteggia l’attività per-tool rispetto a una baseline ora-della-settimana a 14 giorni e segnala picchi, loop di retry e percorsi di transizione tool-to-tool nuovi su un feed esaminabile. |
Posture
| Termine | Definizione |
|---|---|
| Observe mode | Un’impostazione a livello di workspace. Quando attivo e nessuna policy è collegata a una chiave, le chiamate a tool sono consentite ma loggata come gap di copertura, popolando la vista Discovered tools. |
| Shadow mode | Un flag su una policy. La policy valuta e logga esattamente come farebbe in produzione, ma ogni verdetto applicativo viene declassato a audit (motivazione prefissata con [shadow] would …). Switch per il rollout sicuro. |
| Enforce | Lo stato predefinito quando la shadow mode è disattiva e una policy è collegata. I verdetti hanno effetto — deny blocca, sanitize redige, pending_approval trattiene. |
| Livello di autonomia | Un singolo switch (tight / balanced / permissive) che sostituisce atomicamente la postura del Firewall e dei Guardrails del workspace in una transazione con undo a un clic. Vedi Modalità di applicazione e Baseline Secure Agents. |
MCP e skill
| Termine | Definizione |
|---|---|
| MCP server | Un server Model Context Protocol registrato nel tuo workspace ed esposto attraverso il gateway MCP del Firewall (api.orcarouter.ai/api/v1/firewall/mcp). Ogni tools/call che riceve viene valutato inline. Vedi Firewall MCP. |
tools/call | Il messaggio del protocollo MCP che dispatcha un tool verso un MCP server. Il firewall lo valuta sulla superficie mcp prima di inoltrarlo. |
| Rug-pull | Un rischio della supply chain dove un MCP server o una capability installata cambia o espande le definizioni dei tool dopo che gli hai concesso l’accesso. OrcaRouter governa il raggio di esplosione: ogni tools/call MCP viene valutato dal firewall sulla superficie mcp rispetto alle tue regole, e una skill che viene scansionata come rischiosa viene trattenuta in quarantine finché un essere umano non la esamina. |
| Skill | Un pacchetto di capability (uno o più tool da uno o più MCP server) che il gateway scansiona per il rischio alla registrazione. Ogni skill riceve una banda di rischio e una modalità di applicazione (allow, quarantine, block) che si sovrappone ai verdetti a livello di policy. |
Compliance e dati
| Termine | Definizione |
|---|---|
| Compliance pack | Un pacchetto di guardrail + policy del firewall pre-costruito per un profilo normativo (GDPR, PCI, HIPAA, dati finanziari). Applicalo una volta dalla libreria di template; le regole sono modificabili dopo l’applicazione. |
| Report di compliance firmato | Un report di attestazione a livello di workspace firmato con Ed25519. La firma è pubblicamente verificabile — chiunque abbia la chiave pubblica può confermare che il report non è stato manomesso. |
| Residenza dei dati | La regione registrata per la tua evidenza di compliance. I report di compliance firmati vengono timbrati e memorizzati per regione (us, eu, uk, ap, cn, global), e un report viene servito solo sotto una regione dichiarata corrispondente. Impostala nelle impostazioni di compliance. |
| Diritto alla cancellazione | Su una cancellazione del workspace o una richiesta esplicita di cancellazione, OrcaRouter concede un periodo di grazia di 30 giorni, poi scruba le PII dai log e dai record di audit per quel workspace. |
| Evento di audit | Un record immutabile scritto dopo ogni create, update, delete e decisione di applicazione — modifiche alle policy, modifiche alle regole, risoluzioni di approvazione, salvataggi di guardrail. I valori dei segreti e i blob delle regole non vengono mai scritti nel log di audit. |
Minacce (definizioni in una riga)
| Minaccia | Di cosa si tratta |
|---|---|
| Prompt injection | Un attaccante incorpora istruzioni nel contenuto che l’agent ingerisce (diretta: nel messaggio dell’utente; indiretta: in una pagina web, documento o risultato di un tool) per dirottare il comportamento dell’agent. |
| Jailbreak | Un prompt costruito ad arte che tenta di aggirare il training di sicurezza di un modello, tipicamente inquadrando la richiesta come un gioco di ruolo, ipotetico o un override di sistema. |
| Eccessiva agenzia / confused deputy | Un agent a cui sono stati concessi permessi più ampi di quelli richiesti dal suo compito, rendendolo banalmente sfruttabile da istruzioni iniettate — la mitigazione chiave è la minima agenzia. |
| Esfiltrazione di dati | Un agent (o un’istruzione iniettata) che dirige le chiamate a tool o le richieste in uscita per far trapelare dati sensibili verso un endpoint controllato dall’attaccante. Mitigata dalle regole di controllo egress. |
| Denial-of-wallet | Un agent incontrollato o attivato in modo avversariale che genera spesa di modello upstream illimitata. Mitigato da credit_limit_usd sulla chiave e dalle regole cap_cost nella policy del firewall. |
Per il quadro completo di come questi controlli si compongono, vedi Proteggere gli agent AI con OrcaRouter.