A API REVIEWIT

01Em uma frase #sec_decf73bd

A API REVIEWIT expõe as campanhas, as decisões, as provas e o histórico de auditoria às suas próprias ferramentas — em leitura, sob uma identidade de máquina autenticada por certificado, e sem nunca permitir a tomada de uma decisão de revisão.

02O problema #sec_148ec0fa

Uma campanha de recertificação não vive sozinha. Os seus resultados interessam a outros sistemas: a ferramenta de governança de riscos que consolida os controlos, o SIEM que correlaciona os eventos de segurança, a ferramenta de decisão que acompanha os indicadores, a gestão de serviços que desencadeia as remediações.

Sem interface programática, estas trocas são feitas por exportações manuais: alguém descarrega um ficheiro, deposita-o algures, e repete-o no mês seguinte. Três defeitos daí resultam, todos conhecidos:

A frescura. Um painel de controlo alimentado à mão é falso na maioria das vezes.

A rastreabilidade. Um ficheiro que transita por uma caixa de correio não tem origem certa, nem garantia de completude.

O custo humano. O tempo gasto a transportar dados é tempo que não é gasto a examinar acessos.

03A abordagem #sec_63100d97

Lê-se tudo. Não se decide nada.

Esta é a regra fundadora da API, e é o pendant exacto do princípio que governa as superfícies de administração: o administrador não aprova nada.

Nenhuma decisão de revisão por API

É impossível certificar, revogar ou colocar uma excepção por chamada programática. Não é uma funcionalidade adiada para mais tarde: é uma exclusão de princípio.

Uma decisão de recertificação tira todo o seu valor da sua imputabilidade a uma pessoa que olhou, julgou, e que responde por ela. Uma decisão produzida por um script não tem autor — no melhor dos casos, tem um operador que lançou o script, o que não é a mesma coisa. Abrir esta porta seria permitir certificar um parque inteiro numa única requisição, e reduzir a zero o valor probatório de todas as outras decisões do sistema.

A API serve portanto para explorar os resultados do controlo, nunca para os fabricar.

A subscrição vem do token, nunca da chamada

Nenhuma chamada contém um parâmetro que designe o cliente, a subscrição ou o perímetro a interrogar. O perímetro é derivado da identidade do token apresentado.

A consequência é que não existe nenhuma requisição, mesmo malformada, mesmo maliciosa, que possa devolver os dados de outro cliente. Não nos protegemos de um erro de parâmetro: eliminamos o parâmetro.

A autenticação por certificado é obrigatória

Os sistemas chamadores não se autenticam com um segredo partilhado, mas com um certificado: assinam o seu pedido de token com a sua chave privada, que REVIEWIT verifica com a chave pública declarada.

A diferença é concreta. Um segredo partilhado é uma cadeia de caracteres: circula, é copiado num ficheiro de configuração, é encontrado num repositório de código, e uma vez divulgado é utilizável por qualquer pessoa. Uma chave privada nunca sai do sistema chamador — não há nada a interceptar.

04Como funciona #sec_ad3e5605

Os clientes API

Cada sistema autorizado a chamar a API é declarado como cliente, ligado a uma subscrição, com as suas próprias autorizações. A gestão é feita a partir do Subscription Manager, e a capacidade de abrir a API depende da edição subscrita.

Estes clientes são distintos das ligações que REVIEWIT utiliza para ir recolher os dados do cliente. São duas noções opostas — uma entra, a outra sai — e confundi-las seria o mesmo que um acesso de leitura à API herdar as autorizações de recolha.

As autorizações

Um cliente não recebe «a API»: recebe um conjunto de autorizações correspondentes aos domínios de que necessita. Um conector SIEM que só consome o histórico de auditoria não obtém acesso às provas assinadas.

A paginação é obrigatória

Todas as colecções são percorridas por cursor: cada resposta indica onde retomar. Não é um detalhe de conforto.

Uma paginação por número de página torna-se falsa assim que os dados se movem durante o percurso — alguns elementos são vistos duas vezes, outros nunca. Numa exportação de conformidade, isto significa uma prova incompleta sem que ninguém se aperceba. O cursor elimina esta classe de erro.

O contrato está fixo e verificado

A especificação da interface está bloqueada por um teste automatizado. Qualquer modificação não intencional do contrato — um campo renomeado, um tipo alterado, uma resposta cuja forma evolui — faz falhar a cadeia de integração antes da publicação.

É isto que permite comprometer-se com a estabilidade da interface: não é garantida por uma boa intenção, mas por um mecanismo que recusa a mudança acidental. As evoluções de rutura passam por uma nova versão.

05O que a API expõe #sec_0de57e12

Três pontos merecem ser detalhados.

As decisões são normalizadas. Os estados internos do produto são traduzidos para um vocabulário público estável e documentado. Uma evolução do funcionamento interno não quebra as integrações dos clientes.

As provas não são armazenadas. O certificado que atesta uma revisão é produzido no momento em que é solicitado, a partir dos dados da pista, e depois assinado eletronicamente. Nada é conservado antecipadamente. A consequência é importante: uma prova descarregada hoje reflete o estado verificável hoje, e não é um documento imutável cuja frescura se desconhece. Uma revisão não decidida não produz prova — produz uma recusa explícita.

A exportação de auditoria é concebida para o fluxo contínuo. Funciona avançando sobre um cursor e adota uma semântica protetora: enquanto os eventos saem, a posição seguinte é fornecida; quando não há nada de novo, nenhuma posição é devolvida e o consumidor mantém a sua. Um sistema de recolha que interroga todas as minutos nunca perde o seu lugar, mesmo que reinicie.

06O que vem a seguir #sec_45c04ae7

As notificações de saída basear-se-ão no mesmo mecanismo de saída que os e-mails do produto. Não é uma escolha de implementação trivial: garante que um webhook e uma notificação descrevem o mesmo evento, no mesmo momento, com as mesmas garantias de entrega — em vez de dois caminhos concorrentes que acabariam por divergir.

As escritas administrativas permitirão pilotar campanhas a partir de uma ferramenta terceira: criar, lançar, encerrar. Elas permanecerão estritamente administrativas.

A decisão de revisão, ela, nunca será exposta — em nenhuma versão.

07Um ponto aberto, assumido #sec_10c3ba42

Os quotas de consumo são parcialmente tratados. Uma limitação do débito instantâneo protege hoje o serviço, mas os quotas por período e por edição não são ainda arbitrados: é uma decisão comercial tanto quanto técnica, e está identificada como tal.

Este dossier menciona-o em vez de deixar acreditar numa cobertura completa.

08A reter #sec_9a930c7a

A API responde a uma demanda simples — os nossos dados de conformidade devem viver nas nossas ferramentas — sem ceder no que faz o valor do produto.

Está aberta em leitura sobre tudo o que o dispositivo produz, fechada sobre o que deve permanecer um ato humano. Autentica os seus chamadores por certificado, deriva o seu perímetro da sua identidade em vez de lhes pedir, pagina por cursor para nunca mentir sobre a completude, e garante o seu contrato por um teste em vez de uma promessa.

Uma integração nunca deve tornar-se um meio de fazer mais depressa o que o controlo exige que se faça com atenção.