Serviço IAD

API Rest de detecção de ataques de injeção (Injection Attack Detection) — Protege seus sistemas biométricos contra ataques de spoofing.

O que é o IAD Service?

IAD Service é um microserviço de API Rest que detecta ataques de injeção em capturas biométricas. Verifica que os dados biométricos provêm de fontes reais, e não de repetições (replays) nem de entradas sintéticas.

Aviso de mudança incompatível (2.0.0) A versão 2.0.0 quebra a compatibilidade da API REST pública com todas as versões 1.x.x anteriores. As integrações que atualizarem a partir de 1.x.x devem atualizar os caminhos dos endpoints, os nomes dos campos das solicitações multipart e a análise das respostas corretas.

Contrato 1.x.x	Contrato 2.0.0
POST /api/v1/iad/check-capture	POST /api/v1/iad/liveness/evaluate
POST /api/v1/iad/extract-image	POST /api/v1/iad/extract
campo multipart file	campo multipart obrigatório capture; file é rejeitado quando falta capture
Payloads privados herdados de sucesso (capture_liveness, capture_type, rejection, mime_type)	Payloads públicos da Facephi (diagnostic, reason, probability, score, faceProbability, sdkDuration, queueDuration, mimeType)

Use-o para:

• Extrair imagens válidas de capturas autenticadas

• Monitorar o estado e o desempenho do sistema

• Integrá-lo sem atritos com seus fluxos de autenticação

Início rápido

Requisitos

Componente	Requisito
SO	Linux x86_64 (recomendado Ubuntu 24.04)
Licença	Arquivo de licença válido da Facephi

Implantação com Docker

docker run -d \
  -p 6982:6982 \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name iad-service \
  facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:2.2.0

Verificar se funciona

# Check health
curl http://localhost:6982/api/v1/iad/health

# Check version
curl http://localhost:6982/api/v1/iad/version

Respostas típicas:

{
  "message": "Healthy"
}

{
  "message": "2.2.0 Copyright © 2026 FacePhi Biometria. All rights reserved."
}

Endpoints da API

Nota de compatibilidade Os caminhos documentados nesta página são válidos somente para a versão 2.0.0 e posteriores.

Operações principais

Endpoint	Método	Propósito
/api/v1/iad/liveness/evaluate	POST	Avalia o liveness de uma captura criptografada com o contrato público da Facephi
/api/v1/iad/extract	POST	Extrai a imagem de uma captura validada

Gerenciamento

Endpoint	Método	Propósito
/api/v1/iad/version	GET	Versão do serviço e estado da licença
/api/v1/iad/health	GET	Verificação ativa de estado (inclui snapshot initialized e engine.lastHealth*)
/api/v1/iad/metrics	GET	Snapshot JSON de métricas operacionais e de qualidade
/api/v1/iad/metrics/prometheus	GET	Snapshot equivalente em formato Prometheus
/api/v1/iad/config	GET/POST	Obter ou atualizar a configuração

/health e /metrics têm objetivos diferentes:

• /health executa a verificação ativa do engine e atualiza o snapshot de saúde.

• /metrics expõe contadores e snapshots em memória, sem executar verificações ativas caras a cada scrape.

Mitigação experimental de ataques de repetição (replay)

O serviço pode aplicar uma janela de vigência (freshness window) aos payloads de captura de entrada. Essa proteção experimental está desabilitada por padrão.

• Ative-a com FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED=true

• Ajuste a janela de vigência com FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME=<seconds>

• Janela de vigência padrão: 300 segundos

• Aplica-se aos endpoints de processamento de capturas como POST /api/v1/iad/liveness/evaluate e POST /api/v1/iad/extract

• Quando a janela de vigência é excedida, o serviço retorna HTTP 400 com message igual a Replay attack detected

Exemplo de implantação:

docker run -d \
  -p 6982:6982 \
  -e FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED=true \\
  -e FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME=60 \\
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name iad-service \
  facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:2.2.0

Essa funcionalidade é configurada apenas na inicialização por meio de variáveis de ambiente. Não faz parte de config.json nem é exposta por meio de GET|POST /api/v1/iad/config.

Autenticação JWT

A autenticação JWT é opcional e está desabilitada por padrão.

• Configure-a na inicialização por meio de config.json com auth_enabled, auth_jwt_secret, auth_accept_authorization_header, auth_accept_api_key_header e auth_api_key_header_name

