No primeiro dia útil de cada mês alguém da tua equipa entra na plataforma de sensibilização, descarrega um ficheiro, cola-o numa folha de cálculo e monta o diapositivo que a comissão executiva vai ver. Depois repete a operação com as outras ferramentas do stack. O trabalho fica bem feito e o número que chega acima está correto. Faz-se uma vez por mês porque fazê-lo custa uma manhã inteira.
Esse esforço não se explica por falta de dados. Os dados estão lá, cada plataforma tem-nos e mostra-os no seu próprio painel. O que falta é a porta por onde saem sem que ninguém os carregue à mão.
Lidero a equipa de engenharia da SMARTFENSE e, nas conversas técnicas com clientes, essa porta quase nunca aparece como um pedido de API. Aparece como o relatório mensal sem a manhã de trabalho, a ativação que dispara sozinha quando entra uma pessoa nova, a evidência pronta no dia em que o auditor liga. A API da plataforma é o que está por baixo dos três pedidos.
O que significa um programa de sensibilização ter API?
A API de uma plataforma de sensibilização é a interface que permite que outro sistema consulte e altere os dados do programa sem passar pelo ecrã. Onde uma pessoa entra e clica, um programa faz uma chamada e recebe o mesmo dado em formato JSON.
Dito assim soa a detalhe de implementação, mas há quatro decisões de desenho que mudam bastante o trabalho de quem a vai consumir.
É REST sobre HTTPS obrigatório, o desenho que qualquer equipa de sistemas já sabe consumir sem formação prévia. Devolve JSON, por isso o resultado entra diretamente numa ferramenta de BI sem camada de transformação intermédia. As respostas são paginadas, detalhe que importa quando o cadastro tem vinte mil pessoas e a consulta não pode trazê-las todas de uma vez. E as datas viajam em UTC com formato ISO 8601, que é o que permite comparar o resultado de uma campanha no México com o de uma em Espanha sem discutir a que horas começou cada uma.
Nenhuma das quatro é exótica. São as que fazem com que a integração seja terminada pela equipa de sistemas do cliente, em vez de se transformar num projeto com a nossa equipa do outro lado.
Que dados saem do programa e para onde?
Há cinco áreas de dados disponíveis e convém olhar para elas pelo que resolvem, não pelo nome.
Os resultados de campanhas e ações de sensibilização são a matéria-prima do relatório, o que hoje sai como ficheiro descarregado. A pontuação de risco é o valor por pessoa, grupo e organização que a plataforma já calcula e mostra como mapa de calor nos seus relatórios. A gestão de utilizadores e organização é o cadastro, com as entradas, as saídas e a estrutura de áreas. A auditoria e rastreabilidade é o registo de ações, o que o auditor pede. E os conteúdos são o inventário do que está publicado e atribuído.
O destino habitual destas cinco áreas são três sistemas que a organização já tem. A ferramenta de BI, onde o dado do programa se junta ao resto dos indicadores em vez de viver num painel à parte. O SIEM ou o GRC, que somam o risco por pessoa à telemetria que já processam. E o repositório de evidência, que deixa de se encher com capturas de ecrã.
Vale a pena marcar a direção, porque é o ponto onde se confundem duas conversas diferentes. Quando escrevi sobre construir a pontuação de risco humano com sinais do SIEM, o fluxo ia para dentro, a telemetria entrava no cálculo. Aqui o fluxo vai para fora, o resultado do programa sai para os sistemas da organização. São duas integrações distintas, e contratam-se e autorizam-se em separado.
Que tarefas deixam de depender de uma pessoa?
Estas são as cinco que aparecem primeiro quando um cliente liga a API, ordenadas pela frequência com que nos são pedidas.
- O relatório periódico. O dado viaja sozinho para a ferramenta de BI e o relatório atualiza-se sem que ninguém o monte. É a manhã do fecho do mês que se recupera, e também o que torna viável levar três respostas concretas à comissão executiva no dia em que a comissão as pede, e não no dia que o calendário marca.
- A ativação e a desativação de colaboradores. O sistema de recursos humanos empurra o movimento e o cadastro do programa reflete-o. Quem entra recebe a sua formação desde o primeiro dia e quem sai deixa de a ter atribuída, sem que ninguém se tenha de lembrar.
- A evidência de conformidade. Em vez de reconstruir à mão quem completou o quê e quando, o repositório de evidência alimenta-se da fonte. É a mecânica que sustenta um painel de conformidade que se atualiza em tempo real em vez de uma fotografia trimestral.
- A pontuação de risco dentro do painel de segurança. O valor por pessoa chega ao SIEM ou ao GRC e cruza-se com o resto dos sinais, sem que a equipa de segurança tenha de abrir outra ferramenta para o consultar.
- A consolidação entre organizações. Quando o programa está repartido por várias organizações, cada uma com a sua administração, a API é o que permite ler o conjunto sem entrar uma a uma.
O padrão das cinco é o mesmo. A plataforma continua a fazer o mesmo e muda quem o dispara. Cada uma é uma tarefa que hoje tem dono, calendário e risco de esquecimento, e que passa a executar-se sozinha.
Como se autoriza uma integração sem abrir a plataforma a mais?
Ligar dois sistemas é a parte fácil. Que essa ligação seja segura depende de três perguntas, e nenhuma obriga a entrar na especificação.
Em nome de quem atua a integração? Há dois modos. Um é o do processo automático que corre de madrugada sem ninguém por trás e tem identidade própria. O outro é o de uma aplicação que atua em nome de uma pessoa concreta e herda as permissões dela. Confundi-los sai caro. Um processo automático que corre com as credenciais de um administrador humano transforma essa conta numa conta partilhada, e no dia em que a pessoa deixa a organização ninguém sabe o que parte ao desativá-la.
Quanto pode tocar? O OAuth 2.0, a norma em que assenta a autenticação, permite limitar cada integração a uma permissão mínima, o seu scope. O sistema que monta o relatório mensal pode ficar limitado a ler resultados e não tocar no cadastro de pessoas. É a diferença entre dar acesso ao arquivo inteiro e dá-lo a uma só gaveta. Poder fazê-lo não significa que se faça, porque a via cómoda é sempre conceder permissão total e seguir. Dois dos dez principais riscos de segurança em APIs publicados pela OWASP são, precisamente, falhas de permissões.
O que fica registado? Toda a chamada de uma integração é uma ação sobre dados dos teus colaboradores. Se o registo de auditoria não permitir reconstruir que sistema consultou o quê e quando, tens um acesso que ninguém pode rever depois. Convém perguntá-lo antes de assinar.
Quando convém a API e quando basta o que já está integrado?
Esta é a parte que um fornecedor costuma saltar e é a que mais tempo poupa.
Boa parte do que um cliente julga ter de programar já está resolvido no catálogo de integrações e configura-se sem escrever código. A autenticação delega-se no fornecedor de identidade com SAML 2.0, LDAP, Microsoft Entra ID, Google ou Auth0, e o fluxo completo está contado em como funciona a integração SSO de ponta a ponta. A entrega por Slack ou Microsoft Teams, o envio da formação para o Moodle, a ligação com o SAP SuccessFactors ou com o Vanta têm o seu próprio conector.
A API entra onde o catálogo não chega, e isso quase sempre é o que é próprio de cada organização: a tua ferramenta de BI, o teu fluxo interno de integração de novos colaboradores, o teu GRC, o cruzamento de resultados com um dado que só existe nos teus sistemas.
A regra prática que uso nessas conversas é simples. Se o sistema do outro lado é um produto conhecido do mercado, procura primeiro o conector. Se o sistema do outro lado é teu, é aí que entra a API. E nos dois casos a ligação acontece entre servidores, sem instalar nada no equipamento de cada colaborador, que é a razão pela qual nos integramos por API e não por agente.
Perguntas frequentes
O que é a API de uma plataforma de sensibilização?
É a interface que permite que outro sistema consulte e altere os dados do programa sem passar pelo ecrã. Onde uma pessoa entra e clica, um programa faz uma chamada e recebe o mesmo dado em formato JSON.
O que se pode automatizar com a API de um programa de sensibilização?
O relatório periódico para uma ferramenta de BI, a ativação e a desativação de colaboradores a partir do sistema de recursos humanos, a recolha de evidência de conformidade, o envio da pontuação de risco por pessoa para o SIEM ou o GRC, e a consolidação de resultados quando o programa está repartido por várias organizações.
Preciso da API para ligar o programa ao fornecedor de identidade?
Não. A autenticação resolve-se com os conectores do catálogo, como SAML 2.0, LDAP, Microsoft Entra ID, Google ou Auth0, que se configuram sem escrever código. A API serve para o que nenhum conector cobre, como a tua ferramenta interna de BI ou o teu fluxo próprio de integração de novos colaboradores.
Como se autoriza uma integração por API sem dar acessos a mais?
Com OAuth 2.0 e acesso por scopes. O scope delimita o que cada integração pode ler ou escrever, por isso o sistema que monta o relatório mensal pode ficar limitado à leitura de resultados sem tocar no cadastro de utilizadores.
Qual é a diferença entre integrar por API e instalar um agente?
A API liga-se aos sistemas da organização de servidor para servidor, sem instalar nem manter software no equipamento de cada colaborador. Não há componente para atualizar no endpoint nem superfície nova para administrar.
Se estás a avaliar como ligar o programa ao que já tens, a documentação da API e o catálogo de conectores estão públicos. Começar por aí costuma poupar a reunião em que se descobre que o conector já existia.
Deixe um comentário