# FAQ

# Sobre o produto

# O que e o Tatuzim?

E uma camada de seguranca autonoma que entrega arquivos sensiveis (certificados, plugins, configs) entre um hub e VPS remotos com autenticidade verificavel. Foi pensado pra ser uma dependencia confiavel de outros sistemas, nao um produto fim em si.

# Por que nao usar Vault, AWS Secrets Manager ou similar?

Esses sistemas resolvem armazenamento de segredos. O Tatuzim resolve transporte e instalacao deles em VPS:

• Vault precisa de um agente que saiba se autenticar — o enrollment do Tatuzim resolve isso.
• O Tatuzim escreve artefatos em diretorios consumidos por outros processos (Traefik, Mautic, etc.) e roda hooks pra notificar — Vault nao faz isso nativo.
• O Tatuzim opera independente do resto do ecossistema: se o Vault cair, voce pode usar Tatuzim.

# Por que `step-ca` e nao Let's Encrypt?

Let's Encrypt e otimo pra certs publicos. Mas:

• Limita a 50 certs/semana por dominio
• Nao funciona pra hostnames internos (vps-01.internal)
• Nao tem hierarquia (root offline + intermediate online) que voce controla

step-ca da controle total da PKI privada e e operavel localmente.

# Operacao

# Posso rodar o CLI `tatuzim` enquanto o server esta rodando?

Nao. O vault tem um flock exclusivo — segundo processo recebe erro vault already locked. Pare o server, rode o CLI, reinicie.

Workaround pra evitar parar: use a API HTTP do server (planejado pra v0.2).

# Como inspecionar agentes registrados?

Com o server parado:

docker stop dev_tatuzim_server
docker run --rm --entrypoint /usr/local/bin/tatuzim \
    -v tatuzim_tatuzim_vault:/var/lib/tatuzim \
    -e TATUZIM_MASTER_PASSPHRASE=... \
    tatuzim-server:dev \
    agente list --root /var/lib/tatuzim
docker start dev_tatuzim_server

Ou montagem direta se voce roda o server bare-metal:

sudo systemctl stop tatuzim-server
sudo TATUZIM_MASTER_PASSPHRASE=... tatuzim agente list --root /var/lib/tatuzim
sudo systemctl start tatuzim-server

# O que acontece se eu perder a passphrase do vault?

O vault fica permanentemente inacessivel. Nao ha recuperacao — todos os agentes registrados, eventos e cargas se perdem.

Guarde a passphrase em password manager (Bitwarden) e em um envelope fisico selado.

# Como recuperar de comprometimento do hub?

Cenario: alguem pegou root no hub e tem acesso ao step-ca intermediate + vault.

1. Revogar o intermediate no step-ca root (offline) e gerar novo intermediate
2. Atualizar root CA pinada nos agents (deploy de nova versao do agent via self-update)
3. Revogar todos os tokens de enrollment vivos
4. Reenrollar agents com nova identidade
5. Auditar evento list --verify pra detectar adulteracao da chain

A root CA fica offline entao mesmo comprometimento do hub nao permite emitir certs com chain raiz.

# Seguranca

# O agent confia em qual CA?

O server cert (pra mTLS) e validado contra o root CA do step-ca, fornecido via TATUZIM_SERVER_CA_PATH no env do agent. Esse arquivo precisa ser copiado pro VPS no provisioning.

O agent nao confia em CAs do sistema operacional pra requests Tatuzim — so o root pinado.

# O que protege o `vault.lock` contra processo desonesto?

Nada — flock e advisory, nao mandatorio. Um processo que ignore o lock pode mexer no db.plain e corromper. A protecao real e:

1. Permissoes 0700 no diretorio do vault (so o user do server pode entrar)
2. Server roda como user dedicado (tatuzim no caso do .deb)
3. Codigo do Tatuzim (CLI + server) sempre adquire o lock

Isso e suficiente quando voce controla todo o software que toca o vault. Nao protege contra acesso root malicioso — pra isso, encriptacao at-rest (que ja temos) e a defesa.

# O que protege a chave privada de release minisign?

Atualmente: arquivo 0600 no servidor de dev (passwordless). Se o servidor de dev for comprometido, atacante pode assinar binarios maliciosos que self-update vai aceitar.

Mitigacao planejada: mover pro Cofre (storage criptografado dedicado). Ate la, e debito tecnico documentado.

# Como sei se um evento foi adulterado?

Cada evento contem hash_atual = SHA256(hash_anterior || payload || timestamp). O comando tatuzim evento list --verify recomputa toda a chain e reporta Hash chain: VALID ou BROKEN.

Pra protecao stronger, periodicamente publique o hash_atual mais recente em um sistema externo imutavel (S3 com object lock, blockchain, etc.) — assim atacante que controle o vault inteiro nao consegue reescrever a chain sem voce notar.

# Desenvolvimento

# Posso contribuir?

O Tatuzim e MVP interno por agora. Nao aceitamos contribuicoes externas ate a v0.4.

# Como rodar os testes?

cd /proj/tatuzim/server
cargo test          # 27 unit tests
bash tests/server_e2e.sh
bash tests/mtls_e2e.sh
# ... ver tests/ pra lista completa

Todos os E2E precisam:

• step-ca container rodando (docker compose up -d step-ca)
• certs/root_ca.pem extraido

# Onde reportar bugs?

Abra issue em https://github.com/devborlot/tatuzim/issues