/v1/governance:
- Mapeos de actores: vinculan IDs de actor opacos con PII, con operaciones de seudonimización y eliminación.
- Archivos: listan los archivos completados de registros de auditoría y descargan objetos archivados desde el almacenamiento de objetos.
- Registros de auditoría: historial solo por adición encadenado por hash, con una verificación de integridad de solo lectura.
Toda ruta de gobernanza permanece dentro del tenant del llamador. Las lecturas de mapeos de actores tienen dos niveles de autorización: el listado, que omite
displayName y email, y la lectura de de-anonimización de un solo registro. Esta separación mantiene la resolución de identidad aparte del acceso de exploración.Mapeos de actores
Un mapeo de actor vincula un
actorId opaco (por ejemplo, user:550e8400-e29b-41d4-a716-446655440000) con PII legible por humanos (displayName, email). Matcher cifra displayName y email antes de almacenarlos y nunca los almacena en texto plano.
Las filas del listado omiten los campos de PII del mapeo (displayName, email) por diseño, pero sí devuelven el propio actorId. En el upsert, Matcher recorta los espacios en blanco iniciales y finales, y rechaza IDs vacíos o compuestos solo por espacios en blanco, así como IDs de más de 255 caracteres. Matcher no impone un formato de ID opaco ni oculta el valor. Un actorId que en sí mismo contiene PII, como una dirección de correo electrónico, aparece en las filas del listado con su valor almacenado. La seudonimización conserva ese valor. Usa identificadores opacos si el acceso al listado debe permanecer libre de PII.
El GET de un solo registro devuelve la identidad en texto plano y requiere el permiso deanonymize. Los registros de auditoría pueden conservar el actorId sin procesar, que puede ser una dirección de correo electrónico.
Lista los mapeos de actores
Filas paginadas por cursor que omitendisplayName y email. Filtra por un prefijo de ID de actor.
actorId (filtro de prefijo), limit (25 de forma predeterminada, con un máximo de 100) y cursor.
Crea o actualiza un mapeo de actor
Crea o actualiza la PII de un ID de actor.PUT es idempotente. La misma llamada crea el registro en el primer uso y lo actualiza después. Proporciona al menos uno de displayName o email.
Obtén un mapeo de actor (de-anonimizar)
Devuelve la PII en texto plano de un único ID de actor. Esta es la operación primitiva de de-anonimización, por lo que el permiso más restringidodeanonymize la controla en lugar de una lectura simple.
Seudonimiza
ReemplazadisplayName y email del mapeo con [REDACTED], conservando el registro y su vínculo de actorId. Esto elimina la PII solo del mapeo. Los registros de auditoría inmutables conservan el actorId sin procesar de la escritura original, y ese valor puede ser en sí mismo una dirección de correo electrónico. Los registros de auditoría históricos y los archivos archivados conservan sus valores originales. Responde 204 No Content.
Elimina un mapeo
Elimina el mapeo de forma permanente. Responde204 No Content.
Seudonimizar conserva el registro y elimina su PII. Eliminar borra el registro por completo. Elige seudonimizar cuando debas conservar el vínculo de auditoría, y eliminar cuando el registro en sí no deba persistir.
Archivos
Cuando Lerian habilita el archivado de auditoría en tu entorno, Matcher exporta al almacenamiento de objetos cada partición mensual de registros de auditoría más antigua que el período de retención que define Lerian. Verifica la exportación y luego elimina la partición de la base de datos.
Lista los archivos
Paginado por desplazamiento. Filtra por rango de fechas.from, to (YYYY-MM-DD o RFC 3339), limit (1–200, 20 de forma predeterminada) y offset. El endpoint lista solo los archivos COMPLETE y nunca muestra archivos en curso o fallidos. checksum es el SHA-256 en hexadecimal del contenido JSONL descomprimido, así que descomprime un archivo descargado antes de calcular el hash.
Descarga un archivo
Devuelve una URL prefirmada junto con la suma de verificación para la verificación de integridad.Para descargar solo archivos completados, toma los IDs de archivo del endpoint de listado, que devuelve solo archivos
COMPLETE.Registros de auditoría
Matcher registra los cambios de configuración y las resoluciones de excepciones como registros de auditoría solo por adición por tenant. Vincula cada registro en una cadena de hash SHA-256 (
recordHash = SHA-256(prevHash || canonical content)). Usa el endpoint de verificación que se muestra abajo para obtener el veredicto de integridad.
Lista los registros de auditoría
Paginado por cursor, con filtros completos.actor, action, entity_type, date_from, date_to (YYYY-MM-DD o RFC 3339), limit (1–200, 20 de forma predeterminada) y cursor.
actor filtra por el valor actorId del registro. Ese valor es el identificador de actor sin procesar de la escritura original, una dirección de correo electrónico en este ejemplo. Los registros de auditoría almacenan el identificador tal cual. No tiene que coincidir con el actorId de un mapeo de actor.
Cuando una diferencia es demasiado grande para conservarla completa, changes lleva un envoltorio marcador de truncamiento en lugar de la diferencia completa, y truncated pasa a true, mientras originalSize indica el tamaño en bytes antes del truncamiento.
Verifica la cadena de auditoría
Vuelve a verificar que cada registro inspeccionado coincida con su hash almacenado. La verificación recorre un tramo contiguo con un límitemaxRecords, por lo que intact solo da fe de ese tramo inspeccionado. En el endpoint HTTP, un maxRecords proporcionado debe estar en el rango 1–10,000, y un valor fuera de ese rango devuelve 422. Cuando lo omites, Matcher usa el valor predeterminado de 10,000 registros.
De forma predeterminada, la verificación empieza en la secuencia almacenada más baja. Para empezar en un registro posterior, envía el fromSeq opcional: el primer tenantSeq que se inspecciona, un entero igual o mayor que 1. Cuando el primer registro que lee la verificación no es la secuencia 1, la verificación confía en el enlace almacenado de ese registro. No verifica los registros anteriores a él. La verificación permanece estrictamente de solo lectura.
intact es true cuando todo el tramo permanece intacto. Cuando la verificación encuentra una ruptura, firstBrokenSeq indica el tenantSeq del primer registro que falla, y verifiedCount indica cuántos registros se mantuvieron íntegros antes de ese punto. El campo truncated es true cuando la cadena contiene más registros de los que permitió el límite de inspección maxRecords.
La respuesta siempre trae fromSeq, el tenantSeq en el que empezó la verificación.
Obtén un registro de auditoría
También puedes listar el historial de una entidad directamente con
GET /v1/governance/entities/{entityType}/{entityId}/audit-logs (paginado por cursor), lo cual resulta útil cuando ya conoces la entidad que quieres auditar.