Tutorial: Auditar a integridade do vault (DPO/Encarregado)¶

Neste tutorial você vai percorrer, passo a passo, os procedimentos de auditoria do vault do Anotae: localizar o arquivo, verificar a integridade dos backups, inspecionar a cadeia de hash do log de auditoria e produzir um relatório para auditores externos.

O que você vai construir: um relatório textual de auditoria cobrindo integridade criptográfica, log de eventos e cifra em repouso — adequado para apresentar ao Encarregado de Dados (DPO) da unidade de saúde ou a um auditor externo no contexto LGPD.

Tempo estimado: 20 minutos.

Pré-requisitos¶

Anotae instalado (versão ≥ v0.11)
Acesso ao terminal (macOS: Terminal.app ou iTerm2; Linux: qualquer emulador; Windows: PowerShell ou Prompt de Comando)
Senha-mestra do vault disponível — você precisará dela para desbloquear o vault durante a verificação
Permissão de leitura na pasta ~/.anotae/ (normalmente o próprio profissional ou o administrador local do sistema)

Nota de privacidade: este tutorial utiliza apenas caminhos e saídas fictícias. Nunca copie dados reais de pacientes para documentos de trabalho. O vault cifrado pode ser inspecionado estruturalmente sem expor conteúdo clínico.

Passo 1: Localizar o vault¶

Por padrão, o Anotae armazena todos os dados em um único arquivo SQLite cifrado:

~/.anotae/vault.db

No terminal, confirme que o arquivo existe:

ls -lh ~/.anotae/vault.db

Saída esperada (exemplo fictício):

-rw------- 1 dra.silva dra.silva 2,1M mai 19 08:34 /home/dra.silva/.anotae/vault.db

Observe as permissões rw------- (600): somente o proprietário tem acesso de leitura e escrita. Isso é configurado automaticamente pelo Anotae na criação do vault.

Inspecione também a pasta completa:

ls -lh ~/.anotae/

Saída esperada (exemplo fictício):

drwx------ 2 dra.silva dra.silva 4,0K mai 19 08:34 backups/
-rw------- 1 dra.silva dra.silva 2,1M mai 19 08:34 vault.db
-rw------- 1 dra.silva dra.silva  512 mai 19 08:34 vault.db-shm
-rw------- 1 dra.silva dra.silva  24K mai 19 08:34 vault.db-wal

O que são os arquivos -shm e -wal? São arquivos auxiliares do SQLite em modo WAL (Write-Ahead Log), usados para garantir atomicidade das transações. São igualmente cifrados pelo SQLite3 Multiple Ciphers. Nunca os apague manualmente enquanto o Anotae estiver aberto.

Passo 2: Listar os backups disponíveis¶

O Anotae cria backups automáticos do vault. Para listar todos os backups registrados:

anotae backup list ~/.anotae/vault.db

Saída esperada (exemplo fictício):

Backups registrados para: /home/dra.silva/.anotae/vault.db
─────────────────────────────────────────────────────────────────────
  #  Data/Hora (UTC)          Tamanho   Status     Caminho
─────────────────────────────────────────────────────────────────────
  1  2026-05-01 03:00:00      2,0 MB    OK         backups/vault-20260501T030000Z.db
  2  2026-05-08 03:00:00      2,0 MB    OK         backups/vault-20260508T030000Z.db
  3  2026-05-15 03:00:00      2,1 MB    OK         backups/vault-20260515T030000Z.db
  4  2026-05-19 03:00:00      2,1 MB    OK         backups/vault-20260519T030000Z.db
─────────────────────────────────────────────────────────────────────
Total: 4 backups  |  Retenção configurada: 90 dias

Anote o número de backups e as datas — eles entrarão no relatório final.

Passo 3: Verificar a integridade de um backup¶

Para verificar a integridade criptográfica de um backup específico:

anotae backup verify ~/.anotae/backups/vault-20260519T030000Z.db

O comando faz três verificações em sequência:

