03 · SECRET MANAGER

O valor de um secret só existe no seu Agente.

A API do Heimdall governa o nome, a versão, quem pode ler e quem leu, mas se recusa a receber o valor. O Agente guarda o valor cifrado com uma chave sua e só entrega uma leitura que conseguiu registrar.

Falar com engenharia

Abre uma conversa no WhatsApp. Prefere e-mail? heimdall@yops.cloud

O que faz

A API não aceita o valor

Quando você cria ou atualiza um secret pelo CLI, o metadado é gravado na API e o valor, no Agente. Se um pedido levar o valor para a API, ele volta com 400 VALUE_NOT_ACCEPTED. O Console nunca mostra nem recebe valor nenhum.

Quem leu, qual versão, de onde

Cada leitura que o Agente entrega vira um registro: quem leu, quando, qual versão, em que environment, qual Agente a entregou e de qual endereço. O Agente se recusa a entregar uma leitura que não conseguiu registrar. Por isso, um buraco na sequência significa "lido e não reportado" e vira evento de auditoria.

Quando alguém sai

Quando uma pessoa é removida da organização, o Heimdall marca como at_risk cada secret que ela leu e que não mudou desde então, em cada environment em que ela o leu, e avisa a organização. Gravar um valor novo num environment tira a marca daquele environment, e só dele.

Quando um valor vaza

Ao desativar a versão vazada, o Agente troca o valor por um registro que diz apenas que ela foi desativada e passa a responder 410. Todos os Agentes da organização ficam sabendo da desativação no sync seguinte. Nada volta para a versão anterior, porque ela corresponde a uma credencial que alguém já trocou.

O secret pessoal

Só a dona alcança um secret pessoal, pelo certificado de cliente dela. Nenhum token e nenhum papel o abrem, nem o de owner da organização, e só a dona lê a trilha de leitura dele.

Na aplicação, sem arquivo `.env`

heimdall run executa um programa com os secrets do projeto como variáveis de ambiente, lidos do Agente na hora. O heimdall.yaml, que lista os nomes deles, não contém segredo e pode ir para o repositório. No Kubernetes, o External Secrets Operator lê direto do Agente, com um token só de leitura.

Apagar sem deixar cópia para trás

Cada Agente informa à API o que o store dele guarda, mas nunca o valor. Enquanto um Agente que não vai mais sincronizar puder guardar uma cópia, a API recusa apagar o secret com 409 VALUE_MAY_PERSIST e diz qual é o Agente.

Rotação da senha do banco

A senha de cada service user do Database Manager nasce no Agente e é rotacionada lá mesmo, numa agenda, com um período de carência para a aplicação ler a senha nova.

Como funciona

Uma leitura, do comando ao registro:

O CLI pede o valor à API local do Agente que guarda aquele environment, usando o certificado de cliente da pessoa.
O Agente decide com base nas policies da organização, que recebeu pelo sync. Mesmo com a API fora do ar, ele continua decidindo por até 24 horas.
O Agente registra a leitura no próprio store. Se não conseguir registrar, não entrega o valor.
O valor vai para o CLI. Na rodada de sync seguinte (a cada 60 segundos, por padrão), o registro vai para a API. O valor nunca passa por esse canal.

TERMINAL$ heimdall secret access-log db-password

ACCESSED_AT           ACCESSOR                ENVIRONMENT  VERSION  SERVED_BY   FROM       READS
2026-10-10T06:18:58Z  agent site-agent        prod         3        site-agent  127.0.0.1  1
2026-10-10T06:18:45Z  admin@demo.example.com  prod         2        site-agent  127.0.0.1  1
2026-10-10T06:18:45Z  admin@demo.example.com  prod         3        site-agent  127.0.0.1  1

Saída real de heimdall secret access-log.

Onde o dado fica

Tudo roda na sua infraestrutura. Mesmo assim, a divisão abaixo importa dentro da sua empresa, porque mostra quem, no seu time, tem acesso a quê.

Secret Manager: onde o dado fica
NO AGENTE	NA API, QUE É SUA
O valor da versão atual de cada `secret`. O store, em PostgreSQL ou DynamoDB, é cifrado por inteiro com uma master key de 32 bytes que é sua, guardada numa variável de ambiente, num arquivo ou numa chave do AWS KMS; nesse último caso, o material da chave nunca sai do KMS. O registro local de cada leitura.	O nome, o tipo, a descrição, as tags e o status. O número de cada versão, por `environment`, e quem a criou. Os Components ligados a ele. Quem leu cada versão. O que cada Agente diz guardar (o nome, a versão e se ela foi desativada), sem o valor.

Por isso, ninguém recupera um valor pela API: nem a Yops, nem você. O backup do store e da master key fica com o seu time.

Ver a segurança

Quem aprova o quê

Secret Manager: quem aprova o quê
ATO	QUEM
Ler um `secret` da organização	todo membro, por padrão. Uma `policy` `forbid` restringe o acesso, por exemplo, a `production`
Criar, atualizar, apagar e desativar versão	`owner` e `admin`, por padrão
Ler a trilha de quem leu	`owner` e `admin`
Ler um `secret` pessoal e a trilha dele	só a dona
Decidir quais Agentes guardam cada `environment`	`owner`
Decidir o que cada programa alcança	quem opera o Agente, com um token por programa que tem escopo e verbos próprios (`read`, `write`, `delete`)

Com os outros módulos

01

Catálogo

Um secret pode ser ligado aos Components que o usam.
02

Infrastructure Manager

A credencial estática de uma conta de cloud é um secret no Agente, e o Terraform a lê de lá.
04

Database Manager

A credencial administrativa de cada banco é um secret no Agente, e a senha de cada service user nasce e é rotacionada nele.
06

Release Manager

O token do Argo CD que o Agente usa é um secret guardado no próprio Agente, e a API só conhece o nome da Application.

Converse com quem constrói o Heimdall.

Conte como a sua engenharia guarda secrets e acessa o banco hoje. Respondemos dizendo o que o Heimdall colocaria sob regra primeiro e como a implantação chegaria lá.