Previna vazamentos de chaves de API em três camadas: encurtar o tempo de exposição da credencial, restringir o escopo de permissões e configurar alertas com mitigação de perdas, abrangendo chaves de API temporárias, rotação regular, listas de permissões de IP, conexões privadas, alertas de orçamento e alertas de monitoramento de modelos.
Visão geral
Uma chave de API é a credencial usada para chamar os serviços de modelo do Alibaba Cloud Model Studio. Depois de vazar, qualquer pessoa que a obtenha pode chamar os modelos dentro do escopo de autorização da chave e consumir sua cota. O impacto de um vazamento pode ser decomposto em quatro fatores: probabilidade de vazamento, tempo de exposição, escopo de permissões por chamada e duração da anomalia. A probabilidade de vazamento é reduzida pelas práticas básicas presentes em toda esta página, e os outros três fatores são reduzidos pelas três camadas a seguir:
Camada | Fator reduzido | Medidas principais |
|---|---|---|
Encurtar o tempo de exposição | Tempo de exposição | Chaves de API temporárias para clientes, exibição única com armazenamento controlado, rotação regular e revogação na saída de pessoal |
Restringir o escopo de permissões | Escopo de permissões por chamada | Uma chave por negócio, isolamento por workspace, lista de permissões de IP e escopo de modelos, conexões privadas |
Alertas e mitigação de perdas | Duração da anomalia | Alertas de orçamento com parada automática, alertas de monitoramento de modelos, detecção de riscos da plataforma |
- Aplicativos leem credenciais de variáveis de ambiente ou de um serviço de gerenciamento de chaves, em vez de codificá-las diretamente; configure a varredura de informações confidenciais no CI/CD (com ferramentas de varredura de credenciais como o gitleaks), cobrindo padrões de chaves de API.
- Mantenha um registro de chaves: comece com uma tabela básica de IDs de chaves, finalidades, responsáveis e datas da última rotação e, aos poucos, acrescente região, workspace, escopo de permissões e orçamento; nunca armazene chaves completas no registro.
- Restrinja as permissões de gerenciamento de chaves (criar, visualizar, editar, excluir) aos administradores que delas necessitam.
Encurtar o tempo de exposição da credencial
Armazene chaves de API permanentes com segurança
Uma chave de API recém-criada é exibida por completo apenas uma vez, no momento da criação; depois que a caixa de diálogo é fechada, o texto completo não pode mais ser visualizado nem copiado. Se você não a salvou, só é possível redefinir ou recriar a chave; consulte Obter uma chave de API.
Após a criação, armazene a chave completa diretamente em um repositório de credenciais controlado (um serviço de gerenciamento de chaves ou o gerenciamento de segredos da sua plataforma de implantação), sem fazê-la transitar por capturas de tela, e-mails, ferramentas de chat ou documentos comuns; o valor mascarado na lista serve apenas para identificação e comparação.
Nunca coloque chaves de API permanentes nos seguintes locais:
- Scripts de navegador, artefatos de build do frontend e pacotes de aplicativos móveis
- Repositórios de código públicos ou compartilhados (apenas adicionar .gitignore não remove credenciais de commits históricos)
- Saídas de notebooks e códigos de exemplo
- Capturas de tela e gravações de tela
- Tickets de suporte, chats em grupo e documentos online
- Prompts, bases de conhecimento e contextos de agentes
- URLs de requisição e parâmetros de consulta
- Logs de acesso e pilhas de exceção
- Plug-ins de terceiros e serviços de retransmissão de modelos (serviços que encaminham suas chamadas de modelo)
- Ambientes compartilhados, arquivos de configuração expostos externamente, imagens e backups
Use chaves de API temporárias em cenários no lado do cliente
Navegadores, aplicativos móveis e mini programas não conseguem manter credenciais confidenciais de forma confiável. Nesses cenários, faça com que um backend autenticado emita chaves de API temporárias para o frontend usar em chamadas diretas:
- Mantenha a chave de API permanente apenas no seu próprio servidor e nunca a entregue a nenhum cliente.
- Quando o frontend precisar chamar um modelo, solicite primeiro uma chave temporária ao seu backend.
- O backend chama a API de geração de chave de API temporária e retorna ao frontend uma chave st- de curta duração.
- O frontend chama o Model Studio diretamente com a chave st-.
Faça a rotação regular das chaves e revogue-as na saída de pessoal
Chaves de validade longa configuradas em códigos ou agentes acumulam exposição com o tempo e devem passar por rotação regularmente:
- Crie uma nova chave e reconfigure permissões e orçamento conforme as necessidades atuais.
- Atualize as referências de credenciais nos serviços do negócio.
- Verifique se a nova chave funciona corretamente.
- Exclua a chave antiga e confirme que ela não consegue mais iniciar chamadas.
- Atualize o registro de chaves.
Restrinja o escopo de permissões da credencial
Uma chave por negócio e isolamento por workspace
Atribua chaves de API independentes a aplicativos e ambientes distintos (produção, testes e depuração pessoal): isso reduz o impacto do vazamento de uma única chave e facilita localizar problemas e fazer a rotação por chave. Quando você precisar de isolamento de permissões, de controle refinado de acesso a modelos ou de contabilidade de custos independente, atribua ao negócio um workspace não padrão (um workspace é um contêiner do Model Studio que isola permissões e custos; toda conta já tem um workspace padrão); o escopo básico de chamadas de uma chave é restringido pelo workspace ao qual ela pertence; consulte Gerenciamento de permissões.
Além disso, restrinja as permissões de gerenciamento de chaves aos administradores necessários; contas que podem fazer login no console para gerenciar credenciais devem seguir o princípio do menor privilégio e habilitar a autenticação multifator conforme as exigências da organização.
Configure a lista de permissões de IP e o escopo de modelos
Depois de definir a permissão de uma chave de API como Personalizada no painel de criação ou edição da chave, você pode restringir ainda mais o escopo de chamadas dela:
- Lista de permissões de IP: permita apenas os IPs ou blocos CIDR de saída públicos realmente usados pelo negócio, com no máximo 20 entradas (use um serviço como curl ifconfig.me para descobrir seu IP de saída público). Todos os endereços IPv4 são permitidos por padrão; apenas criar a chave não significa que as restrições de origem estão em vigor. Ao chamar por NAT, proxy ou gateway, informe o endereço de saída público que o Model Studio realmente vê, e não o endereço de intranet do servidor.
- Escopo de modelos: uma vez habilitado, a chave só pode chamar os modelos selecionados (até 30, limitados pelos modelos autorizados no workspace), impedindo que chaves vazadas sejam usadas em modelos de alto custo.
Chame por meio de uma conexão privada
Para cenários com requisitos rigorosos de segurança de rede, você pode estabelecer uma conexão privada (PrivateLink) entre sua VPC e o Model Studio: as chamadas não passam pela rede pública, de modo que invasores externos sem conectividade de rede não conseguem chamar o serviço mesmo que a chave vaze. Para o método de configuração, consulte Acessar as APIs do Model Studio por meio de uma rede privada.
Configure alertas e mitigação de perdas
Alertas de orçamento e parada automática
Defina orçamentos mensais e limites de alerta para a conta, um workspace ou uma única chave de API; priorize orçamentos independentes para chaves de alto risco, como as de desenvolvimento e testes, demonstrações e integrações de terceiros. Quando o gasto atinge o limite e quando o orçamento se esgota, notificações são enviadas por mensagens internas do site, SMS, e-mail ou bots; após habilitar "parar imediatamente quando o orçamento for atingido", o serviço restringe as chamadas pay-as-you-go dessa dimensão e retorna 429. Para o método de configuração, consulte Gerenciamento de orçamento.
Alertas de monitoramento de modelos
O monitoramento de modelos agrega por workspace o número de chamadas, o uso de tokens, o número de falhas e a taxa de falhas, oferece filtragem por chave de API e permite criar regras de alerta com base em modelos de alerta predefinidos ou personalizados, notificando contatos ou grupos de contatos. Configure alertas de pico de volume ou de número de chamadas para chaves de alto risco: as anomalias ficam visíveis em minutos após as chamadas ocorrerem, e disparos fora do horário de trabalho exigem intervenção manual. A primeira configuração de alerta exige autorizar antes a função de serviço do Cloud Monitor na entrega de dados; para o método de configuração, consulte Alertas.
Detecção de riscos pela plataforma
A plataforma examina periodicamente ambientes públicos, como repositórios de código abertos, para identificar chaves de API vazadas e notificar você proativamente; os canais concretos dependem do que está habilitado (podem incluir SMS, e-mail e mensagens internas do site). Ela também identifica comportamentos anômalos, como logins de IPs incomuns, picos de tráfego fora do horário e aumentos anormais de custos.
A detecção e os alertas de riscos da plataforma são capacidades de detecção de anomalias e de aviso antecipado oferecidas proativamente pela plataforma para melhorar a experiência de uso; não estão dentro do escopo de serviços acordado no SLA; devido à complexidade dos cenários de risco, não há compromisso de cobertura absoluta dos alertas, e a identificação e a entrega dos alertas também podem sofrer atrasos. A guarda segura e o uso em conformidade de credenciais como chaves de API são de sua responsabilidade; tome como linha de defesa principal os alertas de orçamento, os alertas de monitoramento de modelos e a rotação regular configurados por você mesmo; não receber alertas da plataforma não significa que não há risco de vazamento. Ao identificar um vazamento suspeito ou receber um alerta, localize e trate o problema seguindo Investigação de vazamento de chave de API.
Checklist antes da entrada em produção
Desenvolvedores individuais e equipes pequenas podem começar pelo mínimo: definir orçamento com notificações de alerta para a chave, manter a credencial apenas em variáveis de ambiente e fazer a rotação regularmente. O checklist completo é o seguinte:
- Produção, testes e integrações de terceiros não compartilham a mesma chave de API; os responsáveis e as finalidades de cada chave estão claros.
- Região, workspace, escopo de modelos e IPs de saída das requisições foram verificados, com permissões cobrindo apenas o escopo necessário.
- Chaves permanentes ficam armazenadas apenas em backends controlados e nunca entram em clientes, código-fonte, prompts, documentos compartilhados ou logs.
- As chaves não foram entregues a serviços de retransmissão de terceiros não confiáveis ou a ambientes de plug-ins; se foram, a entrega foi interrompida e as chaves passaram por rotação.
- As credenciais são injetadas por variáveis de ambiente ou por segredos; arquivos confidenciais e artefatos de build não contêm texto claro.
- Cenários de chamada direta pelo cliente usam chaves de curta duração emitidas por um backend autenticado, e a chave permanente emissora teve as permissões restritas.
- As novas chaves foram armazenadas sob controle; as chaves antigas, as chaves ociosas e as chaves de pessoas que saíram foram revisadas.
- Orçamentos e alertas nos níveis de conta, workspace e chave foram configurados, com canais de notificação e responsáveis definidos.
- O impacto na disponibilidade e o atraso de efetivação da parada imediata quando o orçamento é atingido foram avaliados.
- Os procedimentos de rotação e de resposta a vazamentos estão definidos; as etapas de investigação estão descritas em Investigação de vazamento de chave de API.
Perguntas frequentes
Uma chave de API temporária tem menos permissões que uma chave de API permanente?
Uma chave de API temporária tem menos permissões que uma chave de API permanente?
Com uma lista de permissões de IP configurada, ainda preciso me preocupar com vazamentos de chave?
Com uma lista de permissões de IP configurada, ainda preciso me preocupar com vazamentos de chave?
O que fazer se eu entreguei uma chave a um serviço de retransmissão de terceiros?
O que fazer se eu entreguei uma chave a um serviço de retransmissão de terceiros?