La API REVIEWIT

01En una frase #sec_decf73bd

La API REVIEWIT expone las campañas, las decisiones, las pruebas y la pista de auditoría a sus propias herramientas, en lectura, bajo una identidad de máquina autenticada por certificado, y sin permitir nunca tomar una decisión de revisión.

02El problema #sec_148ec0fa

Una campaña de recertificación no vive sola. Sus resultados interesan a otros sistemas: la herramienta de gobernanza de riesgos que consolida los controles, el SIEM que correlaciona los eventos de seguridad, la herramienta de toma de decisiones que sigue los indicadores, la gestión de servicios que desencadena las remediaciones.

Sin interfaz programática, estos intercambios se realizan mediante exportaciones manuales: alguien descarga un archivo, lo deposita en algún lugar y lo vuelve a hacer al mes siguiente. De ello se derivan tres defectos, todos conocidos:

La frescura. Un panel de control alimentado a mano es falso la mayoría de las veces.

La trazabilidad. Un archivo que transita por un buzón de correo no tiene un origen cierto ni una garantía de integridad.

El coste humano. El tiempo empleado en transportar datos es tiempo que no se ha empleado en examinar los accesos.

03La decisión tomada #sec_63100d97

Se lee todo. No se decide nada.

Es la regla fundacional de la API, y es el contrapunto exacto del principio que rige las superficies de administración: el administrador no aprueba nada.

Ninguna decisión de revisión por API

Es imposible certificar, revocar o plantear una excepción mediante una llamada programática. No se trata de una funcionalidad aplazada para más adelante: es una exclusión de principio.

Una decisión de recertificación obtiene todo su valor de su imputabilidad a una persona que ha mirado, juzgado y respondido. Una decisión producida por un script no tiene autor; en el mejor de los casos, tiene un operador que ha iniciado el script, lo que no es lo mismo. Abrir esta puerta equivaldría a permitir certificar todo un parque en una sola solicitud y reducir a cero el valor probatoria de todas las demás decisiones del sistema.

Por tanto, la API sirve para explotar los resultados del control, nunca para fabricarlos.

La suscripción proviene del token, nunca de la llamada

Ninguna llamada contiene un parámetro que designe al cliente, la suscripción o el ámbito a consultar. El ámbito se deriva de la identidad del token presentado.

La consecuencia es que no existe ninguna solicitud, por mal formada o malintencionada que sea, que pueda devolver los datos de otro cliente. No se protege de un error de parámetro: se elimina el parámetro.

La autenticación por certificado es obligatoria

Los sistemas llamantes no se autentican con un secreto compartido, sino con un certificado: firman su solicitud de token con su clave privada, que REVIEWIT verifica con la clave pública declarada.

La diferencia es concreta. Un secreto compartido es una cadena de caracteres: circula, se copia en un archivo de configuración, se encuentra en un repositorio de código y, una vez divulgado, puede ser utilizado por cualquier persona. Una clave privada nunca abandona el sistema llamante; no hay nada que interceptar.

04Cómo funciona #sec_ad3e5605

Los clientes API

Cada sistema autorizado a llamar a la API se declara como cliente, adscrito a una suscripción, con sus propias autorizaciones. La gestión se realiza desde el Subscription Manager, y la capacidad de abrir la API depende de la edición suscrita.

Estos clientes son distintos de las conexiones que REVIEWIT utiliza para recopilar datos del cliente. Son dos nociones opuestas (una entra, la otra sale) y confundirlas equivaldría a que un acceso de lectura a la API heredara las autorizaciones de recopilación.

Las autorizaciones

Un cliente no recibe «la API»: recibe un conjunto de autorizaciones correspondientes a los dominios que necesita. Un conector SIEM que solo consume la pista de auditoría no obtiene acceso a las pruebas firmadas.

La paginación es obligatoria

Todas las colecciones se recorren mediante cursor: cada respuesta indica dónde reanudar. No se trata de un detalle de comodidad.

Una paginación por número de página se vuelve falsa en cuanto los datos se mueven durante el recorrido; algunos elementos se ven dos veces, otros nunca. En una exportación de conformidad, esto significa una prueba incompleta sin que nadie se dé cuenta. El cursor elimina esta clase de error.

El contrato está fijo y verificado

La especificación de la interfaz está bloqueada por una prueba automatizada. Cualquier modificación no intencionada del contrato (un campo renombrado, un tipo cambiado, una respuesta cuya forma evoluciona) hace fallar la cadena de integración antes de la publicación.

Esto permite comprometerse con la estabilidad de la interfaz: no está garantizada por una buena intención, sino por un mecanismo que rechaza el cambio accidental. Las evoluciones disruptivas pasan por una nueva versión.

05Lo que expone la API #sec_0de57e12

Tres puntos merecen ser detallados.

Las decisiones están normalizadas. Los estados internos del producto se traducen en un vocabulario público estable y documentado. Una evolución del funcionamiento interno no rompe las integraciones de los clientes.

Las pruebas no se almacenan. El certificado que atestigua una revisión se produce en el momento en que se solicita, a partir de los datos de la pista, y luego se firma electrónicamente. No se conserva nada por adelantado. La consecuencia es importante: una prueba descargada hoy refleja el estado verificable hoy y no es un documento fijo del que se desconoce la frescura. Una revisión no decidida no produce una prueba; produce una denegación explícita.

La exportación de auditoría está diseñada para el flujo continuo. Funciona avanzando sobre un cursor y adopta una semántica protectora: mientras salgan eventos, se proporciona la posición siguiente; cuando no haya nada nuevo, no se devuelve ninguna posición y el consumidor conserva la suya. Un sistema de recopilación que consulta cada minuto no pierde nunca su lugar, aunque se reinicie.

06Lo que viene a continuación #sec_45c04ae7

Las notificaciones salientes se basarán en el mismo mecanismo de salida que los correos electrónicos del producto. No se trata de una elección de implementación baladí: garantiza que un webhook y una notificación describan el mismo evento, al mismo tiempo, con las mismas garantías de entrega, en lugar de dos caminos concurrentes que acabarían divergiendo.

Las escrituras administrativas permitirán controlar las campañas desde una herramienta de terceros: crear, lanzar, cerrar. Seguirán siendo estrictamente administrativas.

La decisión de revisión, por su parte, nunca se expondrá, en ninguna versión.

07Un punto abierto, asumido #sec_10c3ba42

Los cupos de consumo se tratan parcialmente. Una limitación del caudal instantáneo protege hoy el servicio, pero los cupos por período y por edición aún no están arbitrados: es una decisión comercial tanto como técnica, y se identifica como tal.

Este dossier lo menciona en lugar de dar a entender una cobertura completa.

08A tener en cuenta #sec_9a930c7a

La API responde a una demanda simple —nuestros datos de conformidad deben vivir en nuestras herramientas— sin ceder en lo que hace el valor del producto.

Está abierta en lectura sobre todo lo que el dispositivo produce, cerrada sobre lo que debe seguir siendo un acto humano. Autentica a sus llamadores por certificado, deriva su perímetro de su identidad en lugar de pedírselo, pagina por cursor para nunca mentir sobre la completitud, y garantiza su contrato por una prueba en lugar de por una promesa.

Una integración nunca debe convertirse en un medio para hacer más rápido lo que el control exige que se haga con atención.