Política de Gestão de Segredos
1. Objetivo
Esta política define os requisitos para a gestão do ciclo de vida completo de segredos - chaves de API, tokens de acesso, passwords, certificados, credenciais de base de dados e quaisquer outros valores que, se expostos, permitam acesso não autorizado a sistemas, dados ou infraestrutura.
Segredos são um dos vectores de comprometimento mais frequentes e impactantes: expostos em repositórios, logs, imagens de container ou pipelines, persistem muitas vezes durante meses sem serem rotacionados, transformando uma exposição temporária num risco permanente. A gestão eficaz de segredos não é apenas uma prática de higiene técnica - é um controlo de segurança fundamental cuja falha pode comprometer toda a postura de segurança da organização.
O objetivo desta política é garantir que:
- Nenhum segredo é armazenado em repositórios de código, logs, imagens ou artefactos de build
- Segredos são geridos centralmente em cofres de segredos com acesso controlado e auditado
- Segredos em pipelines são injetados de forma efémera, preferencialmente via OIDC/workload identity
- A rotação é automatizada ou agendada com TTL definidos por tipo e nível de criticidade
- A revogação em caso de exposição é imediata e verificável
2. Âmbito
Esta política cobre todos os segredos usados no contexto de desenvolvimento, pipeline, runtime e infraestrutura, independentemente do tipo:
- Credenciais de acesso a bases de dados, caches, filas e sistemas de mensagens
- Chaves de API de serviços externos
- Tokens de acesso a sistemas de cloud, registos de imagens, repositórios de artefactos
- Tokens de CI/CD (tokens de pipeline, deploy keys)
- Certificados TLS/mTLS e chaves privadas associadas
- Chaves de encriptação de dados em repouso ou em trânsito
- Passwords de contas de serviço
3. Proibições absolutas
As seguintes práticas são proibidas independentemente do nível de criticidade ou contexto:
| Prática proibida | Justificação |
|---|---|
| Hardcoding de segredos no código fonte | Propagação em histórico de versões; impossibilidade de rotação sem alteração de código |
Segredos em ficheiros de configuração versionados (ex: .env commitado, application.yml com passwords) | Exposição a todos com acesso de leitura ao repositório |
| Segredos em variáveis de ambiente não mascaradas em logs de pipeline | Exposição em logs, frequentemente armazenados sem controlo de acesso adequado |
| Segredos embebidos em imagens de container | Impossibilidade de rotação sem rebuild; exposição em camadas da imagem |
| Segredos em artefactos de build (JARs, wheels, binários) | Distribuição incontrolada do segredo com o artefacto |
| Uso de "segredos globais" partilhados entre múltiplos pipelines ou ambientes | Violação do princípio de mínimo privilégio; comprometimento de um pipeline compromete todos |
| Segredos de produção acessíveis em ambientes de desenvolvimento | Exposição desnecessária; risco de fuga via ambiente menos controlado |
A deteção de segredos hardcoded em código ou configuração deve ser automatizada no pipeline (secret detection). Qualquer finding bloqueia o merge em L2/L3, independentemente da severidade dos restantes gates.
4. Armazenamento centralizado
Todos os segredos devem ser armazenados em cofre de segredos centralizado, com acesso controlado e auditado:
| Requisito | L1 | L2 | L3 |
|---|---|---|---|
| Cofre de segredos centralizado em uso | Recomendado | Obrigatório | Obrigatório |
| Acesso ao cofre controlado por RBAC com mínimo privilégio | Recomendado | Obrigatório | Obrigatório |
| Acesso ao cofre auditado e log retido | Recomendado | Obrigatório | Obrigatório |
| Segredos de produção segregados dos restantes ambientes | Recomendado | Obrigatório | Obrigatório |
| Cofre com alta disponibilidade e backup | Recomendado | Obrigatório | Obrigatório |
Ferramentas de referência: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager.
5. Injeção em runtime
Segredos devem ser injetados nas aplicações e pipelines exclusivamente em tempo de execução - nunca persistidos no sistema de ficheiros ou em variáveis de ambiente de forma permanente:
5.1 Aplicações
- Segredos injetados via variável de ambiente em runtime (não em tempo de build)
- Variáveis de ambiente com segredos não expostas em endpoints de diagnóstico ou health checks
- Alternativa preferida em L2/L3: acesso direto ao cofre via SDK em runtime, com identidade do workload
5.2 Pipelines CI/CD
- Segredos referenciados via mecanismo nativo do sistema de CI (
secrets.*,CI/CD Variables masked,Variable Groups) - Output de comandos que acedam a segredos mascarado nos logs
- Credenciais de cloud via OIDC/workload identity (token efémero, TTL ≤ 1h) - elimina chaves estáticas de longa duração
5.3 Containers
- Segredos montados como volumes de segredo do orquestrador (ex: Kubernetes Secrets, com encriptação em repouso)
- Alternativa preferida em L3: acesso via cofre com workload identity (ex: Vault Agent, AWS IRSA, GCP Workload Identity)
- Segredos nunca passados como ARG de Docker durante o build
6. TTL, rotação e revogação
6.1 TTL por tipo de segredo
| Tipo de segredo | TTL máximo recomendado | L3 (TTL máximo obrigatório) |
|---|---|---|
| Tokens de pipeline (OIDC efémeros) | ≤ 1 hora | ≤ 1 hora |
| Tokens de acesso a APIs (short-lived) | ≤ 24 horas | ≤ 8 horas |
| Credenciais de base de dados (rotação automática) | 30 dias | 15 dias |
| Chaves de API de serviços externos | 90 dias | 30 dias |
| Certificados TLS (aplicação) | 1 ano | 90 dias |
| Chaves de encriptação de dados | 1 ano (com rotação de envelope) | 90 dias |
6.2 Rotação
- Rotação automatizada sempre que o sistema de emissão o suporte (ex: Vault dynamic secrets, AWS IAM roles, OIDC)
- Rotação manual agendada para segredos sem suporte a rotação automática, com alertas antes da expiração
- Rotação verificável sem alteração de código ou rebuild de imagens
- Histórico de rotações auditável
6.3 Revogação por exposição suspeita
Em caso de suspeita ou confirmação de exposição de um segredo:
- Revogar o segredo imediatamente (não aguardar o TTL)
- Emitir novo segredo e distribuir para os sistemas que dele dependem
- Rever os logs de acesso do cofre para avaliar uso indevido do período de exposição
- Registar o incidente e notificar conforme Política de Rastreabilidade e processo de IRP
6.4 Ciclo de vida das chaves e inventário de certificados
As chaves criptográficas da aplicação (cifra de dados, assinatura, TLS) seguem um ciclo de vida definido por tipo de chave (ENC-007):
| Fase | O que se exige |
|---|---|
| Geração | Em cofre ou HSM, com gerador aleatório aprovado e o algoritmo e tamanho da lista de primitivas (ENC-003) |
| Distribuição | Só por canal cifrado e autenticado, para os sistemas que a usam |
| Armazenamento | Em cofre ou HSM; nunca em código, imagens ou ficheiros de configuração versionados |
| Cópia de segurança e arquivo | Cifradas, com acesso restrito e separado das cópias dos dados que a chave protege |
| Recuperação | Procedimento documentado e testado, com registo de quem recuperou |
| Rotação e retirada | Nos prazos da §6.1; uma chave retirada guarda-se só para decifrar dados existentes |
| Revogação | Imediata em caso de exposição (§6.3) |
| Destruição | Quando já não há dados que dependam da chave, com registo |
Inventário de certificados. A aplicação mantém um inventário de todos os seus certificados (TLS, assinatura, clientes mTLS), com dono, emissor, validade e local de guarda da chave privada (cofre, HSM, dispositivo). Há alerta antes da expiração (pelo menos 30 dias; 90 dias em L3) e renovação automatizada quando o emissor o permite. A infraestrutura de chaves públicas da organização fica fora do âmbito deste Manual.
7. Segredos de terceiros e integrações
Segredos recebidos de terceiros (ex: chaves de API de fornecedores) devem ser:
- Armazenados no cofre centralizado, não em ficheiros partilhados ou sistemas de ticketing
- Com âmbito e permissões mínimas negociadas com o fornecedor
- Com prazo de validade conhecido e alerta de renovação
- Revogados imediatamente quando a integração é terminada
8. Responsabilidades
| Role | Responsabilidade |
|---|---|
| Developer | Nunca hardcodar segredos; usar mecanismos de injeção aprovados; reportar segredos acidentalmente expostos |
| DevOps / SRE | Gerir cofre de segredos; configurar rotação; implementar OIDC/workload identity; monitorizar acessos |
| AppSec Engineer | Definir TTLs e política de rotação; configurar secret detection no pipeline; auditar acessos ao cofre |
| Tech Lead | Garantir que a equipa conhece e segue esta política; não aprovar PRs com segredos hardcoded |
| GRC / Compliance | Auditar conformidade; verificar que segredos de produção estão segregados; verificar logs de acesso |
9. Agentes AI como principals não-humanos
O capítulo anterior descreve segredos para identidades CI tradicionais (runners, workloads). Quando um agente AI passa a operar o pipeline ou recursos da organização — Claude Code a executar tool calls, Copilot Workspace a actuar em PRs, agentes próprios via SDK — esse agente é mais um principal não-humano sujeito aos mesmos princípios desta política, com três especializações.
9.1 Identidade dedicada por agente e por ambiente
- Cada agente AI tem identidade workload efémera (OIDC) distinta — sem reuso de credenciais humanas, sem reuso entre ambientes (dev / staging / prod) nem entre agentes.
- TTL ≤ 1h (mesma regra das outras workload identities).
- A identidade está declarada no mandate do agente (campo
identity_ref— ver Policy 38 — Mandates de Agentes AI).
9.2 Scoping per-tool
A identidade do agente recebe apenas os scopes necessários para as tools declaradas na tools_allowlist do mandate — não os scopes máximos suportados pelo runtime. Exemplos práticos:
- Agente que abre PRs:
gh:pr:write,gh:repo:read. Nãogh:repo:writenemgh:repo:delete. - Agente que aplica manifests Kubernetes em staging:
k8s:deploy:staging:apply. Nãocluster-admin. - Agente que publica pacotes:
npm:publish:scoped-package. Nãonpm:publish:*.
Alterar tools_allowlist ou scopes é uma alteração estruturalmente equivalente a alterar uma IAM policy — exige novo ciclo de aprovação do mandate (ver Policy 38 §5).
9.3 Kill-switch operacional
Para agentes em nível A2+, o procedimento de revogação imediata (REQ-AGN-003) tem de ser exercitado periodicamente:
| Nível de autonomia | Cadência mínima de exercício |
|---|---|
| A2 | Anual (em sandbox/staging) |
| A3 | Trimestral (em sandbox/staging) |
| A4 | Mensal (em sandbox/staging) |
O exercício mede tempo total entre accionamento e revogação efectiva (revogação OIDC + terminação de runtime + isolamento de namespace). Resultado registado; falha no exercício é tratada como degradação operacional e bloqueia novas activações de agentes A3/A4 até estar resolvido.
9.4 Proibições específicas
- ❌ Reutilizar credenciais humanas para autenticar o agente — viola o princípio fundamental desta política aplicado a principals AI.
- ❌ Token long-lived (>1h) em qualquer identidade de agente AI — mesma regra que se aplica a runners CI.
- ❌
scopeque excede atools_allowlistdo mandate — over-privilege silencioso é incidente operacional. - ❌ Partilha de identidade entre dois agentes ou entre agente e humano — quebra o audit trail.
- ❌ Operação em A3/A4 sem kill-switch exercitado dentro da cadência exigida — o kill-switch é decorativo se nunca foi medido.
📌 Tudo o resto desta política (proibições absolutas §3, armazenamento centralizado §4, injeção em runtime §5, TTL/rotação §6) aplica-se sem reformulação ao caso dos agentes AI.
10. PII e dados sensíveis em prompts (cross-link RGPD)
Os capítulos anteriores cobrem segredos clássicos — tokens, chaves, credenciais. Quando um agente AI recebe input de utilizador (chat, document upload, form), os dados pessoais entram no prompt e, por arrastamento, podem viajar até ao fornecedor de serviços de IA do modelo. A categoria do problema é parecida — informação sensível a fluir por canal não controlado — mas o regime jurídico aplicável é o do RGPD, não o desta política. Esta secção articula explicitamente os dois para que a coerência operacional não se perca na fronteira.
10.1 Princípio de minimização
- O prompt enviado ao modelo deve conter apenas os dados pessoais estritamente necessários para a tarefa. Aplica-se directamente o princípio da minimização do RGPD Art. 5.º, n.º 1, al. c).
- Redacção / pseudonimização antes do envio quando viável — substituir nomes, e-mails, IDs por placeholders (
<USER_X>,<EMAIL_REDACTED>) e remapear no output. - Quando a redacção não é viável (ex.: tarefas que exigem o conteúdo literal), a decisão é registada e revista com cadência do mandate (Policy 38).
10.2 Base legal explícita
Cada uso operacional em que o agente vê PII tem base legal RGPD declarada — Art. 6.º (consentimento, contrato, obrigação legal, interesse legítimo, etc.) e, quando categorias especiais (Art. 9.º), base legal reforçada. A base legal é parte do mandate do agente (Policy 38 — adicionar campo legal_basis quando aplicável) ou da ficha de tratamento do projecto, e é revisitada nas revisões periódicas.
10.3 Subcontratantes
O fornecedor de serviços de IA do modelo é um subcontratante quando trata dados pessoais por conta da organização (RGPD, art. 28.º); se a própria organização for subcontratante, o fornecedor de serviços de IA é «outro subcontratante» (art. 28.º, n.os 2 e 4). Aplica-se a cláusula contratual prevista em Policy 33 §10:
- Contrato com o subcontratante (RGPD, art. 28.º, n.º 3) com cláusulas explícitas (retention, training opt-out, audit rights).
- Localização de processamento documentada; Standard Contractual Clauses (SCCs) ou outro mecanismo válido para transferências internacionais (RGPD Art. 44.º–49.º) quando o fornecedor de serviços de IA processa fora do EEA.
- Sem PII para fornecedores de serviços de IA fora da lista aprovada (
DEP-014).
10.4 Training opt-out obrigatório para PII
Quando o conteúdo do prompt inclui dados pessoais, é exigido contratualmente que o fornecedor de serviços de IA não use esse conteúdo para treino futuro do modelo. Preferência por zero retention para PII; quando o fornecedor de serviços de IA mantém logs operacionais, com retenção minimizada e propósito declarado.
10.5 Telemetria sob controlo do responsável pela implantação (deployer)
Os logs de inferência sob controlo da organização (AI Act, art. 19.º, n.º 1, para o prestador, e art. 26.º, n.º 6, para o responsável pela implantação / RGPD Art. 5.º) cumprem OPS-003 (retenção: pelo menos seis meses nos sistemas de IA de risco elevado, AI Act, art. 19.º, n.º 1, e art. 26.º, n.º 6) e OPS-012 (audit per tool invocation) com redacção de PII nos args — o audit trail preserva o suficiente para responder a auditoria sem replicar os dados pessoais.
10.6 Direitos do titular dos dados
Quando a interacção do utilizador com o agente gera dados pessoais, aplicam-se os direitos do RGPD (acesso Art. 15.º, rectificação Art. 16.º, apagamento Art. 17.º, oposição Art. 21.º). Em particular:
- Apagamento dos audit events sob controlo do deployer quando o titular exerce direito ao esquecimento (sujeito a obrigações legais de retenção concorrentes).
- Não-retenção pelo fornecedor de serviços de IA — verificado contratualmente. Quando a retenção pelo fornecedor de serviços de IA existe, o titular tem de poder accionar o direito também aí.
10.7 Proporcionalidade
| Requisito | L1 | L2 | L3 |
|---|---|---|---|
| Minimização / redacção antes do envio | Recomendado | Obrigatório quando viável | Obrigatório (categorias especiais sempre redactadas) |
| Base legal declarada | Recomendado | Obrigatório | Obrigatório (revisão GRC) |
| Subcontratante com cláusulas do art. 28.º | Obrigatório (sempre que há PII) | Obrigatório | Obrigatório + revisão Legal |
| Training opt-out contratualizado | Obrigatório (sempre que há PII) | Obrigatório | Obrigatório |
| Localização EEA / SCCs quando aplicável | Obrigatório (quando há PII e processamento fora EEA) | Obrigatório | Obrigatório (preferência por processamento EEA) |
Redacção de PII nos audit events (OPS-012) | Recomendado | Obrigatório | Obrigatório |
| Procedimento para direitos do titular | Recomendado | Obrigatório | Obrigatório (incl. apagamento sob controlo do deployer) |
10.8 Anti-padrões
- ❌ Enviar PII a fornecedor de serviços de IA fora da lista aprovada — shadow AI com risco RGPD.
- ❌ Logar prompts com PII sem redacção em
OPS-012—audit trailtorna-se ele próprio repositório de dados pessoais sem base legal específica. - ❌ Confiar que o fornecedor de serviços de IA "não usa para treino" sem cláusula contratual — declarações operacionais não substituem o Art. 28.º.
- ❌ Ignorar categorias especiais (art. 9.º RGPD) no prompt — saúde, dados biométricos para identificação inequívoca, origem racial ou étnica, etc. — ou dados de crianças (art. 8.º), que exigem condições reforçadas que muitos casos de uso de chatbots não satisfazem.
- ❌ Tratar redacção como ofuscação suficiente — pseudonimização (RGPD) não é anonimização; PII pseudonimizada continua a ser dado pessoal.
10.9 Cruzamento com cross-check RGPD
Para alinhamento detalhado com o regulamento, ver o cross-check RGPD. Esta secção mantém a coerência operacional na fronteira AppSec ↔ RGPD; o cross-check trata as obrigações jurídicas em detalhe.
11. Revisão e auditoria desta política
Esta política deve ser revista anualmente ou após qualquer um dos seguintes eventos:
- Incidente com origem em segredo exposto ou não rotacionado
- Adoção de novo cofre de segredos ou plataforma de cloud
- Alteração de fornecedor com impacto em chaves de integração
12. Referências normativas e técnicas
| Referência | Relevância |
|---|---|
| SbD-ToE Cap. 07 - CI/CD Seguro | Gestão e injeção de segredos em pipeline; US-19 — Agentes AI como principals na pipeline |
| SbD-ToE Cap. 09 - Containers e Imagens | Segredos fora de imagens; workload identity |
| SbD-ToE Cap. 11 - Deploy Seguro | Segredos em runtime de deploy |
SbD-ToE Cap. 04 — Arquitetura Segura (ARC-015) | Agente como principal isolado; least privilege per-tool |
Política de CI/CD Seguro (17_policy-cicd-seguro.md) | Secret detection no pipeline; masking de logs |
| Policy 38 — Mandates de Agentes AI | Operacionaliza REQ-AGN-001: mandate, ownership, kill-switch |
| Policy 16 — Uso de Ferramentas de Apoio | Regras operacionais A2+ para agentes |
| NIST SP 800-207 — Zero Trust Architecture | Princípios aplicados a principals não-humanos (incluindo agentes AI) |
| OWASP Secrets Management Cheat Sheet | Referência de boas práticas de gestão de segredos |
| HashiCorp Vault Documentation | Cofre de referência; dynamic secrets; OIDC |
| NIST SP 800-57 | Key Management Guidelines |
| CIS Benchmark - Secrets Management | Controlos de referência |
| SSDF PO.5.2 | Implement and maintain secure environments for software development |