Recursos
Trilha de auditoria
Todo login, toda mudança em usuários, papéis, dashboards, alertas e workloads, e toda
recusa, cada um registrado como um evento com quem, o quê, quando, de onde e com qual
resultado. O orbit-api grava a trilha (Adendo v0.5 do CONTRACT.md), o Deck a lê em
/deck/admin/audit, e ela pode ser exportada em CSV. Para lê-la, é preciso ter a permissão
audit.read, que só o papel embutido admin tem (veja identity.md).
O que é registrado
| Ação | Quando |
|---|---|
auth.login | Um login deu certo. |
auth.login_failed | Um login foi recusado: senha errada, nome de usuário desconhecido, conta desativada ou uma espera ainda em andamento. |
auth.logout | Uma sessão foi encerrada pelo próprio dono. |
auth.setup | O primeiro administrador foi criado com o código de configuração, ou alguém tentou um código errado. |
auth.password_change | Alguém trocou a própria senha, ou digitou errado a senha atual. |
user.create | Um administrador criou um usuário; também é gravado uma vez para cada conta que o orbit-api cria na inicialização (o administrador definido por variável de ambiente, os usuários de demonstração), sem autor. |
user.update | O nome ou o e-mail de um usuário mudou, ou vários campos mudaram de uma vez. |
user.role_change, user.disable, user.enable | Mudou exatamente aquele único campo. |
user.password_reset, user.mfa_reset | Uma senha nova, ou o segundo fator desligado, mesmo que outros campos tenham mudado junto (a senha prevalece quando os dois mudam). Com resultado failure, alguém tentou isso na própria conta sem a senha atual ou o código certos. |
user.delete, user.revoke_sessions | Uma conta foi removida, ou todas as sessões dela foram encerradas. |
role.create, role.update, role.delete | Um papel personalizado mudou. |
dashboard.create, dashboard.update, dashboard.delete | Um dashboard salvo mudou. |
alert.ack, alert.unack, alert.silence, alert.unsilence | O reconhecimento ou o silenciamento de um alerta mudou. |
workload.scale, workload.resources, workload.rollback, workload.restart | Toda tentativa de escrita: os dry runs, as aplicações e as recusas. Um rollback acrescenta fromRevision, toRevision, images, changes (variáveis de ambiente só pelo nome, nunca o valor) e, na aplicação, typedConfirmation. O diff de um reinício é o restartedAt do template antes e depois, e a aplicação acrescenta typedConfirmation. |
workload.rollback.result | Como terminou o rollout de um rollback aplicado: outcome (completed, failed ou timeout), durationMs, updated, ready, desired. |
access.denied | Um usuário logado pediu uma rota que o papel dele não concede. |
Uma mudança de usuário recebe o nome do que mudou: mesmo que um formulário reenvie
todos os campos, uma troca de papel fica registrada como user.role_change, e um salvamento
que não mudou nada não registra nada. A página de configurações do Deck é somente leitura nesta
versão e não registra nada.
Um evento, do jeito que o GET /api/v1/audit o devolve:
{
"id": "1790227603035-7bf2888b",
"ts": 1790227603035,
"actor": { "id": "25c24c6f2e7315a6", "username": "viewer", "role": "viewer" },
"action": "access.denied",
"target": { "type": "route", "id": "GET /api/v1/users", "name": "GET /api/v1/users" },
"outcome": "denied",
"ip": "203.0.113.24",
"userAgent": "Mozilla/5.0 (X11; Linux x86_64)",
"requestId": "78162c82575d135d8642787e",
"details": { "permission": "users.manage" }
}tsé o epoch em milissegundos e nunca anda para trás na trilha, mesmo quando o relógio anda.idé esse instante mais 8 dígitos hexadecimais aleatórios.actorénullquando ninguém estava logado: um login com falha, as contas criadas na inicialização.roleé o papel do autor naquele momento.target.typeéuser,role,route,dashboard,alertouworkload.outcomeésuccess,denied(recusado por uma regra: uma permissão, uma espera, uma conta desativada) oufailure(tentado e malsucedido: uma senha errada, um erro do API server).detailsguarda obeforee oafterde uma mudança (para um dashboard, um resumo: título, versão, contagem de painéis e de variáveis, tags), a permissão que uma recusa citou, o dry run e o diff de uma escrita em workload. Nunca guarda uma senha, um token ou um verificador; uma redefinição de senha registra apenas que ela aconteceu.
Três regras mantêm a trilha fiel sem deixar que ela seja inundada nem que vire um vazamento:
- Um login com falha só nomeia o alvo quando o nome de usuário existe. Qualquer outro valor
é guardado como
usernameFingerprint, os 12 primeiros dígitos hexadecimais do SHA-256 dele, então uma senha digitada no campo de usuário nunca vai parar na trilha, e mesmo assim tentativas repetidas continuam correlacionáveis. - Uma recusa durante uma espera de login é registrada uma vez por espera, com
retryAfterSeconds. access.deniedé respondido toda vez, mas registrado no máximo uma vez por segundo por usuário (com bursts de 30), então um script em loop numa rota proibida não consegue encher o disco.
Todo evento é gravado em disco, com fsync, antes de a requisição que o causou ser
respondida, e também vira uma linha audit no próprio log do orbit-api (id, action,
outcome, actor, target, client_ip, request_id), então um pipeline de logs também
recebe a trilha.
Como ler no Deck
/deck/admin/audit mostra a janela escolhida na barra superior (por padrão, a última hora):
um histograma de eventos ao longo do tempo, empilhado por resultado, em que clicar numa
barra dá zoom nela; facetas por resultado, ação e autor, em que cada faceta conta os eventos
que atendem a todos os demais filtros; os eventos, dos mais novos para os mais antigos, 100
por vez; e um painel lateral por evento, com as mudanças numa tabela de antes e depois e o
JSON bruto. A caixa de busca aceita palavras soltas, cada uma das quais precisa aparecer em
algum valor do evento, e cinco campos:
| Termo | Casa com |
|---|---|
actor:grace | O nome de usuário do autor |
action:user.* | A ação |
outcome:denied | success, denied ou failure |
ip:10.0.* | O endereço do cliente |
target:checkout | Parte do tipo, do id ou do nome do alvo |
Os quatro primeiros casam exatamente, ou como prefixo quando o valor termina em *. Os
termos se combinam com AND, a comparação ignora maiúsculas e minúsculas, e "quoted words"
continuam sendo um único termo. O endereço da página guarda os filtros, então um link abre
a mesma visão.
Como ler pela API
GET /api/v1/audit aceita from e to (epoch em milissegundos, ambos inclusivos; por
padrão, as últimas 24 horas), actor, action e outcome (valores exatos), q (a
linguagem de busca acima), limit (de 1 a 1.000, default 100) e cursor. Com a SESSION
de um usuário que tenha audit.read (identity.md → "Entrar pelo shell"):
curl -fsS -G -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" \ --data-urlencode 'q=outcome:denied' --data-urlencode 'limit=50' localhost:8080/api/v1/auditA resposta é {events, nextCursor, total, facets: {action, actor, outcome}, interval, histogram: [{t, n, denied, failure}]}. total, as facetas e o histograma cobrem a janela
inteira em todas as páginas; interval é a largura do bucket do histograma em
milissegundos, escolhida para que a janela caiba em 60 barras. Para a página seguinte,
envie os mesmos filtros com cursor igual a nextCursor, que vem vazio na última página.
Um valor de filtro maior do que a rota aceita (q 200 bytes, actor e action 64,
outcome 16) é recusado com 400.
Exportar CSV
A ação "Exportar CSV" do Deck baixa os eventos que os filtros atuais selecionam. Pela API,
format=csv transmite todos os eventos que casam com os mesmos filtros, dos mais novos para
os mais antigos, até 100.000 linhas, ignorando limit e cursor:
curl -fsS -G -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" \ --data-urlencode 'format=csv' -o orbit-audit.csv localhost:8080/api/v1/auditColunas: time (RFC 3339, UTC), actor, role, action, outcome, target_type,
target_id, target_name, ip, user_agent, request_id, details (JSON). Uma célula
que começa com =, +, -, @, um caractere de tabulação ou um retorno de carro ganha um
' na frente, para que um user agent ou um nome de usuário não rode como fórmula de
planilha. As duas respostas saem com Cache-Control: no-store.
Retenção e armazenamento
A trilha é JSONL append-only em ORBIT_DATA_DIR/audit, um arquivo por dia UTC
(2026-09-24.jsonl). ORBIT_AUDIT_RETENTION decide por quanto tempo um dia é mantido: em
dias, como 90d (o default) ou 365d, ou uma duração no formato Go de 24h ou mais; com
qualquer valor menor, o serviço se recusa a iniciar. Os arquivos diários mais antigos que
isso são apagados por inteiro quando o orbit-api inicia e quando o primeiro evento de um
novo dia é gravado. Dimensione o volume a partir da sua própria trilha: rode du -sh no
diretório audit depois de uma semana representativa e extrapole para o período de
retenção.
Uma consulta lê, linha a linha, os arquivos dos dias que a janela dela cobre, então uma
janela larga sobre uma retenção longa custa uma varredura desses arquivos; o caminho de
evolução que o código aponta é um índice em SQLite ou Postgres. O backup do diretório é
tratado em operations.md.
Como o IP do cliente é determinado
O ip de um evento, e o endereço que serve de chave para todo limite por cliente do
orbit-api, é decidido em dois lugares.
O web decide o que repassa. Toda requisição do navegador chega ao orbit-api pelo
web, então o peer do socket que o orbit-api vê é sempre o endereço do próprio web. O
web só repassa um header X-Forwarded-For quando WEB_TRUST_PROXY=true, o que indica que
um proxy de borda na frente do web o escreveu; caso contrário, não envia nenhum, e um
header definido pelo navegador nunca atravessa.
O orbit-api decide em que acredita. Ele só lê o X-Forwarded-For numa requisição que
traz o bearer de serviço dele, que só o web tem, ou que vem de um peer em
ORBIT_TRUSTED_PROXIES. Ele percorre o header da direita para a esquerda, pula todo
endereço que está em ORBIT_TRUSTED_PROXIES e registra o primeiro que não está. Sem um
header avalizado, ou com um malformado, ele registra o peer do socket.
| Caminho de instalação | WEB_TRUST_PROXY | O que o ip mostra |
|---|---|---|
| Helm | Derivado: true quando ingress.enabled, false caso contrário | O cliente como o ingress o viu |
| Manifestos puros | true (o 60-ingress.yaml é a borda) | O cliente como o ingress o viu |
| Compose | false (o web é a borda) | O endereço do contêiner do web, para todo visitante |
| Loop do k3d | Derivado pelo chart, true (Traefik) | O cliente como o Traefik o viu |
ORBIT_TRUSTED_PROXIES vem vazio por padrão em todo caminho de instalação, e deve continuar
assim: ele serve para proxies entre o web e o orbit-api (um sidecar de service mesh, um
gateway interno), nunca para o próprio web, que o bearer já avaliza. Com
ORBIT_AUTH_MODE=disabled não há bearer, então só se acredita em um peer que esteja em
ORBIT_TRUSTED_PROXIES. E WEB_TRUST_PROXY=true sem nada na frente do web deixa o
navegador escolher o endereço sob o qual ele é registrado.
Atrás de um load balancer de nuvem ou de uma CDN
A trilha de auditoria registra o endereço que o ingress controller enxerga,
seja ele qual for. O ingress-nginx e o Traefik, por padrão, substituem o
X-Forwarded-For de um cliente pelo endereço da conexão, e um ALB da AWS acrescenta o
endereço que viu, então a última entrada é sempre a visão que o controller tem de quem
chama. Quando o controller fica atrás de um load balancer ou de uma CDN que esconde o
cliente, essa visão é o load balancer, e todo evento carrega o endereço do load balancer
até que a borda passe adiante o cliente real. No ingress-nginx, isso fica no ConfigMap dele
(o controller.config do chart):
| Chave | Defina como | Por quê |
|---|---|---|
use-forwarded-headers | "true" | Acreditar no X-Forwarded-For do load balancer L7 ou da CDN à frente, em vez de substituí-lo. Default "false". |
proxy-real-ip-cidr | As faixas do próprio load balancer ou da CDN (na AWS, o CIDR da VPC, no caso de um ALB) | Em quem acreditar. O default, "0.0.0.0/0", acredita em qualquer um, o que deixa todo cliente forjar o próprio endereço: restrinja sempre. |
compute-full-forwarded-for | Deixe "false" | "true" acrescenta o endereço do load balancer à cadeia, e o orbit-api, que registra o endereço mais à direita em que não confia, registraria de novo o load balancer. |
enable-real-ip com forwarded-for-header | "true" e o header de cliente da CDN (o da Cloudflare é CF-Connecting-IP) | Para uma CDN que nomeia o cliente num header próprio; combine com proxy-real-ip-cidr definido com as faixas que a CDN publica. |
use-proxy-protocol | "true", com o proxy protocol ligado no load balancer | Para um load balancer L4 (um NLB da AWS), que não consegue acrescentar um header. A alternativa, nesse caso, é externalTrafficPolicy: Local no Service do controller. |
Essas configurações valem para o controller inteiro: mudam como todo Ingress do cluster
enxerga os próprios clientes, e um proxy-real-ip-cidr errado deixa qualquer um escolher o
próprio endereço. Mudá-las é decisão de quem é dono do cluster, e o chart
não define nenhuma delas. Para conferir o resultado, faça login a partir de um
endereço conhecido e olhe o ip do seu próprio evento auth.login.
A mesma borda esconde o esquema do navegador. Por padrão, o ingress-nginx sobrescreve o
X-Forwarded-Proto com o esquema da própria conexão, então um ingress sem TLS atrás de uma CDN diz
ao web que o navegador está em http quando não está. O web então define os cookies sem Secure
nem __Host- e imprime http:// no snippet do MCP e nos redirect URIs de SSO, e o orbit-api recusa
um redirect URI em http puro fora de localhost. Defina o publicUrl do chart com o endereço https que as pessoas
abrem (configuration.md), sem mudar nada no controller. Isso corrige o que o web diz ao navegador
e não criptografa nada: senhas, códigos de uso único e tokens de sessão atravessam em claro o trecho
entre a CDN e a origem até que a origem sirva TLS e a CDN o verifique (na Cloudflare, o modo de
criptografia Full (strict)).
O mesmo endereço é a chave dos limites por cliente. Quando o orbit-api não tem um
endereço de cliente confiável (compose, ou uma borda que não repassa nenhum), todo
visitante chega com o endereço do web, e o login recai nas esperas por nome de usuário
mais um único bucket compartilhado por todos os visitantes, para que as falhas de um
visitante não tranquem todos os outros do lado de fora (identity.md →
"O que uma recusa significa").
A linha do tempo de mudanças
A página de namespace e a página de serviço do APM têm, cada uma, a aba Mudanças: o que mudou no namespace (ou no
workload do serviço) na janela de tempo da página, da mudança mais nova para a mais antiga, e por qual ferramenta ou
usuário do Deck. O Kubernetes guarda eventos por cerca de uma hora (--event-ttl, 1h por padrão) e o histórico de um
alerta acaba quando ele é resolvido; por isso o orbit-api registra essas mudanças por conta própria, a partir do que
já observa, em um loop próprio no intervalo dos alertas (ORBIT_ALERTING_INTERVAL, 30 s). Um API server lento segura
esse loop, não as notificações de alerta: as leituras de gerenciadores de campos dividem um orçamento de 10 segundos por
ciclo, e depois dele a linha fica sem "quem".
| Tipo | Quando é registrado | Quem |
|---|---|---|
| Rollout | A revisão mais nova de ReplicaSet de um Deployment muda: um ReplicaSet novo, no instante da criação, ou um antigo trazido de volta por um rollback, no evento do controller de Deployment que o escalou a partir de 0. A linha traz a revisão, o ReplicaSet e, de cada contêiner, a imagem, os requests e os limits antes e depois. | O gerenciador de campos cuja escrita de spec.template é a mais nova nos 5 segundos antes desse instante, lido dos managedFields do Deployment. Uma entrada guarda só a última escrita da ferramenta e os campos que ela ainda possui, então uma escrita posterior pode esconder a anterior (um rollback que só removeu um campo não possui nada), e aí ninguém é nomeado. Nomes típicos: helm, argocd-controller, kubectl-set, kubectl-rollout, kubectl-client-side-apply. |
| Escala | O spec.replicas de um Deployment muda: uma linha por passo, cada uma no instante do evento ScalingReplicaSet do controller de Deployment. Com um rollout em andamento, os passos dele parecem uma escala; então a linha fica com a hora do evento SuccessfulRescale do HPA, se houver, ou com a do ciclo, com ~. Uma linha feita pelo HPA traz a mensagem desse evento. | O gerenciador que escreveu spec.replicas: kubectl, helm ou HPA, quando o controller manager escreveu e o evento do HPA explica. |
| Aviso | Eventos do tipo Warning de um mesmo namespace, motivo, workload e primeira palavra da mensagem (uma falha de Liveness não é uma de Readiness) são uma linha, não importa quantos eventos e objetos ela cubra. A linha vai para o disco quando abre, um minuto depois e, enquanto cresce, a cada 10 minutos: é esse o atraso máximo da aba em relação ao cluster. Uma revisão nova do workload ou uma hora fecham a linha, e o evento seguinte abre outra; assim uma falha crônica aparece hora a hora, e o que os pods de um rollout fazem nunca se mistura com o que veio antes. A linha guarda a mensagem mais recente, diz quantas vezes e nomeia o primeiro objeto, com quantos mais. | Ninguém. |
| Alerta | Um alerta crítico ou de aviso (warning) no namespace começa a disparar ou é resolvido. Alertas Info ficam de fora. | Ninguém. |
| Ação no Deck | Lida desta trilha quando a aba abre: escala, recursos, suspensão, execução imediata, reinício, rollback, terminal aberto, alerta reconhecido ou silenciado. Dry runs ficam de fora. | O usuário do Deck. |
Nada adivinha uma pessoa. A mudança feita por uma ferramenta traz o nome da ferramenta, uma mudança sem gerenciador de
campos por perto não traz nome nenhum, e uma mudança que o orbit-api escreveu diz "o Deck": a linha do próprio Deck ao
lado nomeia o usuário, para um papel com audit.read. A pessoa por trás de um job de CI ou de uma sessão de kubectl
está no log de auditoria do próprio cluster, que o orbit-api não lê. Sem audit.read, a aba deixa de fora as linhas do
Deck e o filtro delas, e o postmortem diz que elas não são visíveis para o papel. O primeiro ciclo num cluster faz o
inventário dos Deployments e dos alertas sem gravar (o que já existia antes de o registro começar não é mudança) e copia
os avisos que o Kubernetes ainda guarda; a aba informa desde quando registra. Uma mudança feita com o orbit-api fora do ar
ganha a linha no ciclo seguinte. Um desligamento grava o que as linhas abertas guardam e as salva; assim a próxima subida
segue contando e as contagens batem com as do cluster. Uma queda sem desligamento perde no máximo os últimos 10 minutos do
crescimento de uma linha, e um evento que cresceu com o orbit-api fora do ar conta uma vez.
Horários. A hora de uma linha é a do cluster: a criação de um ReplicaSet, o evento do controller, a escrita de um
gerenciador de campos. Quando o evento já se foi e nenhuma escrita data a mudança, como depois de uma queda longa ou num
Deployment movimentado (o Kubernetes junta eventos além de 10 parecidos em 10 minutos), a linha fica com a hora em que
um ciclo a viu, um rollback continua antes da revisão seguinte, e a hora aparece com ~ na
tela e no Markdown.
Limites. Um arquivo JSONL por dia UTC em ORBIT_DATA_DIR/changes/<cluster>/, guardado por 14 dias: os arquivos de
dias além disso são apagados na primeira gravação de cada dia. Um dia recebe no máximo 5.000 linhas, das quais no máximo
4.500 de avisos e no máximo 500 de avisos por namespace, não importa quantas gravações cada uma tenha levado, para que a
tempestade de um namespace deixe espaço para os outros e para rollouts, escalas e alertas. As gravações seguintes de uma
linha param quando o arquivo do dia chega a 5 MiB, e a linha fica com a última contagem. O que um dia cheio deixa de fora é
contado por namespace e registrado no log uma vez; a aba e o Markdown dizem quantas linhas. Um dia cheio ocupa no máximo
cerca de 12 MB, já que a mensagem de um evento é cortada em 1 KiB, então o pior caso de um cluster é cerca de 160 MB:
dimensione persistence.size com isso. Um
documento por cluster em changestate/ guarda o que o último ciclo viu. Uma leitura devolve no máximo 500 linhas, da
mais nova para a mais antiga, e os avisos mais antigos são os primeiros a ficar de fora, para que uma tempestade não
esconda os rollouts anteriores a ela. Os filtros contam antes desse corte, e a aba e o Markdown avisam quando houve corte.
Copiar como postmortem copia em Markdown as linhas que os filtros de tipo deixam, da mais antiga para a mais nova: um título com o escopo, a janela em UTC, uma nota sobre o que faltar, uma seção Impacto vazia, a linha do tempo como tabela (hora, tipo, objeto, o que mudou, com o último evento da linha e se ela começou antes da janela, quem), todas as ações no Deck da janela, como lista, e uma seção Causa vazia. O texto vindo do cluster é escapado: colado num rastreador, fica em uma célula, sem link nem imagem. Se o navegador recusar a área de transferência, a cópia diz que falhou. Nada abre sozinho, nenhum incidente é criado e nenhum modelo escreve nada disso.
Não é registrado: rollouts e escalas de StatefulSets e DaemonSets (as revisões deles ficam em ControllerRevisions, que o
orbit-api não observa), o que a aba informa; edições de ConfigMap e Secret; os eventos de objetos sem namespace, como
os nodes, e alertas sem namespace.
O que a trilha não é
- Não detecta adulteração. Os arquivos são JSONL simples num volume: quem consegue
escrever nele consegue editar o histórico. Para ter uma evidência que sobreviva a um
administrador, envie as linhas de log
auditpara um armazenamento append-only que você não administre a partir da mesma conta. - Não é um registro de leituras. Uma leitura bem-sucedida fica no log de requisições,
não na trilha; uma recusada vira
access.denied. - Não fica completa quando o volume se perde. Com
components.orbit-api.persistence.enableddesligado, o diretório é umemptyDir, e a trilha vai embora junto com o pod.
Para onde ir em seguida
- Os papéis e as permissões que todo
access.deniedcita:identity.md. - A rota, os parâmetros e os erros dela na referência:
api.md. - Backups, dimensionamento da retenção e o que monitorar com alertas:
operations.md.