Capítulo 8 — Programação II

Mapa da aula

Aula 08 publicada. Mapa, exemplo, EX022.

flowchart TD
  N0["8.1 Módulos"]
  N1["8.2 Validar na escrita"]
  N2["8.3 Versionamento de API"]
  N3["8.4 Atualizações parciais"]
  N4["8.5 Importação em lote"]
  N5["8.6 Concorrência"]
  N6["8.7 Nota aplicada"]
  N7["8.8 Exercícios de migração"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
  N7 --> EX["Exemplo resolvido"]
  EX --> Q["Exercício EX022"]

Desenho lógico

flowchart LR
  N0["8.1 Módulos"]
  N1["8.2 Validar na escrita"]
  N2["8.3 Versionamento de API"]
  N3["8.4 Atualizações parciais"]
  N4["8.5 Importação em lote"]
  N5["8.6 Concorrência"]
  N6["8.7 Nota aplicada"]
  N7["8.8 Exercícios de migração"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX022"]

[8.1 Módulos]
    |
    v
[8.2 Validar na escrita]
    |
    v
[8.3 Versionamento de API]
    |
    v
[8.4 Atualizações parciais]
    |
    v
[8.5 Importação em lote]
    |
    v
[8.6 Concorrência]
    |
    v
[8.7 Nota aplicada]
    |
    v
[8.8 Exercícios de migração]
    |
    v
[Exemplo resolvido] --> [Exercício EX022]

Objetivos de aprendizagem

Você vai (1) estruturar módulos para a plataforma; (2) validar entradas; (3) versionar APIs com cuidado.

8.1 Módulos

Carregador de escopo, esquema de achados, exportador de relatórios — cada um com testes e um README. Dividir a plataforma dessa forma permite que cada parte falhe e seja testada por conta própria. Os testes do carregador de escopo o alimentam com a /26 sintética com o SWIFT em .20 e verificam que a exclusão sobrevive a todo formato de entrada. Os testes do esquema de achados rejeitam registros sem campos obrigatórios. Os testes do exportador comparam os relatórios gerados com arquivos esperados salvos. Cada README declara o que o módulo faz, o que ele se recusa a fazer e quem revisa as mudanças nele.

8.2 Validar na escrita

O FindingsDesk rejeita tickets sem dono ou sem hash de evidência. Rejeitar tickets incompletos no momento da escrita é mais barato do que persegui-los depois. Um achado sem dono não tem ninguém para corrigi-lo, e um achado sem hash de evidência não pode ser conferido contra o arquivo que afirma descrever. A validação de Sam retorna uma mensagem que nomeia o campo ausente, para que um analista possa corrigir o ticket imediatamente em vez de adivinhar por que ele falhou. O FindingsDesk aplica a mesma regra de campos obrigatórios às importações em lote e às chamadas de API, de modo que nenhuma das vias pode criar um achado sem dono.

8.3 Versionamento de API

O PulseMap v2 acrescenta campos sem quebrar os consumidores da v1. Os consumidores existentes do PulseMap, como a exportação mensal para o conselho, leem campos da v1 e precisam continuar funcionando quando aparecem campos novos, como IDs de técnica por cartão de método. Acrescentar campos é seguro; renomeá-los ou removê-los é uma mudança incompatível que exige uma nova versão e um período de migração. Os testes de contrato de Sam rodam o consumidor da v1 contra o servidor da v2 em todo build, para que uma quebra acidental falhe na CI, e não no próximo material do conselho.

8.4 Atualizações parciais

Um PATCH não pode limpar campos obrigatórios por acidente. Um cliente que envia apenas uma severidade alterada não pode apagar o dono ou o hash de evidência por omissão. O FindingsDesk trata o PATCH como "alterar apenas estes campos" e roda novamente a validação sobre o registro mesclado, de modo que uma atualização parcial não consegue produzir um ticket que teria sido rejeitado na criação. Os testes de Sam enviam requisições PATCH com um campo de cada vez e confirmam que todos os outros campos obrigatórios sobrevivem inalterados. A mesma regra protege o hash de evidência durante edições em lote.

8.5 Importação em lote

A importação de achados por CSV faz primeiro um dry-run e limita o número de linhas. Um dry-run mostra o que a importação criaria, atualizaria ou rejeitaria, incluindo qualquer host fora do escopo do TRB, antes que qualquer coisa seja escrita. O limite de linhas restringe o dano que um arquivo errado pode causar, e a próxima nota aplicada mostra por que os dois limites existem. Só depois que um analista revisa o resumo do dry-run a importação real roda, e o resumo é anexado ao registro da importação. O resumo do dry-run lista cada linha rejeitada com seu motivo, como um host fora do escopo do TRB, para que o analista possa corrigir o arquivo.

8.6 Concorrência

O bloqueio otimista impede que dois analistas sobrescrevam silenciosamente o mesmo ticket. Cada ticket carrega um número de versão. Quando um analista salva, o FindingsDesk confere que a versão não mudou desde que o ticket foi aberto; se um colega salvou primeiro, o segundo salvamento é recusado e o analista vê as duas versões. Sem isso, a mudança de severidade de um analista poderia apagar silenciosamente a nova evidência de outro, e ninguém saberia qual visão do achado era a atual. O analista recusado mescla as duas versões à mão, e a mesclagem é registrada.

8.7 Nota aplicada

A importação em lote tem teto de 500 linhas e exige um segundo aprovador acima de 100. Sam viu um analista quase importar um dump de scanner que incluía hosts fora do escopo como "informativos". Tetos e aprovadores são chatos de propósito. Um host fora do escopo "informativo" ainda é evidência de que alguém testou fora das ROE; por isso, ele precisa de revisão, não de armazenamento silencioso. O segundo aprovador confere o resumo do dry-run contra o escopo assinado antes que importações maiores prossigam. O aprovador nunca é a pessoa que rodou a varredura, para que a verificação seja independente.

8.8 Exercícios de migração

As migrações de esquema rodam numa cópia, com checksums antes e depois. Sam registra a contagem de linhas. Uma migração que muda as contagens silenciosamente reprova no exercício. Checksums e contagens de linhas na cópia mostram se uma migração preservou todo achado e toda referência de evidência. Se as contagens diferem, a migração é corrigida e rodada de novo numa cópia nova; a produção nunca é usada como teste. Sam guarda os números de antes e depois com o script de migração, para que um revisor possa confirmar que o exercício passou.

8.9 Escritas idempotentes

As atualizações de tickets são idempotentes por id do achado. Entregas duplicadas vindas de redes instáveis não conseguem criar F1s duplicados. Como cada atualização é indexada pelo ID do achado, aplicar a mesma requisição duas vezes deixa o ticket no mesmo estado que aplicá-la uma vez. Isso importa no TRB, onde os links de VPN para a zona de avaliação caem com frequência, e achados duplicados inflariam as contagens nos relatórios ao conselho.

As atualizações idempotentes de tickets salvaram o TRB quando uma VPN instável reenviou doze vezes a mesma chamada de criação de achado. O FindingsDesk mostrou um F1, não doze. Sam acrescenta essa história ao onboarding para que os engenheiros parem de temer o "exatamente uma vez" como algo acadêmico. Doze tickets F1 duplicados teriam mostrado ao conselho doze achados críticos abertos e acionado o dono doze vezes. A idempotência tornou a falha de rede inofensiva, que é exatamente o que os engenheiros precisam ver antes de confiar no desenho. Os engenheiros novos agora testam as novas tentativas na primeira semana.

8.10 Dry-run da importação em lote

O dry-run da importação em lote do FindingsDesk certa vez revelou 40 hosts fora das ROE embutidos num CSV de scanner. A importação foi bloqueada. Na retrospectiva, Sam agradece mais ao dry-run do que a qualquer funcionalidade nova lançada naquele mês. Quarenta hosts fora do escopo num banco de dados de avaliação teriam parecido resultados de testes autorizados e poderiam ter motivado trabalho de acompanhamento contra sistemas que ninguém havia aprovado. O dry-run transformou um problema silencioso de dados numa decisão visível, e a configuração do scanner que produziu o CSV foi corrigida antes da janela seguinte.

8.11 Limiar de aprovação de 100 linhas

O limiar de aprovação de 100 linhas do FindingsDesk existe porque um dump de 2.000 linhas certa vez ficou na fila durante a noite e disparou uma tempestade de alertas para os donos. Sam documenta o id do incidente ao lado da constante no código. Ligar a constante ao registro do incidente diz aos futuros engenheiros por que o limiar existe antes que decidam aumentá-lo. Sem o comentário, 100 parece arbitrário e convida à remoção. Com ele, qualquer pessoa que mude o valor pode ler o que aconteceu quando importações grandes rodaram sem revisão e acionaram os donos a noite inteira. O comentário nomeia o ENG-441 e a data da mudança.

O id do incidente é ENG-441 no arquivo do curso. A entrada do arquivo descreve a fila noturna, quantos donos foram acionados e a mudança que introduziu o limiar de aprovação. Um revisor que encontra a constante pode seguir o link e julgar o histórico diretamente. A mesma prática vale para o teto de 500 linhas: todo limite de segurança do FindingsDesk aponta para o motivo pelo qual foi definido, de modo que os limites são mudados de forma deliberada, e não por alguém arrumando o código.

Exemplo resolvido (TRB sintético)

Sam acrescenta uma verificação ao FindingsDesk: um emergency_contact vazio nos metadados das ROE bloqueia o início do engajamento.

Caso sintético — Riverstone Transit Bank (TRB). O banco, Sam Ito, TrackScope/FindingsDesk/PulseMap e todos os números são inventados para fins didáticos.

Erros e limites

Este livro não concede nenhuma autoridade para testar bancos ou sistemas de pagamento reais. Os laboratórios usam apenas endereços de faixas de documentação e dados sintéticos; código de exploit nunca é fornecido.

Exercícios

• EX022 — Regra de rejeição. Nomeie dois campos que devem bloquear a criação do ticket se estiverem vazios.
  Mostrar critérios de avaliação

  Rubrica: 3 = dois entre dono, hash de evidência, severidade; 2 = um; 1 = cor do título; 0 = nada.
• EX023 — Importação com dry-run. Por que fazer dry-run de uma importação em lote?
  Mostrar critérios de avaliação

  Rubrica: 3 = pegar erros de esquema antes da escrita; 2 = parcial; 1 = não precisa; 0 = nada.
• EX024 — Bloqueio otimista. Que problema o bloqueio otimista evita?
  Mostrar critérios de avaliação

  Rubrica: 3 = sobrescrita silenciosa de edições concorrentes; 2 = parcial; 1 = interface lenta; 0 = nada.

Síntese

O código da plataforma valida, versiona e se recusa a iniciar engajamentos inseguros.

Continue estudando — capítulo 08 de 40

← Capítulo 07 (rascunho) · Índice de capítulos do curso · Capítulo 09 (rascunho) →