BroadRouter
Começar

Segurança de chaves de API de LLM: armazenamento, rotação e IPs

Pela equipe da BroadNet Inference · 6 min de leitura · Publicado em · Atualizado em

Guarde chaves de API de LLM num gerenciador de segredos, nunca no código nem no navegador. Dê a cada app ou agente sua própria chave, faça rotação periódica e prenda as chaves aos seus servidores com uma lista de IPs permitidos. A BroadNet Inference diz que suas listas aceitam 32 entradas, que a revogação bloqueia novas requisições em até cinco segundos e que as chaves duram um ano.

Para proteger uma chave de API de LLM, guarde-a num gerenciador de segredos e chame o modelo só a partir do seu servidor, nunca de um navegador ou app. Dê a cada carga de trabalho sua própria chave, faça rotação das chaves periodicamente, prenda-as aos IPs dos seus servidores com uma lista de IPs permitidos e, se uma chave vazar, revogue primeiro e investigue depois.

Este post cobre os hábitos que mantêm as chaves seguras, com os controles específicos que a BroadNet Inference oferece. Para o passo a passo no portal, veja o guia de chaves de API e listas de IPs permitidos; para orçamentos e proteção contra loops descontrolados, veja controle de gastos com APIs de LLM.

Onde guardar uma chave de API de LLM?

Guarde as chaves num gerenciador de segredos ou nos segredos criptografados da sua plataforma, nunca no código. O OWASP Secrets Management Cheat Sheet cobre as opções em detalhe. Repare no alerta dele: variáveis de ambiente “are generally accessible to all processes and may be included in logs or system dumps” (tradução: em geral ficam acessíveis a todos os processos e podem acabar em logs ou dumps do sistema), por isso a OWASP prefere, quando você pode escolher, arquivos de segredo montados ou buscar os segredos num cofre. Uma variável de ambiente preenchida por um gerenciador de segredos na inicialização é o meio-termo mais comum.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],  # fails loudly if missing
)

Use os.environ[...], não os.getenv(...) com um valor padrão fixo no código; é justamente assim que chaves vão parar no Git. No desenvolvimento local, um arquivo .env serve, desde que esteja no .gitignore desde o primeiro commit. Ative o secret scanning e a push protection do seu host Git. No GitHub, a push protection bloqueia pushes que contêm formatos de segredo conhecidos antes que cheguem ao repositório; a push protection para usuários vem ativada por padrão, mas a do nível do repositório vem desativada por padrão e precisa ser ativada por um administrador do repositório ou por um owner da organização.

Dá para colocar uma chave de API num navegador ou app mobile?

Não. Tudo o que vai para um cliente pode ser extraído. Código de front-end e bundles de app são públicos, por mais minificados ou ofuscados que estejam. Chame o LLM do seu servidor, autentique seus próprios usuários ali e aplique seus próprios limites por usuário antes de repassar a requisição.

O mesmo vale para ferramentas desktop que você entrega a outras pessoas. Se um colega precisa de acesso a um agente de código, dê a ele uma chave própria na conta dele, em vez de compartilhar uma.

Por que dar a cada carga de trabalho sua própria chave?

Na BroadNet Inference, uma conta pode ter até dez chaves ativas. Use-as:

Rótulo da chave Usada por
prod-api Backend de produção
prod-worker Jobs em lote
staging Ambiente de staging
agent-ci Agente de código na CI
dev-laptop-<name> Desenvolvimento local

Quando uma vaza, você revoga só aquela, e as outras continuam funcionando. Os rótulos também deixam o uso legível: dá para ver qual carga de trabalho gasta quanto. Dê às chaves o nome do que as usa, não de quem as criou.

Como as listas de IPs permitidos protegem uma chave?

Com uma lista de IPs permitidos, uma chave roubada não funciona em lugar nenhum fora da sua infraestrutura. Na BroadNet Inference:

  • A lista da conta aceita até 32 entradas, um endereço IPv4 ou IPv6 ou um intervalo CIDR por linha.
  • Uma lista vazia significa sem restrição.
  • Chaves novas herdam a lista da conta, a menos que você crie uma chave com seus próprios allowed_ips, que substituem a lista herdada para aquela chave.
  • Uma requisição de um endereço fora da lista é recusada com 403 (“refused by model, route or IP policy”; tradução: recusada pela política de modelo, rota ou IP).

Crie uma chave com lista própria pela API do portal:

curl -X POST https://inference.broadnet.ai/portal/keys \
  -H "Authorization: Bearer $BROADNET_PORTAL_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{"label":"prod-worker","allowed_ips":["203.0.113.7","198.51.100.0/24"]}'

A resposta traz a chave original uma única vez. Guarde-a imediatamente no seu gerenciador de segredos; ela não pode ser lida de novo. O passo a passo completo está no guia de listas de IPs permitidos.

Listas de IPs permitidos servem para servidores com IPs de saída estáveis: uma VPS, um NAT gateway, um IP fixo de escritório. Para notebooks que mudam de rede, use uma chave separada sem lista e mantenha pequena a exposição do saldo.

Por que separar chaves de inferência das credenciais de administração?

A BroadNet usa dois tipos de credencial:

