Vai al contenuto principale
Quando la tua applicazione invia codice in un modello — per esaminarlo, completarlo o eseguirlo tramite un agent — vuoi il modello avvertito sulle parti rischiose e il workspace fermato dal far trapelare segreti nello stesso passaggio. Un guardrail di sicurezza del codice fa esattamente questo: esegue le tue regole di sicurezza del codice sulla richiesta prima che il modello upstream veda un singolo token. Questa è una landing focalizzata. Per il motore di guardrail completo — tipi di regola, stage, risoluzione, la sandbox di test — vedi il riferimento Guardrails e la panoramica dei guardrails.

​
1. Cosa fa davvero un guardrail di sicurezza del codice

OrcaRouter fornisce una famiglia di preset code_security che applichi dal selettore di template. Ognuno è un’ordinaria regola di guardrail — con scope a livello di workspace, ordinata, collegabile a qualsiasi chiave — messa a punto per il codice:

.env / Secret-File Block

Blocca assegnazioni di segreti in stile .env (DATABASE_URL=, AWS_SECRET_ACCESS_KEY=, API_TOKEN=…) e dump di configurazione multi-riga incollati prima che raggiungano il provider. Si basa sulla sintassi dell’assegnazione, non sul valore.

License Compliance (copyleft)

Segnala le richieste che portano header strong-copyleft — tag SPDX GPL / AGPL / LGPL / SSPL o nomi completi di licenza — così che un reviewer possa confermare che il codice è sicuro da mescolare in una codebase permissiva. Solo flag.

GPL/AGPL Provenance (output)

Flag nello stage di output sui suggerimenti del modello che portano firme di provenienza copyleft — un marcatore che il modello potrebbe aver rigurgitato dati di training copyleft nel codice generato.

Insecure-API Advisory

Annota il prompt con un avviso di sicurezza quando referenzia un sink ad alto rischio — eval( / exec( / os.system( / subprocess.run( / pickle.loads( / child_process.exec(. Non bloccante.
I primi tre riutilizzano azioni che già conosci — block e flag. L’Insecure-API Advisory usa annotate: invece di rifiutare o redigere la richiesta, la aumenta con una nota che il modello legge prima di rispondere. Lo stesso primitivo alimenta la decorazione CVE/SBOM (sotto).
I preset code_security sono deterministici — pura regex, nessuna chiamata di rete, sicuri sull’hot path. Gli scanner di rete (lookup CVE, SBOM, SAST) sono connessioni esterne separate, non preset. Vedi §3.

​
2. Annotate — avverti il modello senza cambiare il traffico

Le azioni che configuri su un guardrail sono block (rifiuta la chiamata, HTTP 400), mask (redige il match) e flag (solo log). La sicurezza del codice aggiunge un quarto comportamento sotto il cofano: annotate, che non blocca né maschera. Quando una regola annotate corrisponde, il gateway registra una breve nota e il relay la inietta upstream come avviso di sistema — così al modello viene detto, es., “this request references a high-risk API (code eval, shell execution, or unsafe deserialization); prefer safer alternatives” — prima che risponda. Il testo dell’utente non viene mai rifiutato né riscritto.

​
Un esempio concreto

Applica il preset Insecure-API Advisory a un guardrail e collegalo a una chiave. Poi invia codice che chiama un sink pericoloso: 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user",
       "content": "Refactor this: result = eval(user_supplied_expr)"}
    ]
  }'
La richiesta passa non modificata — stesso contenuto, stesso modello — ma il gateway antepone un avviso di sicurezza che il modello legge per primo. La completion torna sterzata verso API parametrizzate e validazione dell’input, senza modifiche al codice nella tua applicazione e senza un secondo round-trip.
Annotate si compone con le altre azioni. Un singolo guardrail può mascherare un segreto e annotare la stessa richiesta — il testo è redatto e una nota è aggiunta in un passaggio.

​
3. Decorazione CVE e SBOM tramite scanner esterni

Il primitivo dell’avviso si generalizza. Connetti uno scanner di sicurezza del codice come external vendor e i suoi findings cavalcano lo stesso percorso annotate:
Estrae import e pin di manifest dal testo della richiesta e li incrocia con il database pubblico di vulnerabilità OSV. Un hit decora il prompt con, es., “requests@2.0.0 has CVE-2014-1830 (HIGH). Fixed in 2.20.0.” — così al modello viene detto di una vulnerabilità nota in un package che gli è stato chiesto di usare. Gratuito e non autenticato, quindi non c’è campo per la chiave API. Per default annotate; puoi impostarlo a flag o block invece.
Connetti uno scanner SBOM (software bill-of-materials) o SAST (static-analysis) nello stesso modo in cui connetti qualsiasi external vendor — un URL base più credenziali, memorizzate cifrate e mascherate in lettura. Ogni finding porta un’identità stabile, così un finding che hai già triato non riscatta a ogni richiesta.
Gli scanner esterni seguono lo stesso default fail-open di ogni regola avanzata: un errore o timeout dello scanner viene registrato come telemetria e la richiesta continua. Imposta fail_open a false sulla regola per fare fail closed per policy in cui una scansione mancata è inaccettabile.

​
4. Abbinamento con regole di segreti e licenze

Un guardrail di sicurezza del codice raramente cavalca da solo. La forma comune è un guardrail con qualche regola:
ObiettivoRegola
Fermare credenziali incollate.env / Secret-File Block (block)
Catturare valori di segreti inlineSecrets Blocker (block)
Gestire codice copyleftLicense Compliance (flag)
Sterzare i sink pericolosiInsecure-API Advisory (annotate)
Aggiungile tutte a una policy nominata, collegala alla chiave del tuo coding-agent, e ogni richiesta viene filtrata — block sulle violazioni inequivocabili, annotate sulle decisioni di giudizio, flag il resto per la review.
Una richiesta bloccata restituisce HTTP 400 guardrail_blocked e non costa quota — un block nello stage di input scatta prima della misurazione. È anche marcata skip-retry, quindi rieseguire lo stesso prompt contro un altro canale si limita a bloccarlo di nuovo. Vedi l’ errore guardrail-blocked.

​
5. Configuralo (console + ruoli)

Tutto qui è configurato nella console, non tramite la chiave di relay. Le rotte di management (/api/guardrail/*) si autenticano con la tua sessione / access token, non con la chiave di relay sk-. Le letture — elencare i guardrails e il feed Matches — sono aperte a ogni membro del workspace. Le scritture (create / edit / delete) e la sandbox di test richiedono il ruolo Developer o superiore: la sandbox può scatenare chiamate a modelli a pagamento e richieste a vendor in uscita, quindi è gestita come una scrittura.
1

Crea il guardrail

Nella console, apri Guardrails → New guardrail. Lo split-button ti porta nella libreria di template — scegli un preset Code security come punto di partenza.
2

Modifica liberamente

Un preset è un seme, non un lucchetto. Metti a punto la regex, aggiungi una regola Secrets Blocker, cambia un’azione. Usa la tab Test per dimostrare che una regola scatta nel modo in cui ti aspetti contro testo di esempio prima di collegarla a una chiave.
3

Collega una chiave

Imposta il guardrail su una chiave API (guardrail_id), o marcalo come default del workspace. Il binding vive sulla chiave nel gateway, quindi modificare il guardrail sposta ogni chiave collegata alla chiamata successiva.
I findings atterrano nel feed Matches del workspace (tipo di regola, azione, stage, detail). La sottostringa corrispondente viene registrata solo quando Log raw content è attivo — disattivato per default, la postura conservativa sulla privacy. Vedi logging e privacy.

​
6. Dove andare dopo

  • Block secrets — la regola complementare che cattura i valori delle credenziali negli argomenti della richiesta.
  • Azioni — block, mask, flag, annotate e spotlight in profondità.
  • Compliance logger — mantieni un record immutabile di ogni finding di sicurezza del codice.
  • Testing ed eval — dimostra che la tua policy cattura codice noto-cattivo prima di metterlo in produzione.
  • Riferimento Guardrails — il motore completo.
  • Proteggere gli agent AI — dove i rail di sicurezza del codice si collocano nel control stack zero-trust.