> 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/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/security-compliance/injection-attack-detection.md). # Detecção de ataque por injeção (IAD) Esta API, no contexto de captura e avaliação facial, permite a detecção de: **Vetores de ataque:** câmeras virtuais, dispositivos externos, ataques de navegador, ataques de rede. **Conteúdo de ataque:** renderização 3D, morphing facial, face swap, cheap fake, deep fake. Esta API requer a Integração do lado do cliente das bibliotecas de captura IAD. A biblioteca de captura IAD (incluída em **Selphi**) controla o processo de captura no cliente e gera o **IAD bundle** (pacote criptografado de metadados e imagens). A API sabe como descompactar o IAD bundle do cliente para realizar tanto a Detecção de Ataques de Injeção quanto a detecção de ataques de apresentação. ### Endpoint ``` POST /iad ``` ### Cabeçalhos | Nome | Tipo | Obrigatório | Descrição | | --------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **x-api-key** | string | **Sim** | API Key de autorização de acesso. | | **OperationId** | string | Não | Identificador da operação na Plataforma V2. Se enviado junto com `SessionId`, é emitido um evento de Tracking na aba Segurança do detalhe da operação. | | **SessionId** | string | Não | Identificador de sessão associado à operação. Obrigatório para ativar o Tracking, a menos que seja utilizado `ExtraData`. | | **ExtraData** | string | Não | Token criptografado que empacota `operationId` e `sessionId`. Alternativa a enviá-los separadamente. | | **Família** | string | Não | Família do evento de Tracking. Por padrão `Onboarding`. | ### Corpo da solicitação **Content-Type:** `application/octet-stream` #### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | ------------ | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `IAD_BUNDLE` | binário | **Sim** | Pacote criptografado de metadados e imagens. O bundle deve ser enviado como uma solicitação `application/octet-stream` no body. | #### Exemplo de solicitação ```bash curl --location '{IDENTITY_API_BASE_URL}/iad' \\ --header 'x-api-key: {API_KEY}' \\ --header 'Content-Type: application/octet-stream' \\ --data 'IAD_BUNDLE' ``` ### Respostas #### `200` Sucesso #### Parâmetros de resposta | Parâmetro | Tipo | Descrição | | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | `attack` | boolean | Valor booleano que indica se foi detectado um ataque. `true`: foi detectado um ataque, `false`: nenhum ataque foi detectado. | #### Exemplo de resposta ```json { "attack": true } ``` #### `400` Solicitação inválida Quando a solicitação é inválida, a resposta inclui um código de erro específico no campo `errors` que descreve o problema detectado. Veja [Códigos de erro IAD](#códigos-de-error-iad). ```json { "status": 400, "title": "Solicitação inválida", "detail": "Requisição inválida.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [ "FACE_ANGLE_TOO_LARGE: O ângulo de rotação facial fora do plano é extremamente grande" ] } ``` #### Códigos de erro IAD | Código HTTP | Mensagem | Código de erro | Descrição | | ----------- | -------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | 400 | Rosto não encontrado | `FACE_NOT_FOUND` | Não foram detectados rostos na imagem. | | 400 | Rosto cortado | `FACE_CROPPED` | O rosto está apenas parcialmente dentro da imagem. | | 400 | Rosto ocluído | `FACE_IS_OCCLUDED` | O rosto está sendo parcialmente ocultado atrás de um objeto. | | 400 | Muitos rostos detectados | `TOO_MANY_FACES` | Mais de um rosto está visível na imagem. | | 400 | O ângulo de rotação facial fora do plano é extremamente grande | `FACE_ANGLE_TOO_LARGE` | O ângulo do rosto correspondente ao ponto de vista da câmera é grande demais. | | 400 | O tamanho absoluto do rosto é muito pequeno | `FACE_TOO_SMALL` | A densidade de pixels do rosto é muito pequena; ele deveria estar mais perto da câmera ou a imagem deveria ter maior resolução. | | 400 | O tamanho relativo do rosto é muito pequeno | `FACE_TOO_SMALL` | O rosto está muito pequeno; ele deveria estar mais perto da câmera para ocupar uma porção maior da imagem. | | 400 | O rosto está muito próximo de uma ou mais bordas | `FACE_CLOSE_TO_BORDER` | O rosto está muito próximo do limite do ponto de vista da câmera; ele deveria estar centralizado em relação à vista da câmera. | | 400 | Falha ao analisar o arquivo | `UNKNOWN` | O arquivo não é um payload de blob criptografado válido ou está corrompido. | | 400 | Falha ao ler metadados | `UNKNOWN` | Os dados do blob criptografado não foram gerados com o formato correto. | | 400 | Falha ao descriptografar a mensagem | `UNKNOWN` | O par de chaves pública-privada configurado no servidor e a biblioteca de captura não coincidem. | #### `401` Não autorizado ```json { "message": "Não autorizado" } ``` #### `403` Acesso negado ```json { "Message": "O usuário não está autorizado a acessar este recurso com uma negação explícita" } ``` #### `502` Gateway inválido ```json { "status": 502, "title": "Gateway inválido", "detail": "O servidor recebeu uma resposta inválida.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" } ``` #### `504` Gateway Timeout ```json { "message": "A solicitação do Endpoint excedeu o tempo limite" } ``` ### Integração com a Plataforma V2 (opcional) Se a operação estiver sendo rastreada na Plataforma V2 / IDV Suite, o Endpoint pode emitir um evento de Tracking por chamada ao IAD. Esta Integração é **opcional** e **aditiva**: não enviar os headers de Tracking deixa o comportamento do Endpoint idêntico ao das versões anteriores. #### Ativação Para ativar o Tracking em uma chamada específica, basta incluir os headers `OperationId` e `SessionId` (ou, alternativamente, um `ExtraData` Tokenizado que os contenha). Além disso, o tenant deve ter o Tracking habilitado em sua configuração interna; caso contrário, os headers são ignorados. #### Informação publicada Quando o evento é emitido, aparece na aba **Segurança** do detalhe da operação com os seguintes campos: | Campo | Descrição | | -------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Diagnóstico IAD** | Resultado de alto nível: `Ataque não detectado`, `Ataque detectado`, ou `Erro: ` se a detecção não foi concluída. | | **ID da requisição** | Identificador único da requisição, útil para correlacionar com logs. | | **Versão** | Versão do motor de IAD utilizada. Só aparece se o tenant a tiver configurado. | O evento é emitido tanto em sucessos (`Ataque detectado` / `Ataque não detectado`) como em erros (falha do motor, Timeout, bundle inválido), de forma que qualquer invocação ao IAD fica registrada com seu resultado de alto nível. Não são expostos detalhes internos do motor nem do bundle: o evento contém apenas o resultado de alto nível e os identificadores necessários para auditoria. ### Integração do lado do cliente Para gerar o payload do blob criptografado, é necessário utilizar a Versão do **Widget Selphi Antispoof** e capturar o evento `onExtractionFinished`. O evento retornará um objeto com os resultados do processo de extração facial. Uma das propriedades desse objeto é `encryptedLivenessRaw`, que contém o payload do blob criptografado. Uma vez obtido o payload, ele deve ser enviado ao servidor do cliente por meio de uma solicitação POST. Pode-se utilizar qualquer biblioteca cliente HTTP, como Axios ou Fetch. O servidor do cliente deve receber esse payload e enviá-lo ao Endpoint IAD da Identity API. A API retornará os resultados em um objeto JSON indicando se passa nas validações. #### Exemplo de Integração ```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); }); } ```