Análisis forense

De un vistazo

NextPDF Enterprise Forensics lee el historial de actualizaciones incrementales de un PDF y produce un informe estructurado y de solo lectura de las revisiones, los eventos clasificados y los cambios por objeto. Da soporte a flujos de trabajo de análisis forense. No es un sello a prueba de manipulaciones y no afirma que un documento sea auténtico ni que no haya sido alterado.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Una implementación sin ese derecho de uso no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Instalación

composer require nextpdf/enterprise:^3

Descripción conceptual

Un PDF se puede actualizar anexando los cambios al final del archivo en lugar de reescribirlo. Cada actualización añade una nueva sección de referencias cruzadas y un nuevo tráiler, y los bytes originales se dejan en su sitio — ISO 32000-2:2020 §7.5.6. Cuando se cambia un objeto, la actualización anexa una nueva copia y la sección de referencias cruzadas de la actualización registra un desplazamiento de bytes que invalida el desplazamiento más antiguo; un lector resuelve la copia más reciente — ISO 32000-2:2020 §7.5.6. La estructura inicial del archivo puede ser modificada por actualizaciones posteriores — ISO 32000-2:2020 §7.5.4. La sección de referencias cruzadas de una actualización enumera únicamente los objetos que se añadieron, modificaron o eliminaron en esa actualización — ISO 32000-2:2020 §7.5.5.

El analizador lee esta estructura en capas. Analiza la tabla de referencias cruzadas de cada revisión, deriva los límites de bytes de la revisión y compara las entradas de cada revisión con la siguiente revisión más antigua para clasificar cada objeto como añadido, modificado o eliminado. A continuación, agrupa los cambios de objeto en eventos de nivel superior: se añadió una firma, se actualizó el catálogo del documento, apareció un diccionario de cifrado, o se añadió, modificó o eliminó un conjunto de objetos. La salida es un objeto de informe que transporta un recuento de revisiones, el tamaño total, una lista de resumen por revisión, una línea de tiempo de eventos clasificados y la lista de cambios por objeto.

El analizador es de solo lectura. Detecta la existencia de una revisión de firma a partir de marcadores estructurales; no valida ninguna firma, no recalcula ningún resumen ni comprueba ningún certificado. La validación de firma es una capacidad separada de Core. Un informe producido es una descripción estructural del historial de actualizaciones tal como se analizó; no es una determinación de que un documento sea auténtico, de que un cambio fuera no autorizado ni de que se haya detectado toda modificación. Trate el informe como detección de evidencia de manipulación probada frente a la vista del analizador de la cadena de revisiones, no como una garantía forense ni una atestación admisible ante un tribunal.

Por qué funciona así

El analizador se detiene deliberadamente en la estructura. Informa de lo que contiene la cadena de revisiones y nunca afirma que un cambio estuviera autorizado ni que una firma fuera válida. La presencia estructural y la validez criptográfica son afirmaciones distintas; combinarlas permitiría que quien llama confundiera la evidencia de manipulación con una garantía. Por ello, la validez de firma permanece en la única superficie de firma de Core, con la que Forensics se compone en lugar de duplicarla. El informe son metadatos estructurales serializables en JSON, de modo que un SIEM ingiere el historial de edición sin tocar el contenido del documento. Contexto de diseño: Actualizaciones incrementales y por qué importan.

Superficie de la API

Tipo	Clase	Función	Estabilidad	Desde
ForensicAnalyzer	clase	Analiza un PDF y devuelve un informe forense (analyze estático)	estable	1.10.0
ForensicReport	clase	El resultado del análisis; JsonSerializable para exportación a SIEM	estable	1.10.0
RevisionSummary	clase	Datos por revisión: número de objetos, tamaño, límites de bytes, indicadores de presencia	estable	1.10.0
ForensicEvent	clase	Un evento clasificado con una lista de objetos afectados	estable	1.10.0
ForensicEventType	enum	Categorías de evento (firma añadida, catálogo actualizado, objetos añadidos y otras)	estable	1.10.0
ObjectChange	clase	El registro de cambio de un objeto entre dos revisiones	estable	1.10.0
ObjectChangeType	enum	Added, Modified o Deleted	estable	1.10.0

ForensicReport expone hasIncrementalUpdates(), hasAnySignature(), getEventsByType(), getChangesForRevision() y jsonSerialize(). El indicador hasSignature en un resumen de revisión es una señal de presencia estructural, no un resultado de validez.

Ejemplo de código — Inicio rápido

Analyze the revision history of a PDF

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Forensics\ForensicAnalyzer;

/**
 * Produce a forensic report from PDF bytes.
 *
 * @param string $pdfData Raw PDF file bytes.
 *
 * @return array{revisions: int, incremental: bool, signedRevisionPresent: bool}
 */
