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

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

{
  "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.

{
  "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

{
  "message": "Não autorizado"
}

403 Acesso negado

{
  "Message": "O usuário não está autorizado a acessar este recurso com uma negação explícita"
}

502 Gateway inválido

{
  "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

{
  "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: <detalhe> 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

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);
  });
}