Enterprise edition

Forensics

At a glance

NextPDF Enterprise Forensics reads the incremental-update history of a PDF and produces a structured, read-only report of revisions, classified events, and per-object changes. It supports forensic analysis workflows. It is not a tamper-proof seal and does not assert that a document is authentic or unaltered.

Availability & licensing

This capability ships in NextPDF Enterprise (nextpdf/enterprise) and activates with an Enterprise-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

Install

composer require nextpdf/enterprise:^3

Conceptual overview

A PDF can be updated by appending changes to the end of the file rather than rewriting it. Each update adds a new cross-reference section and a new trailer, and the original bytes are left in place — ISO 32000-2:2020 §7.5.6. When an object is changed, the update appends a new copy and the update’s cross-reference section records a byte offset that overrides the older offset; a reader resolves the most recent copy — ISO 32000-2:2020 §7.5.6. The initial file structure may be modified by later updates — ISO 32000-2:2020 §7.5.4. An update’s cross-reference section lists only the objects that were added, modified, or deleted in that update — ISO 32000-2:2020 §7.5.5.

The analyzer reads this layered structure. It parses each revision’s cross-reference table, derives revision byte boundaries, and compares each revision’s entries against the next older revision to classify every object as added, modified, or deleted. It then groups object changes into higher-level events: a signature was added, the document catalog was updated, an encryption dictionary appeared, or a set of objects was added, modified, or removed. The output is one report object that carries a revision count, total size, a per-revision summary list, a classified event timeline, and the per-object change list.

The analyzer is read-only. It detects the existence of a signature revision from structural markers; it does not validate any signature, recompute any digest, or check any certificate. Signature validation is a separate Core capability. A produced report is a structural description of the update history as parsed; it is not a determination that a document is authentic, that a change was unauthorized, or that every modification was detected. Treat the report as tamper-evidence detection as tested against the parser’s view of the revision chain, not as a forensic guarantee or a court-admissible attestation.

Why it works this way

The analyzer deliberately stops at structure. It reports what the revision chain contains, and never asserts that a change was authorized or a signature valid. Structural presence and cryptographic validity are different claims; merging them would let a caller mistake tamper-evidence for a guarantee. Signature validity therefore stays with the single Core signing surface, which Forensics composes with rather than duplicates. The report is JSON-serializable structural metadata, so a SIEM ingests the edit history without touching document content. Design background: Incremental updates and why they matter.

API surface

Type	Kind	Role	Stability	Since
`ForensicAnalyzer`	class	Parses a PDF and returns a forensic report (static `analyze`)	stable	1.10.0
`ForensicReport`	class	The analysis result; `JsonSerializable` for SIEM export	stable	1.10.0
`RevisionSummary`	class	Per-revision facts: object count, size, byte boundaries, presence flags	stable	1.10.0
`ForensicEvent`	class	One classified event with an affected-object list	stable	1.10.0
`ForensicEventType`	enum	Event categories (signature added, catalog updated, objects added, and others)	stable	1.10.0
`ObjectChange`	class	One object’s change record across two revisions	stable	1.10.0
`ObjectChangeType`	enum	Added, Modified, or Deleted	stable	1.10.0

ForensicReport exposes hasIncrementalUpdates(), hasAnySignature(), getEventsByType(), getChangesForRevision(), and jsonSerialize(). The hasSignature flag on a revision summary is a structural presence signal, not a validity result.

Code sample — Quick start

<?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() reports that a signature revision is present in the structure. It does not state that the signature is valid.

Code sample — Production

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

The log record carries counts and sizes only. It does not carry document text. The catch block rethrows; it does not swallow a parse failure.

Edge cases & gotchas

A single-revision document has no incremental history. The change list is empty; this is not evidence of authenticity.
A SignatureAdded event means a signature revision is structurally present. It is not a signature-validity result. Validate the signature with the Core signing surface.
Object reuse is normal: an updated object keeps its object number and a new copy is appended. The analyzer reports this as Modified, not as removal and re-creation.
A Deleted classification is a free-entry transition in the cross-reference chain. A reader may still resolve an older copy of that object; deletion at the structure level is not guaranteed unrecoverability.
The analyzer reports what the parser observed. A document crafted to confuse a parser may yield a report that does not match a different tool’s view. The report is not a claim that every modification was detected.
Input is bounded. An oversized or excessively multi-revision document fails closed with a typed parse exception rather than consuming unbounded memory.