Credencial O que pode fazer Onde guardar
Chave de inferência Requisições a modelos em /v1/* Onde o app roda
Credencial do portal Criar e revogar chaves, mudar IPs permitidos, fazer compras Só nas suas ferramentas de automação ou administração

A documentação diz para tratar cada credencial do portal como autoridade total sobre a conta. Nunca coloque uma credencial do portal junto da sua aplicação. Se o servidor do app for comprometido, o atacante deve conseguir uma chave de inferência, não o controle da conta.

Com que frequência fazer a rotação de chaves de API?

A OWASP recomenda rotação regular “so that any stolen credentials will only work for a short time” (tradução: para que credenciais roubadas funcionem só por pouco tempo). As chaves da BroadNet duram um ano a partir da criação, então toda chave vai precisar ser trocada de qualquer jeito. Faça da rotação uma rotina:

  1. Crie uma chave nova com o mesmo padrão de rótulo e a mesma lista de IPs permitidos.
  2. Coloque-a no ar ao lado da antiga, ou troque o segredo e reinicie.
  3. Acompanhe o tráfego migrar para a chave nova.
  4. Revogue a chave antiga com DELETE /portal/keys/{alias}.

Como uma conta pode ter até dez chaves ativas, você pode manter a antiga e a nova juntas por alguns minutos, sem indisponibilidade. Antecipe a rotação das chaves às quais tinha acesso alguém que está saindo da equipe.

O que fazer quando uma chave vaza?

Quando uma chave vaza, revogue primeiro e investigue depois. Na BroadNet Inference, novas requisições param em até cinco segundos depois de uma revogação ou mudança na lista de IPs permitidos; a documentação explica que as decisões de autorização podem ficar num cache replicado durante esse intervalo limitado.

Depois de revogar:

  • verifique o uso da chave na página da conta ou em GET /portal/usage;
  • descubra como ela vazou (histórico de commits, logs de CI, uma captura de tela compartilhada);
  • faça a rotação de outros segredos guardados no mesmo lugar.

Uma chave revogada ou bloqueada retorna 401 ou 403; veja o guia de erros para que seu monitoramento não trate esses códigos como transitórios.

Como as chaves vazam pelos logs?

Logs são um vazamento fácil de deixar passar. Mascare o cabeçalho Authorization no log de depuração HTTP, nas ferramentas de relatório de erros e nos logs de acesso de proxies. Ao falar com o suporte, envie o X-Request-ID, o horário, a rota, o status e o alias da chave, nunca a chave em si. A documentação da BroadNet diz que o portal guarda só um hash de cada chave, então ele também não consegue mostrar uma chave perdida.

Como limitar o estrago de um vazamento que você ainda não descobriu?

Mesmo com todos os hábitos acima, conte com a possibilidade de uma chave vazar um dia. Reduza o raio de impacto:

  • Mantenha o saldo de pagamento por uso num nível que você aceitaria perder, e recarregue conforme precisar.
  • Use um plano de preço fixo para agentes pesados: uma sessão de plano tem preço fixo, então uma chave de plano roubada não consegue inflar uma conta por token. Veja o que “ilimitado” realmente significa.
  • Configure alertas para gasto ou taxa de requisições fora do normal por chave; a calculadora de custo de API de LLM dá um valor mensal normal para usar como referência nos alertas. Nosso post sobre controle de gastos com APIs de LLM cobre orçamentos e alertas.

Quais controles de chave a BroadNet Inference oferece?

Controle BroadNet Inference
Chave mostrada uma vez, guardada como hash Sim
Chaves ativas por conta Até 10
Validade da chave Um ano
Lista de IPs permitidos Até 32 entradas IPv4, IPv6 ou CIDR
Lista de IPs permitidos por chave Sim, allowed_ips na criação
A revogação passa a valer Em até cinco segundos
Credencial de administração separada Credencial do portal

As chaves protegem sua conta; a retenção zero de dados protege o que você envia por ela. Leia sobre as duas antes de colocar em produção.

Perguntas frequentes

Onde devo guardar uma chave de API de LLM?

Num gerenciador de segredos ou nos segredos criptografados da sua plataforma, injetada no processo como variável de ambiente, por exemplo BROADNET_API_KEY. Não no código-fonte, não num arquivo .env commitado e nunca no código de front-end.

Com que rapidez consigo revogar uma chave da BroadNet Inference?

A documentação da BroadNet diz que novas requisições param em até cinco segundos depois de uma revogação ou de uma mudança na lista de IPs permitidos, porque as decisões de autorização podem ficar num cache replicado durante esse intervalo limitado.

Quanto tempo dura uma chave da BroadNet Inference?

Uma chave de pagamento por uso dura um ano a partir da criação. Uma conta pode ter até dez chaves ativas, então você pode criar a substituta antes que a antiga expire.

A BroadNet consegue me mostrar uma chave de novo se eu a perder?

Não. A documentação da BroadNet diz que a chave original é retornada uma única vez e o portal guarda só o hash dela. Crie uma chave nova e revogue a antiga.

O que fazer se minha chave de API compatível com a OpenAI vazar?

Primeiro revogue, depois investigue. Verifique o uso da chave em busca de tráfego desconhecido, descubra onde ela vazou (histórico de commits, logs de CI, capturas de tela), faça a rotação de outros segredos guardados no mesmo lugar e emita uma chave substituta com lista de IPs permitidos.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity