Saltar para o conteúdo principal
Quando sua aplicação envia código para um modelo — para revisá-lo, completá-lo ou rodá-lo através de um agente — você quer o modelo avisado sobre as partes arriscadas e o workspace impedido de vazar segredos na mesma passada. Um code security guardrail faz exatamente isso: ele roda suas regras de segurança de código sobre a requisição antes de o modelo upstream ver um único token. Esta é uma página de destino focada. Para o motor de guardrail completo — tipos de regra, estágios, resolução, o sandbox de teste — veja a referência de Guardrails e a visão geral dos guardrails.

​
1. O que um code security guardrail realmente faz

O OrcaRouter traz uma família de presets code_security que você aplica a partir do seletor de templates. Cada um é uma regra de guardrail comum — com escopo de workspace, ordenada, vinculável a qualquer chave — afinada para código:

.env / Secret-File Block

Bloqueia atribuições de segredo no estilo .env (DATABASE_URL=, AWS_SECRET_ACCESS_KEY=, API_TOKEN=…) e dumps de config multilinha colados antes de chegarem ao provedor. Baseia-se na sintaxe da atribuição, não no valor.

License Compliance (copyleft)

Sinaliza requisições que carregam cabeçalhos de strong-copyleft — tags SPDX GPL / AGPL / LGPL / SSPL ou nomes completos de licença — para que um revisor confirme que o código é seguro para misturar em uma base de código permissiva. Somente flag.

GPL/AGPL Provenance (output)

Flag no estágio de output em sugestões do modelo que carregam assinaturas de proveniência copyleft — um marcador de que o modelo pode ter regurgitado dados de treino copyleft em código gerado.

Insecure-API Advisory

Anota o prompt com um aviso de segurança quando ele referencia um sink de alto risco — eval( / exec( / os.system( / subprocess.run( / pickle.loads( / child_process.exec(. Não bloqueante.
Os três primeiros reutilizam ações que você já conhece — block e flag. O Insecure-API Advisory usa annotate: em vez de rejeitar ou redigir a requisição, ele a aumenta com uma nota que o modelo lê antes de responder. A mesma primitiva alimenta a decoração de CVE/SBOM (abaixo).
Os presets code_security são determinísticos — regex puro, sem chamada de rede, seguro no caminho quente. Os scanners em rede (lookup de CVE, SBOM, SAST) são conexões externas separadas, não presets. Veja §3.

​
2. Annotate — avise o modelo sem mudar o tráfego

As ações que você configura em um guardrail são block (rejeita a chamada, HTTP 400), mask (redige a correspondência) e flag (apenas registra). A segurança de código adiciona um quarto comportamento por baixo dos panos: annotate, que nem bloqueia nem mascara. Quando uma regra annotate corresponde, o gateway registra uma nota curta e o relay a injeta upstream como um aviso de sistema — de modo que o modelo é avisado, ex.: “this request references a high-risk API (code eval, shell execution, or unsafe deserialization); prefer safer alternatives” — antes de responder. O texto do usuário nunca é rejeitado e nunca reescrito.

​
Um exemplo concreto

Aplique o preset Insecure-API Advisory a um guardrail e vincule-o a uma chave. Depois envie código que chama um sink perigoso: 
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)"}
    ]
  }'
A requisição passa sem modificação — mesmo conteúdo, mesmo modelo — mas o gateway prepende um aviso de segurança que o modelo lê primeiro. O completion volta direcionado para APIs parametrizadas e validação de input, sem mudança de código na sua aplicação e sem um segundo round-trip.
Annotate se compõe com as outras ações. Um único guardrail pode mascarar um segredo e anotar a mesma requisição — o texto é redigido e uma nota é adicionada em uma passada.

​
3. Decoração de CVE e SBOM via scanners externos

A primitiva de aviso se generaliza. Conecte um scanner de segurança de código como um fornecedor externo e suas descobertas pegam o mesmo caminho de annotate:
Extrai imports e pins de manifesto do texto da requisição e os cruza-referencia contra o banco de dados público de vulnerabilidades OSV. Um hit decora o prompt com, ex.: “requests@2.0.0 has CVE-2014-1830 (HIGH). Fixed in 2.20.0.” — de modo que o modelo é avisado sobre uma vulnerabilidade conhecida em um pacote que foi pedido para usar. Gratuito e não autenticado, então não há campo de chave de API. O padrão é annotate; você pode defini-lo como flag ou block em vez disso.
Conecte um scanner SBOM (software bill-of-materials) ou SAST (análise-estática) da mesma forma que você conecta qualquer fornecedor externo — uma URL base mais credenciais, armazenadas criptografadas e mascaradas na leitura. Cada descoberta carrega uma identidade estável, então uma descoberta que você já triou não dispara de novo em cada requisição.
Scanners externos seguem o mesmo padrão fail-open de toda regra avançada: um erro ou timeout de scanner é registrado como telemetria e a requisição continua. Defina fail_open como false na regra para falhar fechado em políticas onde um scan perdido é inaceitável.

​
4. Combinando com regras de segredos e licença

Um code-security guardrail raramente anda sozinho. A forma comum é um guardrail com algumas regras:
ObjetivoRegra
Deter credenciais coladas.env / Secret-File Block (block)
Pegar valores de segredo inlineSecrets Blocker (block)
Gatear código copyleftLicense Compliance (flag)
Direcionar sinks perigososInsecure-API Advisory (annotate)
Adicione todas a uma política nomeada, vincule-a à chave do seu agente de código, e cada requisição é filtrada — block nas violações inequívocas, annotate nas decisões de julgamento, flag no resto para revisão.
Uma requisição bloqueada retorna HTTP 400 guardrail_blocked e não custa cota — um block no estágio de input dispara antes da medição. Ela também é marcada como skip-retry, então reexecutar o mesmo prompt contra outro canal apenas bloqueia de novo. Veja o erro guardrail-blocked.

​
5. Configure (console + papéis)

Tudo aqui é configurado no console, não via a chave de relay. As rotas de gerenciamento (/api/guardrail/*) autenticam com sua sessão / access token, não com a chave de relay sk-. Leituras — listar guardrails e o feed Matches — estão abertas a cada membro do workspace. Escritas (criar / editar / deletar) e o sandbox de teste exigem o papel Developer ou acima: o sandbox pode disparar chamadas pagas de modelo e requisições outbound a fornecedores, então é gateado como uma escrita.
1

Crie o guardrail

No console, abra Guardrails → New guardrail. O split-button te leva à biblioteca de templates — escolha um preset Code security como seu ponto de partida.
2

Edite livremente

Um preset é uma semente, não uma trava. Ajuste o regex, adicione uma regra Secrets Blocker, mude uma ação. Use a aba Test para provar que uma regra dispara da forma que você espera contra texto de amostra antes de vinculá-la a uma chave.
3

Vincule uma chave

Defina o guardrail em uma chave de API (guardrail_id), ou marque-o como o padrão do workspace. O vínculo vive na chave dentro do gateway, então editar o guardrail desloca cada chave vinculada na próxima chamada.
Descobertas caem no feed Matches do workspace (tipo de regra, ação, estágio, detalhe). A substring correspondente é registrada apenas quando Log raw content está ligado — desligado por padrão, a postura conservadora de privacidade. Veja logging e privacidade.

​
6. Para onde ir a seguir