> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/api-rest/identity-api/identity-api-reference/security-compliance/injection-attack-detection.md). # Injection Attack Detection (IAD) Esta API, en el contexto de captura y evaluación facial, permite la detección de: **Vectores de ataque:** cámaras virtuales, dispositivos externos, ataques de navegador, ataques de red. **Contenido de ataque:** renderizado 3D, morphing facial, face swap, cheap fake, deep fake. Esta API requiere la integración del lado del cliente de las bibliotecas de captura IAD. La biblioteca de captura IAD (incluida en **Selphi**) controla el proceso de captura en el cliente y genera el **IAD bundle** (paquete cifrado de metadatos e imágenes). La API sabe cómo desempaquetar el IAD bundle del cliente para realizar tanto la detección de ataques de inyección como la detección de ataques de presentación. ### Endpoint ``` POST /iad ``` ### Headers | Nombre | Tipo | Requerido | Descripción | | --------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **x-api-key** | string | **Sí** | API key de autorización de acceso. | | **OperationId** | string | No | Identificador de la operación en Plataforma V2. Si se envía junto con `SessionId`, se emite un evento de tracking en la pestaña de Seguridad del detalle de la operación. | | **SessionId** | string | No | Identificador de sesión asociado a la operación. Requerido para activar el tracking, salvo que se utilice `ExtraData`. | | **ExtraData** | string | No | Token cifrado que empaqueta `operationId` y `sessionId`. Alternativa a enviarlos por separado. | | **Family** | string | No | Familia del evento de tracking. Por defecto `ONBOARDING`. | ### Cuerpo de la solicitud **Content-Type:** `application/octet-stream` #### Parámetros | Parámetro | Tipo | Requerido | Descripción | | ------------ | ------ | --------- | ----------------------------------------------------------------------------------------------------------------------------- | | `IAD_BUNDLE` | binary | **Sí** | Paquete cifrado de metadatos e imágenes. El bundle debe ser enviado como una solicitud `application/octet-stream` en el body. | #### Ejemplo de solicitud ```bash curl --location '{IDENTITY_API_BASE_URL}/iad' \ --header 'x-api-key: {API_KEY}' \ --header 'Content-Type: application/octet-stream' \ --data 'IAD_BUNDLE' ``` ### Respuestas #### `200` Éxito #### Parámetros de respuesta | Parámetro | Tipo | Descripción | | --------- | ------- | ------------------------------------------------------------------------------------------------------------------ | | `attack` | boolean | Valor booleano que indica si se detectó un ataque. `true`: se detectó un ataque, `false`: no se detectó un ataque. | #### Ejemplo de respuesta ```json { "attack": true } ``` #### `400` Bad Request Cuando la solicitud es inválida, la respuesta incluye un código de error específico en el campo `errors` que describe el problema detectado. Ver [Códigos de error IAD](#códigos-de-error-iad). ```json { "status": 400, "title": "Bad Request", "detail": "Invalid request.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [ "FACE_ANGLE_TOO_LARGE: Facial out-of-plane rotation angle is extremely large" ] } ``` #### Códigos de error IAD | Código HTTP | Mensaje | Código de error | Descripción | | ----------- | ----------------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | 400 | Face not found | `FACE_NOT_FOUND` | No se detectaron rostros en la imagen. | | 400 | Face is cropped | `FACE_CROPPED` | El rostro está solo parcialmente dentro de la imagen. | | 400 | Face is occluded | `FACE_IS_OCCLUDED` | El rostro está siendo parcialmente oculto detrás de un objeto. | | 400 | Too many faces detected | `TOO_MANY_FACES` | Más de un rostro es visible en la imagen. | | 400 | Facial out-of-plane rotation angle is extremely large | `FACE_ANGLE_TOO_LARGE` | El ángulo del rostro correspondiente al punto de vista de la cámara es demasiado grande. | | 400 | Absolute face size is too small | `FACE_TOO_SMALL` | La densidad de píxeles del rostro es muy pequeña, debería estar más cerca de la cámara o la imagen debería tener mayor resolución. | | 400 | Relative face size is too small | `FACE_TOO_SMALL` | El rostro es demasiado pequeño, debería estar más cerca de la cámara para que ocupe una mayor porción de la imagen. | | 400 | Face is too close to one or more borders | `FACE_CLOSE_TO_BORDER` | El rostro está demasiado cerca del límite del punto de vista de la cámara, debería estar centrado respecto a la vista de la cámara. | | 400 | Failed to parse file | `UNKNOWN` | El archivo no es un payload de blob cifrado correcto o está corrupto. | | 400 | Failed to read a meta data | `UNKNOWN` | Los datos del blob cifrado no fueron generados con el formato correcto. | | 400 | Failed to decrypt message | `UNKNOWN` | El par de claves pública-privada configurado en el servidor y la biblioteca de captura no coinciden. | #### `401` Unauthorized ```json { "message": "Unauthorized" } ``` #### `403` Forbidden ```json { "Message": "User is not authorized to access this resource with an explicit deny" } ``` #### `502` Bad Gateway ```json { "status": 502, "title": "Bad Gateway", "detail": "Server got an invalid response.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" } ``` #### `504` Gateway Timeout ```json { "message": "Endpoint request timed out" } ``` ### Integración con Plataforma V2 (opcional) Si la operación está siendo rastreada en Plataforma V2 / IDV Suite, el endpoint puede emitir un evento de tracking por cada llamada a IAD. Esta integración es **opcional** y **aditiva**: no enviar los headers de tracking deja el comportamiento del endpoint idéntico al de versiones anteriores. #### Activación Para activar el tracking en una llamada concreta, basta con incluir los headers `OperationId` y `SessionId` (o, alternativamente, un `ExtraData` tokenizado que los contenga). Además, el tenant debe tener el tracking habilitado en su configuración interna; en caso contrario, los headers son ignorados. #### Información publicada Cuando se emite el evento, aparece en la pestaña **Seguridad** del detalle de la operación con los siguientes campos: | Campo | Descripción | | ------------------ | -------------------------------------------------------------------------------------------------------------------- | | **IAD Diagnostic** | Resultado de alto nivel: `Attack Not Detected`, `Attack Detected`, o `Error: ` si la detección no concluyó. | | **Request ID** | Identificador único de la petición, útil para correlacionar con logs. | | **Version** | Versión del motor de IAD utilizada. Sólo aparece si el tenant la tiene configurada. | El evento se emite tanto en éxitos (`Attack Detected` / `Attack Not Detected`) como en errores (fallo del motor, timeout, bundle inválido), de forma que cualquier invocación a IAD queda registrada con su resultado de alto nivel. No se exponen detalles internos del motor ni del bundle: el evento contiene únicamente el resultado de alto nivel y los identificadores necesarios para auditoría. ### Integración del lado del cliente Para generar el payload del blob cifrado, es necesario utilizar la versión del **Widget Selphi Antispoof** y capturar el evento `onExtractionFinished`. El evento retornará un objeto con los resultados del proceso de extracción facial. Una de las propiedades de este objeto es `encryptedLivenessRaw`, que contiene el payload del blob cifrado. Una vez obtenido el payload, se debe enviar al servidor del cliente mediante una solicitud POST. Se puede utilizar cualquier biblioteca de cliente HTTP, como Axios o Fetch. El servidor del cliente debe recibir este payload y enviarlo al endpoint IAD de Identity API. La API retornará los resultados en un objeto JSON indicando si pasa las validaciones. #### Ejemplo de integración ```javascript const onExtractionFinished = (extractionResult) => { fetch(YOUR_BACKEND_URL, { method: 'POST', headers: { 'Content-Type': 'application/octet-stream', }, body: extractionResult.detail.encryptedLivenessRaw }).then(response => { return response.json(); }).then(result => { console.log('RESULT FROM SERVICE', result); }).catch(e => { console.error(e); }); } ```