Capítulo 16 — Documentação técnica e segurança
Mapa da aula
Aula 16 publicada. Mapa, exemplo, EX061.
flowchart TD
N0["16.1 Documentação de controles"]
N1["16.2 Runbooks"]
N2["16.3 Segurança em serviços em produção"]
N3["16.4 Registros de mudanças"]
N4["16.6b Revisando os documentos com periodicidade"]
N5["Síntese"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5
N5 --> EX["Exemplo resolvido"]
EX --> Q["Exercício EX061"]
Desenho lógico
flowchart LR
N0["16.1 Documentação de controles"]
N1["16.2 Runbooks"]
N2["16.3 Segurança em serviços em produção"]
N3["16.4 Registros de mudanças"]
N4["16.6b Revisando os documentos com periodicidade"]
N5["Síntese"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> Q["EX061"]
[16.1 Documentação de controles]
|
v
[16.2 Runbooks]
|
v
[16.3 Segurança em serviços em produção]
|
v
[16.4 Registros de mudanças]
|
v
[16.6b Revisando os documentos com periodicidade]
|
v
[Síntese]
|
v
[Exemplo resolvido] --> [Exercício EX061]
Objetivos de aprendizagem
Você vai (1) escrever documentação técnica clara para controles de segurança de IA; (2) escrever runbooks para incidentes de IA; (3) seguir regras de segurança ao trabalhar em serviços em produção; (4) documentar mudanças e decisões.
16.1 Documentação de controles
Para cada controle: finalidade (que risco ele trata), onde é configurado, como é testado, quem é o responsável e limites conhecidos. Exemplo: "Verificação de titularidade nas reinicializações — impede reiniciar roteadores de outros clientes (LLM06). Configurada na política da ferramenta de roteador v2.1. Testes RST-N01–N30. Responsável: operações de serviço. Limite: não cobre reinicializações feitas pelo suporte telefônico." O exemplo mostra cada elemento cumprindo uma função. A finalidade liga o controle ao achado das reinicializações entre contas. O local da configuração diz ao próximo técnico onde procurar. O intervalo de testes RST-N01–N30 permite que qualquer pessoa reproduza a evidência. O responsável diz quem aprova as mudanças. O limite é a linha mais útil: a equipe do suporte telefônico reinicia roteadores por outro console, então esta verificação não protege esse caminho, e ninguém deve supor que proteja.
16.2 Runbooks
Cada tipo de incidente de IA precisa de um runbook: como é detectado; perguntas de triagem; etapas de contenção (desativar a ferramenta, remover o documento, limitar a taxa, reverter o prompt); evidências a preservar; quem notificar; recuperação; encerramento. Escreva as etapas como ações numeradas que uma pessoa cansada consiga seguir às 3 da manhã. Os runbooks da Kestrel acompanham os incidentes deste livro: conteúdo injetado provocando ações, dados divulgados numa resposta, uma divergência de hash em arquivo de modelo e um pico de consumo como o do fim de semana das 40.000 mensagens. Cada um começa por como o problema aparece, por exemplo um alerta noturno ou uma reclamação de cliente, e termina com uma etapa de encerramento que acrescenta um teste de regressão, como foi feito depois do artigo da restauração de fábrica.
16.3 Segurança em serviços em produção
Nunca rode testes de ataque contra clientes reais. Faça as mudanças nas janelas aprovadas, com um plano de reversão. Use verificação por duas pessoas para mudanças arriscadas. Na dúvida, pare e pergunte. Na Kestrel, o teste de reinicialização entre contas rodou apenas na homologação, com contas sintéticas, porque em produção reiniciaria os roteadores de clientes reais. As mudanças na política da ferramenta de reinicialização são feitas na janela de manutenção de terça-feira, com uma feature flag pronta para reverter. Mudar uma coleção de recuperação em produção exige que uma segunda pessoa confira a mudança antes de ela ser aplicada. A parada de Ana no teste do canário, quando viu que a ferramenta de chamados ainda apontava para uma fila real, é a última regra na prática.
16.4 Registros de mudanças
Registre cada mudança: o quê, por quê, quem aprovou, resultados dos testes, plano de reversão. Quando acontecem incidentes, os registros de mudanças costumam ser o caminho mais rápido até a causa.
"""Lab R: token-bucket limits against unbounded consumption (synthetic).
Simulates 60 seconds of requests from a normal client and a flooding client
against a model endpoint with a per-client token bucket."""
import random
rng = random.Random(4)
def simulate(rate_per_s, burst, reqs):
tokens, last, ok = burst, 0.0, 0
for t in reqs:
tokens = min(burst, tokens + (t - last) * rate_per_s); last = t
if tokens >= 1: tokens -= 1; ok += 1
return ok
normal = sorted(rng.uniform(0, 60) for _ in range(90))
flood = sorted(rng.uniform(0, 60) for _ in range(3000))
for rate, burst in ((5, 20), (2, 10), (1, 5)):
print(f"limit={rate}/s burst={burst:2d} normal_served={simulate(rate, burst, normal):3d}/90 "
f"flood_served={simulate(rate, burst, flood):4d}/3000")
Saída esperada:
limit=5/s burst=20 normal_served= 90/90 flood_served= 319/3000
limit=2/s burst=10 normal_served= 90/90 flood_served= 129/3000
limit=1/s burst= 5 normal_served= 62/90 flood_served= 64/3000
Na divergência de hash do LineWatch, o registro de implantação respondeu à pergunta em minutos: uma mudança aprovada, com o nome do aprovador, tinha substituído o modelo sem atualizar o manifesto. Sem esse registro, Ana teria precisado tratá-la como possível adulteração por muito mais tempo. Um registro de mudança para aumentar o limite de taxa do HelpBot informaria os valores antigos e novos, o motivo, o resultado do laboratório para os novos valores e como reverter.
16.5 Exemplo resolvido (caso sintético da Kestrel)
Ana escreve o runbook "Conteúdo injetado provocando ações". Etapa 1: confirmar pelos rastros qual documento foi recuperado. Etapa 2: desativar a coleção desse documento ou a ferramenta afetada por meio da feature flag. Etapa 3: exportar os rastros e o documento para o repositório de evidências. Etapa 4: avisar o líder de plantão e o responsável pelo conteúdo. Etapa 5: conferir nos registros das ferramentas as ações executadas e revertê-las. Etapa 6: reativar depois que o documento for corrigido e a bateria passar. Num exercício simulado, um colega que nunca tinha visto o HelpBot o segue em 12 minutos. O exercício também encontrou uma etapa pouco clara: a etapa 2 não dizia onde ficava a feature flag, então o runbook agora nomeia a flag e a página do console.
16.6 Erros e limites
Três erros são comuns: documentação escrita uma vez e nunca atualizada; runbooks que só o autor consegue seguir; e mudanças sem plano de reversão. Uma documentação escrita uma única vez descreve o HelpBot de antes da ferramenta de senha do Wi-Fi, e um técnico que a seguisse deixaria de ver o caminho mais recente até o roteador de um cliente. Um runbook que só o autor consegue seguir falha às 3 da manhã, quando o autor está dormindo; o exercício simulado, em que um colega novo no HelpBot terminou em 12 minutos, é o teste contra isso. Uma mudança sem plano de reversão transforma uma configuração ruim numa interrupção enquanto alguém descobre como desfazê-la.
16.6b Revisando os documentos com periodicidade
Os runbooks do HelpBot e do SpamShield têm uma data de revisão. Um runbook com a data vencida é sinalizado na reunião semanal da equipe e conferido com o sistema atual; etapas desatualizadas num serviço em produção são um risco de segurança, não apenas desleixo. A data de revisão do runbook de conteúdo injetado foi antecipada quando a ferramenta de senha do Wi-Fi foi acrescentada, porque a etapa 5, conferir nos registros das ferramentas as ações executadas, precisava incluir o registro da nova ferramenta. Um runbook que mencionasse apenas reinicializações e chamados a teria deixado de fora. A revisão do runbook de divergência de hash descobriu que ele ainda nomeava o caminho antigo do modelo do LineWatch.
Exercícios
- EX061 — Documentação de controle. Documente o controle de orçamento de tokens do HelpBot. Rubrica: 3 = finalidade, configuração, testes, responsável, limites; 2 = quatro; 1 = dois; 0 = nenhum.
- EX062 — Runbook. Escreva um runbook para "dados de cliente divulgados numa resposta". Rubrica: 3 = detecção, triagem, contenção, evidências, notificação, recuperação, encerramento; 2 = cinco; 1 = três; 0 = nenhum.
- EX063 — Segurança. Liste quatro regras de segurança para trabalhar em serviços de IA em produção. Rubrica: 3 = quatro pertinentes; 2 = três; 1 = uma ou duas; 0 = nenhuma.
- EX064 — Registro de mudança. Escreva um registro de mudança para o aumento do limite de taxa. Rubrica: 3 = o quê, por quê, aprovação, testes, reversão; 2 = quatro; 1 = dois; 0 = nenhum.
Síntese
Boa documentação, runbooks testados e práticas de trabalho seguras tornam os controles de segurança de IA mantíveis por pessoas que não são seus autores.
Continue estudando — capítulo 16 de 18
← Capítulo 15 (rascunho) · Índice de capítulos do curso · Capítulo 17 (rascunho) →