function inspect(string $pdfData): array
{
    $report = ForensicAnalyzer::analyze($pdfData);

    return [
        'revisions' => $report->revisionCount,
        'incremental' => $report->hasIncrementalUpdates(),
        'signedRevisionPresent' => $report->hasAnySignature(),
    ];
}

hasAnySignature() informa de que una revisión de firma está presente en la estructura. No declara que la firma sea válida.

Ejemplo de código — Producción

Forensic analysis with SIEM export and fail-closed handling

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Forensics\ForensicAnalyzer;
use NextPDF\Enterprise\Forensics\ForensicEventType;
use Psr\Log\LoggerInterface;

final readonly class RevisionAuditor
{
    public function __construct(private LoggerInterface $logger) {}

    /**
     * Analyze a document and emit a structural JSON record for the SIEM.
     *
     * @param string $pdfData The PDF bytes to inspect.
     *
     * @return string A JSON forensic report (no document content).
     */
    public function audit(string $pdfData): string
    {
        try {
            $report = ForensicAnalyzer::analyze($pdfData);

            $this->logger->info('Forensic analysis complete', [
                'revisions' => $report->revisionCount,
                'sizeBytes' => $report->totalSizeBytes,
                'signatureAddedEvents' => count(
                    $report->getEventsByType(ForensicEventType::SignatureAdded),
                ),
            ]);

            return json_encode($report, JSON_THROW_ON_ERROR);
        } catch (\Throwable $e) {
            $this->logger->error('Forensic analysis failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

El registro de log transporta únicamente recuentos y tamaños. No transporta texto del documento. El bloque catch vuelve a lanzar; no engulle un fallo de análisis.

Casos límite y trampas

• Un documento de una sola revisión no tiene historial incremental. La lista de cambios está vacía; esto no es evidencia de autenticidad.
• Un evento SignatureAdded significa que una revisión de firma está estructuralmente presente. No es un resultado de validez de firma. Valide la firma con la superficie de firma de Core.
• La reutilización de objetos es normal: un objeto actualizado conserva su número de objeto y se anexa una nueva copia. El analizador lo informa como Modified, no como eliminación y recreación.
• Una clasificación Deleted es una transición de entrada libre en la cadena de referencias cruzadas. Un lector aún puede resolver una copia más antigua de ese objeto; la eliminación a nivel de estructura no garantiza la irrecuperabilidad.
• El analizador informa de lo que observó el analizador sintáctico. Un documento diseñado para confundir a un analizador puede producir un informe que no coincida con la vista de otra herramienta. El informe no es una afirmación de que se haya detectado toda modificación.
• La entrada está acotada. Un documento de tamaño excesivo o con un número excesivo de revisiones falla de forma cerrada con una excepción de análisis tipada en lugar de consumir memoria sin límite.

Rendimiento

El costo del análisis escala con el número de revisiones y el número de objetos, no con la complejidad de las páginas representadas. El presupuesto de tiempo de pared de 1500 ms cubre un documento de negocio típico con varias revisiones. El perfil de reproducibilidad es structural: el informe es determinista para una entrada dada, pero los desplazamientos de bytes absolutos reflejan el archivo de entrada exacto y no son portables entre copias vueltas a guardar.

Notas de seguridad

El analizador es de solo lectura y nunca escribe en la entrada. Es una superficie analítica, no transformacional. Detecta la existencia de marcadores de firma y de cifrado, pero no realiza ninguna operación criptográfica, por lo que no hace ninguna declaración FIPS. Un informe describe el historial de actualizaciones analizado; no es una afirmación de autenticidad y no debe presentarse como a prueba de manipulaciones, garantizado forensemente ni admisible ante un tribunal. El operador extrae conclusiones; la biblioteca informa de la estructura.

Residencia de datos y mitigaciones de PII

El análisis se ejecuta en proceso en el host que contiene el PDF. Ningún contenido del documento sale del host. El informe transporta números de objeto, índices de revisión, tamaños, límites de bytes y categorías de evento — metadatos estructurales, no texto del documento ni datos personales detectados. Si el PDF de entrada o el propio informe contiene datos personales, y dónde se almacena cada uno, es una responsabilidad de despliegue fuera del límite de la biblioteca.

Telemetría segura y depuración de registros

La biblioteca genera excepciones tipadas con mensajes estructurales y no coloca bytes del documento en el texto de la excepción. Una implementación que registre alrededor del análisis debería registrar los recuentos y las categorías del informe —como se muestra en el ejemplo de producción— y no debe registrar la carga útil del PDF en bruto en los registros ni en un backend de APM. El informe JSON es el artefacto seguro para reenviar a un SIEM.

Comportamiento en modo FIPS

En este módulo no ocurre ninguna operación criptográfica, por lo que no hay ningún comportamiento específico del modo FIPS. La validación de firma, que es criptográfica, es una capacidad separada de Core y se documenta allí.

Conformidad

Declaración	Estándar	Cláusula
Las actualizaciones posteriores anexan elementos adicionales al final del archivo; la estructura original se modifica con actualizaciones posteriores.	ISO 32000-2:2020	§7.5.6
Un objeto actualizado se anexa como una nueva copia y la entrada de referencias cruzadas de la actualización invalida el desplazamiento de bytes anterior; el lector resuelve la copia más reciente.	ISO 32000-2:2020	§7.5.6
La estructura inicial del archivo puede ser modificada por actualizaciones posteriores.	ISO 32000-2:2020	§7.5.4
La sección de referencias cruzadas de una actualización contiene entradas únicamente para objetos añadidos, modificados o eliminados.	ISO 32000-2:2020	§7.5.5
El diccionario de firma registra qué se firma.	ISO 32000-2:2020	§12.8.1
ByteRange define el rango de bytes que cubre la firma (la validación de firma es una capacidad separada de Core).	ISO 32000-2:2020	§12.8.1
Un almacén de seguridad de documento contiene material de validación a largo plazo en una revisión posterior.	ISO 32000-2:2020	§12.8.4

Todas las cláusulas están parafraseadas. NextPDF no reproduce el texto normativo. Consulte el estándar publicado para conocer la redacción autorizada. NextPDF no hace ninguna declaración de certificación forense; el informe describe la estructura de actualizaciones analizada, no una determinación certificada de la integridad del documento.

Contrato de comportamiento

• El analizador es de solo lectura: nunca escribe en el documento de entrada y no realiza ninguna operación criptográfica.
• Analiza la tabla de referencias cruzadas de cada revisión, deriva los límites de bytes de la revisión y clasifica cada objeto como añadido, modificado o eliminado, y después agrupa los cambios en una línea de tiempo de eventos clasificados.
• Un evento SignatureAdded significa que una revisión de firma está estructuralmente presente; no es un resultado de validez de firma — la validación es una capacidad separada de Core.
• Un documento de una sola revisión tiene una lista de cambios vacía (no es evidencia de autenticidad); una clasificación Deleted es una transición de entrada libre, no una irrecuperabilidad garantizada.
• La entrada está acotada: un documento de tamaño excesivo o con un número excesivo de revisiones falla de forma cerrada con una excepción de análisis tipada. El informe es detección de evidencia de manipulación probada, no una garantía forense ni una atestación admisible ante un tribunal.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de API pública admitida. Las rutas internas de espacio de nombres, las clases auxiliares, las tablas de mecanismos, los nombres de archivos de runbook y los prefijos de tickets quedan fuera de alcance.

Alternativa de Core

NextPDF Core (Apache-2.0) no tiene analizador forense del historial de revisiones — ninguno; esta capacidad no tiene equivalente en el nivel Core. Core suministra la superficie autorizada de validación de firma, con la que el analizador se compone pero a la que no reemplaza.

Alternativa de Pro

NextPDF Pro no tiene analizador forense del historial de revisiones — ninguno; esta capacidad no tiene equivalente en el nivel Pro. El informe de solo lectura de revisiones y de cambios por objeto y el informe serializable en JSON para SIEM se distribuyen únicamente en el paquete nextpdf/enterprise.

Nota sobre el límite de Enterprise

El analizador de revisiones, la clasificación de cambios y la línea de tiempo de eventos se describen a nivel de comportamiento. Los detalles internos del analizador y cualquier detalle interno de clasificación quedan fuera del alcance de la superficie pública. La validez de firma queda deliberadamente fuera de alcance aquí — es responsabilidad de la superficie de firma de Core.

Límite de despliegue

El análisis se ejecuta en proceso en el host que contiene el PDF; ningún contenido del documento sale del host. Si el PDF de entrada o el informe contiene datos personales, y dónde se almacena cada uno, es una responsabilidad de despliegue fuera del límite de la biblioteca. El operador extrae conclusiones del informe; la biblioteca informa de la estructura y no afirma la autenticidad del documento.

Límite de cumplimiento legal

No se aplica ninguna restricción de control de exportación a la superficie de Forensics. El informe no debe presentarse como a prueba de manipulaciones, garantizado forensemente ni admisible ante un tribunal. Esta documentación no es una opinión legal; consulte a sus propios asesores de cumplimiento y legales.

Consulte también

• Análisis forense — Referencia detallada — derivación de límites de revisión y reglas de clasificación de cambios por objeto.
• Core signing — la superficie autorizada de validación de firma.
• Evidence bundles — artefactos de salida de cadena de custodia.
• NextPDF Enterprise — la superficie completa de funciones de Enterprise.
• Core AST — el modelo de documento analizado.
• Incremental update · Cross-reference table · DSS — términos del glosario.