• Substitua esses mesmos valores por meio de variáveis de ambiente FACEPHI_IAD_REST_AUTH_*

• GET /api/v1/iad/config omite todas as chaves de autenticação JWT

• POST /api/v1/iad/config rejeita todas as chaves de autenticação JWT; use em vez disso a configuração de inicialização

Exemplo de trecho de config.json:

{
  "auth_enabled": true,
  "auth_jwt_secret": "replace-with-secret",
  "auth_accept_authorization_header": true,
  "auth_accept_api_key_header": true,
  "auth_api_key_header_name": "x-api-key"
}

Exemplo de variáveis de ambiente:

export FACEPHI_IAD_REST_AUTH_ENABLED=true
export FACEPHI_IAD_REST_AUTH_JWT_SECRET=replace-with-secret
export FACEPHI_IAD_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER=true
export FACEPHI_IAD_REST_AUTH_ACCEPT_API_KEY_HEADER=true
export FACEPHI_IAD_REST_AUTH_API_KEY_HEADER_NAME=x-api-key

Contrato público de erros

Nas respostas HTTP públicas 400, o serviço retorna mensagens públicas documentadas no corpo da resposta padrão.

Resultado de Liveness

As respostas corretas de POST /api/v1/iad/liveness/evaluate exibem apenas os seguintes campos públicos:

Campo	Significado
diagnostic	Resultado de alto nível: Live ou NoLive
reason	Valor público do motivo retornado pelo serviço
probability	Probabilidade pública da captura
score	Pontuação pública de confiança
faceProbability	Probabilidade pública opcional de liveness facial, quando disponível
sdkDuration	Duração da análise da captura em milissegundos
queueDuration	Duração na fila informada pelo RestManager em milissegundos

Os valores possíveis para reason são:

• None

• Unknown

• UntrustedEnvironment

• SuspiciousActivity

• UntrustedDevice

• SdkIntegrityViolation

• UntrustedCorruptedPayload

• UntrustedContent

• UntrustedContentLowConfidence

reason	Significado
None	A captura foi aceita como Live e nenhum motivo de rejeição se aplica.
Unknown	O serviço não conseguiu atribuir a resposta a um motivo de rejeição público documentado.
UntrustedEnvironment	A captura foi rejeitada porque o ambiente de execução não é considerado confiável.
SuspiciousActivity	A captura foi rejeitada porque o dispositivo exibiu padrões de atividade associados a um ataque.
UntrustedDevice	A captura foi rejeitada porque não foi possível confiar que o dispositivo fosse quem diz ser.
SdkIntegrityViolation	A captura foi rejeitada porque o SDK de captura ou suas bibliotecas parecem ter sido alterados.
UntrustedCorruptedPayload	A captura foi rejeitada porque o payload parece estar corrompido ou manipulado.
UntrustedContent	A captura foi rejeitada porque foi detectado um ataque de injeção.
UntrustedContentLowConfidence	A captura foi rejeitada porque o serviço detectou indícios de um ataque de injeção com menor confiança; ainda assim deve ser tratada como uma rejeição.

Quando existem várias causas de rejeição, o serviço retorna o primeiro valor público de rejeição documentado conforme a ordem de resposta do serviço.

Erros de validação normalizados

Para o endpoint POST /api/v1/iad/liveness/evaluate, as falhas de validação de captura são retornadas como HTTP 400 com valores de message documentados, como:

Cenário	message público
Rosto muito próximo	NoneBecauseFaceTooClose
Rosto não encontrado	NoneBecauseFaceNotFound
Rosto cortado	NoneBecauseFaceCropped
Rosto ocluído	NoneBecauseFaceOccluded
Muitos rostos	NoneBecauseTooManyFaces
Ângulo do rosto muito grande	NoneBecauseAngleTooLarge
Rosto muito pequeno	NoneBecauseFaceTooSmall
Rosto muito perto da borda	NoneBecauseFaceTooCloseToBorder
Olhos fechados	NoneBecauseEyesClosed
Não é possível processar a imagem ou o payload	NoneBecauseImageDataError
Problema de licença reportado pelo runtime do serviço	NoneBecauseLicenseError
Janela de vigência de repetição excedida	Replay attack detected
Falha de liveness não classificada	ErrorProcessing

