Análisis forense de un PDF firmado mediante Connect

De un vistazo

Esta receta usa la herramienta de análisis forense en los transportes de Connect para reconstruir el historial de revisiones de un documento firmado e informar sobre los cambios de contenido producidos fuera de los rangos de bytes firmados. La herramienta es de nivel Enterprise: se detecta mediante una comprobación class_exists() y se registra únicamente cuando nextpdf/premium está instalado junto con el servidor.

La herramienta informa la evidencia observada: revisiones, rangos de bytes, cobertura de firma e indicadores heurísticos de ataques de sombra, con puntuaciones de confianza. Un veredicto «limpio» equivale a la ausencia de modificaciones detectadas dentro del análisis que realiza la herramienta; no garantiza que el documento no haya sido alterado. Los hallazgos respaldan una investigación; no certifican la integridad.

Instalación

composer require nextpdf/server

Confirmar que la herramienta forense Enterprise esté disponible con una llamada tools/list. Consultar /connect/tool-catalog/.

Descripción conceptual

Una firma cubre un rango de bytes, por lo que una modificación posterior a la firma es detectable comparando el documento con ese rango (ISO 32000-2 §12.8). Las actualizaciones incrementales añaden revisiones, y una firma no cubre el contenido agregado después de ella (ISO 32000-2 §12.8). La cadena de revisiones puede reconstruirse a partir de las secciones de referencias cruzadas (ISO 32000-2 §7.5). La herramienta recorre estas estructuras para construir una línea de tiempo y señalar el contenido modificado fuera de la cobertura de firma.

Superficie de la API

Verificar los nombres de las herramientas con el registro en ejecución mediante tools/list. El catálogo de referencia es /connect/tool-catalog/. Esta receta no reproduce el recuento de herramientas.

Ejemplo de código — Inicio rápido

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

Ejemplo de código — Producción

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

La respuesta incluye una línea de tiempo de revisiones, la cobertura de firma por revisión, una lista unsigned_modifications con desplazamientos de bytes y gravedad, indicadores heurísticos de ataques de sombra con puntuaciones de confianza y brechas de cobertura. Tratar el veredicto como evidencia que debe interpretarse, no como una conclusión.

Casos límite y trampas

El documento no tiene firmas. La herramienta devuelve un error de ausencia de firmas. Usar la comprobación de estándares para validar documentos sin firmar.
Documento cifrado. Proporcionar las credenciales de descifrado; de lo contrario, la llamada fallará en lugar de analizar parcialmente.
Referencia cruzada con formato incorrecto. La reconstrucción puede fallar en un archivo gravemente dañado. Reparar el PDF antes de volver a enviarlo.
Herramienta ausente. Sin nextpdf/premium, la herramienta forense Enterprise no se registra y la llamada falla con un error de herramienta desconocida.

Rendimiento

El presupuesto declarado en el front matter es un límite documental. Los documentos muy grandes pueden superar el límite de tamaño de análisis de la herramienta. En ese caso, la herramienta devuelve un error de límite de tamaño en lugar de truncar silenciosamente.

Notas de seguridad

Los indicadores de ataques de sombra son heurísticos e incluyen puntuaciones de confianza. Señalan patrones; no prueban intención. Un veredicto «limpio» significa que no se detectó ninguna modificación dentro del análisis realizado; no es una garantía a prueba de manipulaciones. No registrar la ruta del documento ni el informe completo en un nivel de registro que se exporte externamente.

Conformidad

Afirmación	Cláusula	reference_id
La modificación posterior a la firma es detectable con respecto al rango de bytes firmado	ISO 32000-2 §12.8
Una firma no cubre el contenido agregado por una actualización incremental posterior	ISO 32000-2 §12.8
La cadena de revisiones se puede reconstruir a partir de las secciones de referencias cruzadas	ISO 32000-2 §7.5

La compatibilidad con el análisis forense no certifica la integridad del documento. La interpretación de la evidencia corresponde a un examinador independiente.

Contexto comercial

La herramienta de análisis forense pertenece al nivel Enterprise y se registra únicamente cuando nextpdf/premium está instalado junto con el servidor.

Aspectos específicos de Connect

Disponibilidad de transportes (MCP / REST / gRPC)

Se invoca de forma idéntica a través de MCP tools/call, el punto de conexión de herramientas REST y el servicio gRPC mediante el ejecutor de herramientas compartido.

Nivel de riesgo HITL

El análisis es de solo lectura y no es approval_required de forma predeterminada. Una anulación del operador solo puede elevar su nivel de riesgo. Consultar /connect/hitl-risk-tiers/ para más detalles.

Envoltorio JSON de la puerta de confirmación

La herramienta no activa la puerta salvo que una anulación del operador la eleve a approval_required. El contrato del envoltorio y del token de un solo uso está en /connect/hitl-risk-tiers/.

Véase también

/cookbook/connect/compliance-check/ — validar frente a estándares con nombre.
/cookbook/connect/ltv-health-check/ — inspeccionar el material de validación a largo plazo.
/connect/tool-catalog/ — calcular el conjunto de herramientas por nivel.
/connect/hitl-risk-tiers/ — consultar el modelo de riesgo y la puerta.