Hash SHA-256 do arquivo — compara com o digest registrado no momento do backup.
Abertura cifrada — tenta abrir o arquivo com a chave derivada da sua senha-mestra, confirmando que o conteúdo não foi corrompido.
Verificação da cadeia de auditoria — percorre o log de auditoria interno e valida cada elo da cadeia de hash.

Você será solicitado a informar a senha-mestra:

Senha-mestra do vault: ████████████

Saída esperada em caso de sucesso (exemplo fictício):

Verificando: backups/vault-20260519T030000Z.db
  [✓] SHA-256 do arquivo     a3f9c1d2e5b7...  (corresponde ao registro)
  [✓] Decifragem             ChaCha20-Poly1305 OK — 847 páginas verificadas
  [✓] Cadeia de auditoria    312 entradas  |  último hash: 9e4a02b1...
Resultado: ÍNTEGRO

Se alguma verificação falhar, o Anotae exibe uma mensagem como:

  [✗] SHA-256 do arquivo     DIVERGÊNCIA DETECTADA
      Registrado:  a3f9c1d2e5b7...
      Calculado:   ff00deadbeef...
Resultado: FALHA — possível corrupção ou adulteração

O que fazer em caso de falha? Não use o backup comprometido. Reporte imediatamente ao responsável técnico da unidade e preserve o arquivo para perícia. Consulte docs/explanation/auditoria-checklist.md para o procedimento de incidente.

Passo 4: Inspecionar a cadeia de hash do log de auditoria¶

O log de auditoria do Anotae é append-only e usa uma cadeia de SHA-256: cada entrada armazena o hash da entrada anterior, formando uma corrente que torna qualquer adulteração retroativa matematicamente detectável.

Para inspecionar as últimas entradas do log, use o subcomando de auditoria:

anotae backup verify ~/.anotae/vault.db --audit-log --last 10

Saída esperada (exemplo fictício — sem dados clínicos reais):

Log de auditoria — últimas 10 entradas
─────────────────────────────────────────────────────────────────────────────
  Seq   Data/Hora (UTC)       Ação          Entidade       Hash do elo
─────────────────────────────────────────────────────────────────────────────
  303   2026-05-19 07:42:11   CREATE        encounter      4d3a1f…→ 9e4a02b1
  302   2026-05-19 07:41:58   UPDATE        encounter      c1b209…→ 4d3a1f
  301   2026-05-19 07:38:03   CREATE        encounter      a8f7c0…→ c1b209
  300   2026-05-18 16:22:45   DELETE        encounter      5b3e91…→ a8f7c0
  299   2026-05-18 16:21:30   CREATE        patient        09de72…→ 5b3e91
  ...
─────────────────────────────────────────────────────────────────────────────
  [✓] Cadeia íntegra: 312/312 elos verificados

Como ler a coluna "Hash do elo"? O formato HASH_ANTERIOR → HASH_DESTA_ENTRADA mostra que cada registro incorpora o digest do registro imediatamente anterior. Se qualquer entrada for excluída ou modificada, todos os hashes subsequentes se tornam inválidos — o que o verificador detecta automaticamente.

Note que a coluna Entidade mostra apenas o tipo de registro (encounter, patient) e nunca o conteúdo clínico, que permanece cifrado em repouso.

Passo 5: Entender a cifra em repouso¶

O Anotae utiliza dois níveis de proteção:

Nível 1 — Cifra de página (vault inteiro)¶

Todo o arquivo vault.db é cifrado com ChaCha20-Poly1305 via SQLite3 Multiple Ciphers. A chave é derivada da senha-mestra usando Argon2id com os parâmetros:

Parâmetro	Valor padrão	Valor fallback (hardware modesto)
Memória (`m`)	64 MiB	19 MiB
Iterações (`t`)	3	2
Paralelismo (`p`)	1	1

Sem a senha-mestra, o arquivo é opaco — não há chave de recuperação armazenada remotamente.

Nível 2 — Cifra em campo (dados clínicos)¶

A partir da Migration 010 (hardening P0.1), todos os campos clínicos sensíveis (subjetivo, objetivo, avaliacao, plano, notas) são adicionalmente cifrados em nível de coluna antes de serem gravados no banco.

O que está em texto claro no banco (após abrir o vault)?

