Capítulo 4 — Scripts e formatos de dados

Mapa da aula

Aula 04 publicada. Mapa, exemplo, EX010.

flowchart TD
  N0["4.1 Formatos"]
  N1["4.2 Atividade prática — Laboratório J"]
  N2["4.3 Desconhecido não é não"]
  N3["4.4 Scripts reexecutáveis"]
  N4["4.5 Caso resolvido"]
  N5["4.6 Atividade prática"]
  N6["4.8 Um pequeno exemplo em CSV"]
  N7["Síntese"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
  N7 --> EX["Exemplo resolvido"]
  EX --> Q["Exercício EX010"]

Desenho lógico

flowchart LR
  N0["4.1 Formatos"]
  N1["4.2 Atividade prática — Laboratório J"]
  N2["4.3 Desconhecido não é não"]
  N3["4.4 Scripts reexecutáveis"]
  N4["4.5 Caso resolvido"]
  N5["4.6 Atividade prática"]
  N6["4.8 Um pequeno exemplo em CSV"]
  N7["Síntese"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX010"]

[4.1 Formatos]
    |
    v
[4.2 Atividade prática — Laboratório J]
    |
    v
[4.3 Desconhecido não é não]
    |
    v
[4.4 Scripts reexecutáveis]
    |
    v
[4.5 Caso resolvido]
    |
    v
[4.6 Atividade prática]
    |
    v
[4.8 Um pequeno exemplo em CSV]
    |
    v
[Síntese]
    |
    v
[Exemplo resolvido] --> [Exercício EX010]

Objetivos de aprendizagem

Você vai (1) ler e escrever JSON e CSV em Python; (2) resumir exportações de inventário; (3) tratar valores ausentes como desconhecidos; e (4) escrever scripts que outras pessoas possam executar de novo.

4.1 Formatos

Os inventários chegam como JSON vindo de APIs e como CSV vindo de planilhas e scanners. Os módulos json e csv do Python leem ambos. Sempre verifique se os campos de que você precisa estão presentes e têm os tipos esperados.

No HHG, as exportações do scanner vêm em CSV e o inventário de endpoints em JSON. Confira a contagem de registros e os nomes dos campos antes de confiar em qualquer resumo. Se um campo estiver ausente ou tiver o tipo errado, pare e comunique, em vez de adivinhar.

4.2 Atividade prática — Laboratório J

# Lab J (ch 4): parse a synthetic JSON export of TLS endpoints and summarise key exchange by property.
import json, collections
export = json.loads("""[
 {"property": "harbour", "host": "pms-01", "group": "X25519MLKEM768"},
 {"property": "harbour", "host": "pos-02", "group": "secp256r1"},
 {"property": "summit",  "host": "pms-01", "group": "X25519"},
 {"property": "summit",  "host": "lock-hub", "group": null},
 {"property": "lakeside","host": "pms-01", "group": "X25519MLKEM768"}]""")
summary = collections.defaultdict(collections.Counter)
for e in export:
    g = e["group"]
    kind = "unknown" if g is None else ("hybrid" if "MLKEM" in g else "classical")
    summary[e["property"]][kind] += 1
for prop, c in sorted(summary.items()):
    print(f"{prop:9s} hybrid={c['hybrid']} classical={c['classical']} unknown={c['unknown']}")

Saída esperada:

harbour   hybrid=1 classical=1 unknown=0
lakeside  hybrid=1 classical=0 unknown=0
summit    hybrid=0 classical=1 unknown=1

O hub de fechaduras do Summit não tem grupo registrado. O script o conta como unknown (desconhecido), não como classical (clássico), porque ninguém o observou ainda.

O script lê uma exportação JSON, decide para cada endpoint se o seu grupo é híbrido, clássico ou desconhecido e conta os resultados por unidade. Repare que null vira desconhecido, não clássico, e que o híbrido é detectado pela parte MLKEM do nome. O PMS de Lakeside negocia híbrido, enquanto o do Summit não, o que dá uma primeira comparação entre unidades. Execute-o, depois acrescente um endpoint seu e verifique se as contagens mudam como esperado.

4.3 Desconhecido não é "não"

Tratar valores ausentes como resposta negativa faz os relatórios parecerem completos e esconde trabalho. Um desconhecido significa "descubra" e deve gerar uma tarefa: perguntar ao fornecedor, verificar a configuração ou observar o tráfego.

No HHG, o hub de fechaduras do Summit continua desconhecido até que o fornecedor das fechaduras responda ou o tráfego seja observado. Conte os desconhecidos separadamente em todo relatório, para que os leitores vejam quanto ainda falta descobrir. Dê a cada desconhecido um responsável e uma data, para que ele seja fechado em vez de ser carregado adiante.

4.4 Scripts reexecutáveis

Coloque o caminho de entrada e o formato de saída em argumentos, imprima o que foi lido (número de registros) e mantenha os scripts sob controle de versão com um README curto. Um script que outra pessoa consegue executar de novo no mês que vem vale muito mais do que um cálculo avulso.

Escreva o script para que ele falhe de forma ruidosa diante de entradas ruins, em vez de produzir um resumo errado. Inclua uma entrada de exemplo e a saída esperada, como fazem os laboratórios. Imprima os erros com clareza, nomeando o arquivo e a linha que os causaram.

4.5 Caso resolvido

Um operador recebe endpoints.csv de um scanner. O seu script conta híbridos, clássicos e desconhecidos por unidade, imprime o total de linhas lidas (48) e grava um pequeno CSV para o painel. Quando a saída do scanner ganha uma nova coluna no mês seguinte, o script continua funcionando porque lê as colunas pelo nome.

A contagem de linhas permite ao leitor verificar que nada foi descartado: se o scanner produziu 48 linhas, o resumo precisa dar conta das 48. Ler pelo nome, e não pela posição, foi o que tornou inofensiva a nova coluna.

4.6 Atividade prática

Modifique o Laboratório J para imprimir também a proporção de endpoints híbridos em todas as unidades.

Calcule a proporção como endpoints híbridos divididos por todos os endpoints, e também como híbridos divididos pelos endpoints com grupo conhecido, e imprima ambas com rótulos. Com os dados do Laboratório J, as respostas diferem por causa do hub de fechaduras do Summit. Explique em uma frase qual número pertence a um relatório e por quê. Mantenha a contagem de desconhecidos visível ao lado de ambos os números e teste o script com uma exportação vazia para garantir que ele não divide por zero.

4.7 Erros comuns e limites

• Ler colunas pela posição.
• Pular silenciosamente linhas com erros.
• Não imprimir quantos registros foram lidos.

Cada erro produz enganos silenciosos. Ler pela posição quebra assim que um scanner acrescenta uma coluna, como aconteceu no caso resolvido. Pular linhas ruins faz os totais parecerem completos quando não são, e as linhas puladas podem ser justamente as interessantes. Sem uma contagem de registros impressa, ninguém consegue verificar se o script leu o arquivo inteiro. Acrescente um teste para cada um aos seus scripts.

4.8 Um pequeno exemplo em CSV

A mesma ideia funciona com CSV. Leia com csv.DictReader, para que cada linha seja um dicionário indexado pelo nome da coluna; verifique se a coluna group existe antes do laço; e, para cada linha, decida entre híbrido, clássico ou desconhecido com a mesma regra do Laboratório J. Imprima as contagens e o número de linhas lidas, e grave cada linha que falhar na validação num arquivo separado para revisão, em vez de descartá-la. As linhas rejeitadas costumam ser as mais interessantes — um scanner que não conseguiu completar um handshake pode estar apontando exatamente para o problema de firewall que o Capítulo 13 ensina você a diagnosticar.

Quando entregar o script a um colega, inclua um arquivo de entrada de exemplo com algumas linhas sintéticas e a saída que ele deve produzir. Esse pequeno teste permite verificar que o script ainda funciona depois de alterado, do mesmo jeito que os laboratórios deste livro mostram a sua saída esperada.

Mantenha a regra de validação num único lugar do script.

Exercícios

• EX010 — Proporção. Que proporção dos endpoints do Laboratório J é híbrida? Rubrica: 3 = 2/5 = 40 %.
• EX011 — Validação. Nomeie três verificações que um script deve fazer em cada registro de inventário. Rubrica: 3 = campos obrigatórios, tipo/valores permitidos, duplicatas.
• EX012 — Tarefa para o desconhecido. Escreva a tarefa que você abriria para o hub de fechaduras do Summit. Rubrica: 3 = o que descobrir, como, responsável.

Síntese

Scripts simples, validados e reexecutáveis transformam exportações de inventário em resumos honestos, nos quais os desconhecidos viram tarefas.