Para o endpoint POST /api/v1/iad/extract, as falhas de análise e desencriptação do payload são retornadas como NoneBecauseImageDataError; as capturas expiradas rejeitadas pela proteção contra repetições retornam Replay attack detected; as falhas de extração não classificadas são retornadas como ErrorFacialImage.

Exemplo de uso

Nota de atualização Os exemplos a seguir usam intencionalmente o contrato público 2.x introduzido na Versão 2.0.0: o campo multipart capture e o esquema de resposta pública.

Avaliar Liveness

curl -X POST \\
  -F "capture=@biometric_capture.bin" \\
  http://localhost:6982/api/v1/iad/liveness/evaluate

Resposta:

{
  "diagnostic": "Live",
  "reason": "None",
  "probability": 1,
  "score": 1,
  "sdkDuration": 12,
  "queueDuration": 3
}

Extrair imagem

curl -X POST \\
  -F "capture=@biometric_capture.bin" \\
  http://localhost:6982/api/v1/iad/extract

Resposta:

{
  "image": "base64_encoded_image...",
  "mimeType": "image/jpeg"
}

Obter configuração

Retorna a visão pública da configuração em tempo de execução. As chaves de autenticação JWT são omitidas intencionalmente.

curl http://localhost:6982/api/v1/iad/config

Atualizar configuração

POST /api/v1/iad/config espera um objeto JSON com o campo config_json_string, que contém a configuração completa serializada como uma string JSON. As chaves de autenticação JWT são rejeitadas por este endpoint e devem ser definidas apenas na inicialização.

curl -X POST \\
  -H "Content-Type: application/json" \\
  -d '{"config_json_string":"{\"port\":6982,\"number_of_threads\":1,\"engine_url\":\"http://localhost:8080\",\"engine_pool_size\":8}"}' \\
  http://localhost:6982/api/v1/iad/config

Resposta:

{
  "message": "Configuration updated successfully"
}

Configuração

Cria /app/config/config.json:

{
  "port": 6982,
  "number_of_threads": 1,
  "connection_timeout": 60,
  "keep_alive_request_number": 0,
  "client_max_body_size": 100,
  "logger_level": "info",
  "logger_path": "/app/logs",
  "logger_rotation": "daily",
  "logger_max_files": 7,
  "auth_enabled": false,
  "auth_jwt_secret": "",
  "auth_accept_authorization_header": true,
  "auth_accept_api_key_header": true,
  "auth_api_key_header_name": "x-api-key",
  "engine_connection_timeout": 10000,
  "engine_request_timeout": 60000,
  "engine_max_retries": 3,
  "engine_retry_delay": 1000,
  "engine_verify_ssl": false,
  "engine_verbose": false,
  "engine_pool_size": 4,
  "engine_url": "http://localhost:8080"
}

Parâmetros principais

Parâmetro	Padrão	Descrição
port	6982	Porta de escuta do serviço
number_of_threads	1	Threads de trabalho para o processamento de solicitações
connection_timeout	60	Timeout de conexão do Rest::Manager
keep_alive_request_number	0	Número máximo de solicitações keep-alive
client_max_body_size	100	Tamanho máximo do corpo da solicitação em MB
logger_level	"info"	Nível de log (trace/debug/info/warn/error)
auth_enabled	false	Requer autenticação JWT para os endpoints protegidos
auth_jwt_secret	""	Segredo compartilhado HS256 usado para validar os JWTs
auth_accept_authorization_header	true	Aceita Authorization: Bearer <jwt>
auth_accept_api_key_header	true	Aceita JWT no cabeçalho de API key configurado
auth_api_key_header_name	"x-api-key"	Nome do cabeçalho usado quando a extração de token por API key está habilitada
engine_connection_timeout	10000	Timeout de conexão (ms)
engine_request_timeout	60000	Timeout de solicitação (ms)
engine_max_retries	3	Tentativas de repetição do engine
engine_retry_delay	1000	Atraso entre tentativas do engine em ms
engine_verify_ssl	false	Verifica os certificados SSL do runtime de análise de capturas
engine_verbose	false	Habilita logs detalhados do proxy de análise de capturas
engine_pool_size	4	Tamanho do pool de conexões
engine_url	http://localhost:8080	URL base do runtime de análise de capturas

Visão geral da arquitetura

Suporte

Para consultas de licença ou Suporte Técnico, entre em contato com seu representante da Facephi.