Capítulo 16 — Documentação técnica e segurança

Capítulo 16 — Documentação técnica e segurança

Mapa da aula

Aula 16 publicada. Mapa, exemplo, EX061.

flowchart TD
  N0["16.1 Runbooks que funcionam"]
  N1["16.2 Documentar sem segredos"]
  N2["16.3 Segurança em produção"]
  N3["Síntese"]
  N0 --> N1 --> N2 --> N3
  N3 --> EX["Exemplo resolvido"]
  EX --> Q["Exercício EX061"]

Desenho lógico

flowchart LR
  N0["16.1 Runbooks que funcionam"]
  N1["16.2 Documentar sem segredos"]
  N2["16.3 Segurança em produção"]
  N3["Síntese"]
  N0 --> N1 --> N2 --> N3 --> Q["EX061"]

[16.1 Runbooks que funcionam]
    |
    v
[16.2 Documentar sem segredos]
    |
    v
[16.3 Segurança em produção]
    |
    v
[Síntese]
    |
    v
[Exemplo resolvido] --> [Exercício EX061]

Objetivos de aprendizagem

Você vai (1) escrever runbooks que outro técnico consiga seguir; (2) documentar as configurações criptográficas sem expor segredos; (3) aplicar regras de segurança ao trabalho em produção.

16.1 Runbooks que funcionam

O primeiro runbook de Tomás, para renovar o certificado do host de transferência de arquivos, pressupunha conhecimentos que só ele tinha. Priya pede que um colega o siga, e o colega para no passo três. Tomás o reescreve com pré-requisitos, comandos exatos, saídas esperadas, uma verificação depois de cada passo e uma seção de reversão. Ele acrescenta quem chamar se um passo falhar. Um runbook é testado por outra pessoa que o usa, e não pelo autor relendo-o. Bons runbooks transformam a experiência de uma pessoa numa capacidade da equipe e encurtam as indisponibilidades às três da manhã.

16.2 Documentar sem segredos

A documentação precisa descrever onde os segredos ficam sem contê-los. Tomás escreve que o segredo dos callbacks de pagamento está guardado no cofre sob um caminho nomeado, acessível à svc-portal, rotacionado a cada 180 dias, em vez de escrever o segredo. Ele documenta abertamente as configurações de TLS, os perfis de certificado e os tamanhos de chave, porque eles não são secretos, e o princípio de Kerckhoffs diz que um sistema deve continuar seguro mesmo quando seu projeto é público. Ele revisa cada documento com uma busca por padrões que pareçam chaves ou senhas antes de publicá-lo na wiki da equipe.

16.3 Segurança em produção

As regras de segurança de Priya para o trabalho criptográfico em produção são curtas: ter uma mudança aprovada, uma reversão testada e uma segunda pessoa disponível; nunca desativar a verificação para restaurar o serviço; nunca mover chaves privadas por e-mail, chat ou mídia removível; e parar e escalar se aparecer algo inesperado. Tomás acrescenta sua própria regra: anunciar o trabalho no canal de operações antes de começar e ao terminar. Essas regras existem porque erros criptográficos podem bloquear todos os usuários de uma só vez, e um processo calmo e conferido evita que um pequeno erro se torne uma indisponibilidade em toda a empresa.

Exemplo resolvido

Tomás reescreve o runbook de renovação depois do teste de um colega, documenta o segredo dos callbacks apenas pelo caminho no cofre e lista as regras de segurança em produção no topo.

Caso sintético. Os passos do runbook e os caminhos no cofre são sintéticos.

Erros e limites

Os runbooks envelhecem à medida que os sistemas mudam; revise-os depois de cada uso. Os scanners de segredos deixam passar formatos incomuns.

Exercícios

• EX061 — Teste do runbook. Como um runbook é testado corretamente? Rubrica: 3 = alguém que não o autor o segue e relata as lacunas;; 2 = um colega segue;; 1 = o autor relê;; 0 = nenhuma.

• EX062 — Kerckhoffs. Por que as configurações de TLS e os tamanhos de chave podem ser documentados abertamente? Rubrica: 3 = a segurança deve repousar nas chaves, e não no sigilo do projeto (Kerckhoffs);; 2 = nomeia o princípio;; 1 = configurações secretas;; 0 = nenhuma.

• EX063 — Referência ao segredo. Como o runbook deve se referir ao segredo dos callbacks? Rubrica: 3 = pelo caminho no cofre, pela conta que o acessa e pelo período de rotação, nunca pelo valor;; 2 = caminho;; 1 = inclui o valor;; 0 = nenhuma.

• EX064 — Nunca restaurar com. Cite um atalho que as regras de segurança proíbem ao restaurar o serviço. Rubrica: 3 = desativar a verificação, ou mover chaves por e-mail ou chat;; 2 = um atalho;; 1 = vago;; 0 = nenhuma.

Síntese

A documentação torna as operações criptográficas repetíveis e seguras quando é testada por outros e descreve os segredos sem revelá-los.

Continue estudando — aula 16 (capítulo 16 de 18)

← Capítulo 15 · Índice das aulas · Capítulo 17 →

Continue para a próxima aula já escrita.