Campo	Cifrado?	Motivo
`id` (UUID)	Não	Necessário para JOINs
`patient_id` (UUID)	Não	Referência relacional
`created_at`, `updated_at`	Não	Metadados de ordenação
`subjetivo`, `objetivo`, `avaliacao`, `plano`	Sim	Conteúdo clínico
`ciap2_codes`, `cid10_codes`	Sim	Códigos diagnósticos
`audit_log.action`	Não	Necessário para verificação da cadeia
`audit_log.entity_hash`	Não	Hash (não reverte ao conteúdo)

Para a arquitetura completa de criptografia, consulte docs/CRYPTO-DESIGN.md.

Passo 6: Gerar o relatório de auditoria¶

Para produzir um relatório estruturado pronto para apresentação externa:

anotae backup verify ~/.anotae/vault.db --report > relatorio-auditoria-$(date +%Y%m%d).txt

O arquivo gerado conterá (exemplo fictício):

======================================================
RELATÓRIO DE AUDITORIA — ANOTAE VAULT
======================================================
Data/hora da auditoria  : 2026-05-19 09:15:42 UTC
Versão do Anotae        : v0.15-3
Vault auditado          : /home/dra.silva/.anotae/vault.db
Auditado por            : [identificação do DPO — preencher manualmente]
------------------------------------------------------
INTEGRIDADE DO ARQUIVO
  SHA-256               : a3f9c1d2e5b7084f...
  Resultado             : ÍNTEGRO

CIFRA EM REPOUSO
  Algoritmo             : ChaCha20-Poly1305
  KDF                   : Argon2id (m=64 MiB, t=3, p=1)
  Migration de campo    : 010 (P0.1 hardening)
  Resultado             : ATIVO

LOG DE AUDITORIA
  Total de entradas     : 312
  Período               : 2026-04-01 → 2026-05-19
  Cadeia de hash        : ÍNTEGRA (312/312 elos)
  Último hash           : 9e4a02b1c3d4e5f6...

BACKUPS
  Total registrados     : 4
  Backup mais recente   : 2026-05-19 03:00:00 UTC — ÍNTEGRO
  Retenção              : 90 dias

CONFORMIDADE
  Sem dados exportados para servidores externos
  Sem telemetria ativa sem opt-in
  Cifra em repouso ativa em todos os campos clínicos
======================================================

Edite o arquivo gerado para incluir:

Identificação do DPO/Encarregado responsável pela auditoria
Identificação da unidade de saúde (CNES)
Observações sobre o contexto da auditoria (rotina periódica, incidente, etc.)
Assinatura digital ou manuscrita conforme exigido pela instituição

Referências e próximos passos¶

Checklist completo de auditoria (41 ameaças mapeadas): docs/explanation/auditoria-checklist.md
Arquitetura criptográfica detalhada: docs/CRYPTO-DESIGN.md
Avaliação de impacto à privacidade (RIPD/LGPD): docs/PRIVACY-IMPACT-ASSESSMENT.md
Modelo de ameaças: docs/THREAT-MODEL.md
Como criar e restaurar backups: docs/how-to/backup-restaurar.md (how-to)

O que aprendemos¶

Ao final deste tutorial você aprendeu a:

Localizar o vault cifrado e verificar suas permissões de sistema de arquivos.
Listar backups registrados com anotae backup list.
Verificar a integridade de um backup com anotae backup verify, confirmando hash SHA-256, decifragem e cadeia de auditoria.
Inspecionar o log de auditoria append-only e entender o que a cadeia de hash garante: qualquer adulteração retroativa é matematicamente detectável.
Compreender os dois níveis de cifra em repouso (página e campo) e identificar quais colunas estão em texto claro.
Gerar um relatório estruturado para auditores externos.

Compliance LGPD: o Encarregado (DPO) deve executar esta auditoria periodicamente (recomendado: trimestral) e arquivar os relatórios pelo prazo exigido pela política de retenção da instituição. O Anotae não transmite dados para servidores externos em nenhuma circunstância — toda a auditoria ocorre localmente, sem necessidade de rede.