Execute uma análise forense em um PDF assinado

Visão geral

Use a ferramenta de análise forense pelo Connect para reconstruir o histórico de revisões de um documento assinado e relatar alterações de conteúdo ocorridas fora dos intervalos de bytes assinados. A ferramenta pertence à camada Enterprise: ela é detectada por uma sondagem class_exists() e registrada somente quando nextpdf/premium está instalado junto ao servidor.

A ferramenta relata as evidências observadas: revisões, intervalos de bytes, cobertura da assinatura e indicadores heurísticos de ataque shadow com pontuações de confiança. Um veredito “limpo” significa que a ferramenta não detectou nenhuma modificação no escopo da análise realizada. Não é uma garantia de que o documento não foi adulterado. Use as constatações para apoiar uma investigação; elas não certificam a integridade.

Instalação

composer require nextpdf/server

Confirme se a ferramenta forense Enterprise está presente com uma chamada tools/list. Consulte /connect/tool-catalog/.

Visão conceitual

Uma assinatura cobre um intervalo de bytes. Você pode detectar modificações posteriores à assinatura comparando o documento com esse intervalo (ISO 32000-2 §12.8). Atualizações incrementais acrescentam revisões, e uma assinatura não cobre o conteúdo adicionado depois dela (ISO 32000-2 §12.8). A cadeia de revisões pode ser reconstruída a partir das seções de referência cruzada (ISO 32000-2 §7.5). A ferramenta percorre essas estruturas para montar uma linha do tempo e sinalizar conteúdo alterado fora da cobertura da assinatura.

Superfície da API

Verifique os nomes das ferramentas no registro em execução com tools/list. O catálogo oficial é /connect/tool-catalog/. Esta receita não repete uma contagem de ferramentas.

Exemplo de código — Início rápido

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "forensic_analyze",
    "arguments": { "document_id": "<id>" }
  }
}

Exemplo de código — Produção

curl -sS -X POST https://connect.example.com/v1/tools/forensic_analyze \
  -H 'Authorization: Bearer '"$NEXTPDF_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"source":"/var/lib/nextpdf/evidence/disputed-contract.pdf"}' \
  -o /tmp/forensic.json -w '%{http_code}' > /tmp/forensic-status || {
    echo "transport failure invoking forensic_analyze" >&2; exit 1; }

A resposta inclui uma linha do tempo de revisões, a cobertura da assinatura por revisão, uma lista unsigned_modifications com deslocamentos de bytes e gravidade, indicadores heurísticos de ataque shadow com pontuações de confiança e lacunas de cobertura. Trate o veredito como evidência a ser interpretada, não como conclusão.

Casos de borda e pegadinhas

• Nenhuma assinatura no documento. A ferramenta retorna um erro indicando ausência de assinaturas. Use a verificação de conformidade com padrões para validar um documento não assinado.
• Documento criptografado. Forneça as credenciais de descriptografia, ou a chamada falha em vez de executar uma análise parcial.
• Referência cruzada malformada. A reconstrução pode falhar em um arquivo gravemente corrompido. Repare o PDF antes de reenviá-lo.
• Ferramenta ausente. Sem nextpdf/premium, a ferramenta forense Enterprise não é registrada, e a chamada falha com um erro de ferramenta desconhecida.

Desempenho

O orçamento do front-matter é um limite de documentação. Documentos muito grandes podem exceder o limite de tamanho para análise da ferramenta. Nesse caso, a ferramenta retorna um erro de limite de tamanho em vez de truncar silenciosamente.

Notas de segurança

Os indicadores de ataque shadow são heurísticos e incluem pontuações de confiança. Eles sinalizam padrões; não comprovam intenção. Um veredito “limpo” significa que a ferramenta não detectou nenhuma modificação no escopo da análise realizada. Não é uma garantia à prova de adulteração. Não registre o caminho do documento nem o relatório completo em um nível de log exportado para fora.

Conformidade

Afirmação	Cláusula
Modificações posteriores à assinatura são detectáveis em relação ao intervalo de bytes assinado	ISO 32000-2 §12.8
Uma assinatura não cobre o conteúdo adicionado por uma atualização incremental posterior	ISO 32000-2 §12.8
A cadeia de revisões pode ser reconstruída a partir das seções de referência cruzada	ISO 32000-2 §7.5

O suporte para análise forense não é uma certificação da integridade do documento. Um examinador independente interpreta as evidências.

Contexto comercial

A ferramenta de análise forense pertence à camada Enterprise e só é registrada quando nextpdf/premium está instalado junto ao servidor.

Especificidades do Connect

Disponibilidade de transporte (MCP / REST / gRPC)

Invoque a ferramenta da mesma forma pelo tools/call do Model Context Protocol (MCP), pelo endpoint de ferramenta Representational State Transfer (REST) e pelo serviço gRPC, usando o executor de ferramentas compartilhado.

Camada de risco HITL

A análise é somente leitura e não é approval_required por padrão. Uma substituição feita pelo operador só pode elevar o nível de risco. Consulte /connect/hitl-risk-tiers/ para ver os detalhes.

Envelope JSON do portão de confirmação

A ferramenta não aciona o portão a menos que uma substituição feita pelo operador a eleve para approval_required. O contrato do envelope e do token de uso único está em /connect/hitl-risk-tiers/.

Veja também

• /cookbook/connect/compliance-check/ — valide em relação a padrões nomeados.
• /cookbook/connect/ltv-health-check/ — inspecione o material de validação de longo prazo.
• /connect/tool-catalog/ — calcule o conjunto de ferramentas de cada camada.
• /connect/hitl-risk-tiers/ — consulte o modelo de risco e o portão.