Performance

Analysis cost scales with the revision count and the object count, not with rendered page complexity. The 1500 ms wall budget covers a typical multi-revision business document. The reproducibility profile is structural: the report is deterministic for a given input, but absolute byte offsets reflect the exact input file and are not portable across re-saved copies.

Security notes

The analyzer is read-only and never writes to the input. It is an analytical surface, not a transformational one. It detects the existence of signature and encryption markers but performs no cryptographic operation, so it makes no FIPS claim. A report describes the parsed update history; it is not an authenticity assertion and must not be presented as tamper-proof, forensically guaranteed, or court-admissible. An operator draws conclusions; the library reports structure.

Data residency & PII mitigations

Analysis runs in-process on the host that holds the PDF. No document content leaves the host. The report carries object numbers, revision indices, sizes, byte boundaries, and event categories — structural metadata, not document text or detected personal data. Whether the input PDF or the report itself contains personal data, and where each is stored, is a deployment responsibility outside the library’s boundary.

Safe telemetry & log scrubbing

The library raises typed exceptions with structural messages and does not place document bytes into exception text. A deployment that logs around analysis should log the report’s counts and categories — as shown in the production sample — and must not log the raw PDF payload to logs or an APM backend. The JSON report is the safe artifact to forward to a SIEM.

FIPS-mode behavior

No cryptographic operation occurs in this module, so there is no FIPS-mode-specific behavior. Signature validation, which is cryptographic, is a separate Core capability and is documented there.

Conformance

Claim	Standard	Clause
Later updates append additional elements to the end of the file; the original structure is modified by later updates.	ISO 32000-2:2020	§7.5.6
An updated object is appended as a new copy and the update’s cross-reference entry overrides the prior byte offset; the reader resolves the most recent copy.	ISO 32000-2:2020	§7.5.6
The initial file structure may be modified by later updates.	ISO 32000-2:2020	§7.5.4
An update’s cross-reference section contains entries only for added, modified, or deleted objects.	ISO 32000-2:2020	§7.5.5
The signature dictionary records what is signed.	ISO 32000-2:2020	§12.8.1
ByteRange defines the byte span the signature covers (signature validation is a separate Core capability).	ISO 32000-2:2020	§12.8.1
A Document Security Store holds long-term validation material in a later revision.	ISO 32000-2:2020	§12.8.4

All clauses are paraphrased. NextPDF does not reproduce normative text. Consult the published standard for the authoritative wording. NextPDF makes no forensic-certification claim; the report describes the parsed update structure, not a certified determination of document integrity.

Behavior contract

The analyzer is read-only: it never writes to the input document and performs no cryptographic operation.
It parses each revision’s cross-reference table, derives revision byte boundaries, and classifies every object as added, modified, or deleted, then groups changes into a classified event timeline.
A SignatureAdded event means a signature revision is structurally present; it is not a signature-validity result — validation is a separate Core capability.
A single-revision document has an empty change list (not evidence of authenticity); a Deleted classification is a free-entry transition, not guaranteed unrecoverability.
Input is bounded: an oversized or excessively multi-revision document fails closed with a typed parse exception. The report is tamper-evidence detection as tested, not a forensic guarantee or court-admissible attestation.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

Core fallback

NextPDF Core (Apache-2.0) has no revision-history forensic analyzer — none; this capability has no Core-tier equivalent. Core supplies the authoritative signature-validation surface, which the analyzer composes with but does not replace.

Pro fallback

NextPDF Pro has no revision-history forensic analyzer — none; this capability has no Pro-tier equivalent. The read-only revision and per-object change reporting and the JSON-serializable SIEM report ship in the nextpdf/enterprise package only.

Enterprise boundary note

The revision parser, the change classification, and the event timeline are described at the behavior level. The parser internals and any internal classification detail are out of scope for the public surface. Signature validity is deliberately not in scope here — it is the Core signing surface’s responsibility.

Deployment boundary

Analysis runs in-process on the host that holds the PDF; no document content leaves the host. Whether the input PDF or the report contains personal data, and where each is stored, is a deployment responsibility outside the library’s boundary. The operator draws conclusions from the report; the library reports structure and does not assert document authenticity.

Legal-compliance boundary

No export-control restriction applies to the Forensics surface. The report must not be presented as tamper-proof, forensically guaranteed, or court-admissible. This documentation is not a legal opinion; consult your own compliance and legal advisers.