Pular para o conteúdo

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çãoQuando
auth.loginUm login deu certo.
auth.login_failedUm login foi recusado: senha errada, nome de usuário desconhecido, conta desativada ou uma espera ainda em andamento.
auth.logoutUma sessão foi encerrada pelo próprio dono.
auth.setupO primeiro administrador foi criado com o código de configuração, ou alguém tentou um código errado.
auth.password_changeAlguém trocou a própria senha, ou digitou errado a senha atual.
user.createUm 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.updateO nome ou o e-mail de um usuário mudou, ou vários campos mudaram de uma vez.
user.role_change, user.disable, user.enableMudou exatamente aquele único campo.
user.password_reset, user.mfa_resetUma 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_sessionsUma conta foi removida, ou todas as sessões dela foram encerradas.
role.create, role.update, role.deleteUm papel personalizado mudou.
dashboard.create, dashboard.update, dashboard.deleteUm dashboard salvo mudou.
alert.ack, alert.unack, alert.silence, alert.unsilenceO reconhecimento ou o silenciamento de um alerta mudou.
workload.scale, workload.resources, workload.rollback, workload.restartToda 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.resultComo terminou o rollout de um rollback aplicado: outcome (completed, failed ou timeout), durationMs, updated, ready, desired.
access.deniedUm 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:

json
{
  "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 é null quando 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, alert ou workload.
  • outcome é success, denied (recusado por uma regra: uma permissão, uma espera, uma conta desativada) ou failure (tentado e malsucedido: uma senha errada, um erro do API server).
  • details guarda o before e o after de 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:

TermoCasa com
actor:graceO nome de usuário do autor
action:user.*A ação
outcome:deniedsuccess, denied ou failure
ip:10.0.*O endereço do cliente
target:checkoutParte 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"):

bash
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/audit

A 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:

bash
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/audit

Colunas: 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çãoWEB_TRUST_PROXYO que o ip mostra
HelmDerivado: true quando ingress.enabled, false caso contrárioO cliente como o ingress o viu
Manifestos purostrue (o 60-ingress.yaml é a borda)O cliente como o ingress o viu
Composefalse (o web é a borda)O endereço do contêiner do web, para todo visitante
Loop do k3dDerivado 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):

ChaveDefina comoPor 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-cidrAs 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-forDeixe "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 balancerPara 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".

TipoQuando é registradoQuem
RolloutA 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.
EscalaO 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.
AvisoEventos 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.
AlertaUm 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 DeckLida 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 audit para 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.enabled desligado, o diretório é um emptyDir, e a trilha vai embora junto com o pod.

Para onde ir em seguida

  • Os papéis e as permissões que todo access.denied cita: 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.