Capítulo 31 — Segurança de TO, IoT e sistemas ciberfísicos: implementação II
Mapa da aula
Aula 31 publicada. Mapa, exemplo, EX091.
flowchart TD
N0["31.1 Upsert"]
N1["31.2 Validar na escrita"]
N2["31.3 Versionamento da API"]
N3["Nota prática"]
N4["31.1b Atualizações parciais e concorrência"]
N5["Nota de campo — incidente de importação em massa"]
N6["Síntese"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6
N6 --> EX["Exemplo resolvido"]
EX --> Q["Exercício EX091"]
Desenho lógico
flowchart LR
N0["31.1 Upsert"]
N1["31.2 Validar na escrita"]
N2["31.3 Versionamento da API"]
N3["Nota prática"]
N4["31.1b Atualizações parciais e concorrência"]
N5["Nota de campo — incidente de importação em massa"]
N6["Síntese"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> Q["EX091"]
[31.1 Upsert]
|
v
[31.2 Validar na escrita]
|
v
[31.3 Versionamento da API]
|
v
[Nota prática]
|
v
[31.1b Atualizações parciais e concorrência]
|
v
[Nota de campo — incidente de importação em massa]
|
v
[Síntese]
|
v
[Exemplo resolvido] --> [Exercício EX091]
Objetivos de aprendizagem
Você vai (1) acrescentar upserts idempotentes de constatações; (2) impor validação de esquema na escrita; (3) versionar as respostas das APIs das ferramentas do CNHP.
31.1 Upsert
A API de constatações do CNHP recebe PUT /findings/{id} com o corpo completo, então o mesmo id enviado duas vezes gera uma linha.
Na ABP, os ids das constatações vêm do cliente na criação e são reutilizados em cada nova tentativa, então uma falha de rede no meio do pedido não pode criar uma duplicata. As impressões digitais sugerem quando duas constatações podem ser o mesmo problema, mas uma pessoa confirma qualquer fusão, porque duas constatações no PLC-A podem compartilhar um registrador e ainda ter causas diferentes. As fusões são registradas com os motivos.
31.2 Validar na escrita
Rejeite campos desconhecidos e nomes proibidos; force a severidade por um enum. Os erros de validação retornam códigos legíveis por máquina.
O repositório de constatações de Lena na ABP rejeita qualquer registro com um campo desconhecido ou um nome proibido, como payload ou password, e retorna um código dizendo qual campo falhou. A severidade aceita apenas os valores acordados. O mesmo validador roda para as criações interativas e para as importações em massa, então nenhum caminho de entrada é mais confiável do que outro, e uma importação de scanner que envia risk_score é recusada com o mesmo código que o cliente móvel. Os erros são documentados com exemplos.
31.3 Versionamento da API
Prefixo /v1/; apenas mudanças aditivas dentro da v1. Mudanças incompatíveis exigem /v2/ e uma nota de migração.
Caso sintético — Ashford Batch Plant. Um cliente móvel enviou risk_score; o validador o rejeitou — as pontuações vazias ficam de fora (Capítulo 15).
A API de Lena para a ABP continua na v1 até agora. Lena publica a regra das mudanças aditivas na documentação da API, e a integração contínua compara cada novo esquema com a última versão para pegar campos removidos ou renomeados. Se algum dia uma mudança incompatível se tornar necessária, a v1 continuará rodando ao lado da v2 por um período anunciado, para que os clientes móveis e as importações de scanners possam migrar sem falhar no meio de uma janela.
31.4 Erros e limites
As chaves de idempotência não podem ser derivadas apenas do relógio.
Uma chave de idempotência construída a partir da hora atual muda entre as tentativas, então cada nova tentativa parece um pedido novo e cria uma duplicata. Os clientes de Lena geram a chave uma vez por operação lógica, guardam-na com o pedido pendente e a reutilizam até que o servidor confirme o sucesso. A regra é documentada com a API, e as bibliotecas cliente a impõem, para que desenvolvedores individuais não possam reintroduzir o atalho baseado no tempo. As revisões conferem essa regra explicitamente.
Nota prática
A importação em massa de scanners precisa passar pela mesma validação de esquema que a criação interativa, incluindo as verificações de campos proibidos.
31.1b Atualizações parciais e concorrência
Um PATCH que permite mudar a severidade sem referências de evidência convida a rebaixamentos silenciosos. Para as constatações do CNHP, prefira o PUT completo do corpo validado, ou um PATCH restrito que não possa limpar os hashes das capturas do monitor. Use ETags para que dois responsáveis pela remediação não sobrescrevam um ao outro.
Uma mudança de status para encerrado só é aceita quando o mesmo pedido traz um ponteiro de novo teste. Exclusões em massa são proibidas sem controle duplo. Documente a semântica do upsert no OpenAPI, para que os clientes móveis não inventem ids de nova tentativa.
ETags são obrigatórias em toda atualização de constatação.
Nota de campo — incidente de importação em massa
Um caminho de importação de scanner pulava as verificações de campos proibidos porque era considerado confiável. O campo de notas de alguém continha uma senha. Depois da limpeza e da troca da senha, a importação em massa foi religada pelo mesmo validador da criação interativa. A importação "confiável" é como os payloads entram em repositórios lacrados.
Clientes que omitem o id da constatação na criação recebem 400 com um link para a documentação do upsert, para que as novas tentativas não inventem duplicatas por acidente.
31.5 Exemplo resolvido — upsert idempotente de registros de ativos (ABP sintética)
Duas fontes de inventário relatam o PLC-A: a exportação do projeto de engenharia e a descoberta passiva na rede. O upsert de Lena usa como chave (site, etiqueta do ativo), e não o endereço IP, porque o IP muda quando um controlador é substituído. Cada escrita traz a fonte e um horário de observação; uma observação posterior só atualiza a versão de firmware se a sua fonte for a autoridade para esse campo (a exportação do projeto vence para o firmware; a descoberta vence para "visto pela última vez"). Reproduzir a mesma importação duas vezes não produz mudança — é o teste que prova a idempotência. Sem essas regras, uma importação em massa certa vez sobrescreveu o campo de firmware do PLC-A com "unknown" e o escondeu de uma verificação de avisos de segurança.
Exercícios
- EX091 — Upsert. Por que um POST sem id é arriscado para as novas tentativas? Rubrica: 3 = duplicatas na nova tentativa; 2 = vago; 1 = errado; 0 = nada.
- EX092 — Rejeitar. Corpo JSON que precisa receber 400. Rubrica: 3 = contém payload/password/risk_score; 2 = fraco; 1 = corpo válido; 0 = nada.
- EX093 — Versão. Renomear reason_code para reason é uma mudança segura na v1? Rubrica: 3 = não, incompatível, vai para a v2; 2 = hesitante; 1 = sim; 0 = nada.
Síntese
Escritas idempotentes, esquema estrito, versões explícitas.
Continue estudando — capítulo 31 de 50
← Capítulo 30 · Índice de capítulos do curso · Capítulo 32 →
Siga para a próxima lição escrita.