Forensic analysis of a signed PDF over Connect

Forensic analysis of a signed PDF over Connect

At a glance

Use the forensic-analysis tool over Connect to rebuild a signed document’s revision history and report content changes that occurred outside the signed byte ranges. The tool is Enterprise-tier: it is discovered by a class_exists() probe and registered only when nextpdf/premium is installed alongside the server.

The tool reports observed evidence: revisions, byte ranges, signature coverage, and heuristic shadow-attack indicators with confidence scores. A “clean” verdict means the tool detected no modification within the analysis it performed. It is not a guarantee that the document is untampered. Use the findings to support an investigation; they do not certify integrity.

Install

composer require nextpdf/server

Confirm that the Enterprise forensic tool is present with a tools/list call. See /connect/tool-catalog/.

Conceptual overview

A signature covers a byte range. You can detect modification after signing by comparing the document against that range (ISO 32000-2 §12.8). Incremental updates append revisions, and a signature does not cover content added after it (ISO 32000-2 §12.8). The revision chain is reconstructable from the cross-reference sections (ISO 32000-2 §7.5). The tool walks these structures to build a timeline and flag content changed outside signature coverage.

API surface

Verify tool names against the running registry with tools/list. The catalog of record is /connect/tool-catalog/. This recipe does not repeat a tool count.

Code sample — Quick start

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

Code sample — Production

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

The response includes a revision timeline, per-revision signature coverage, an unsigned_modifications list with byte offsets and severity, heuristic shadow-attack indicators with confidence scores, and coverage gaps. Treat the verdict as evidence to interpret, not as a conclusion.

Edge cases & gotchas

• No signatures in the document. The tool returns a no-signatures error. Use the standards check to validate an unsigned document.
• Encrypted document. Supply decryption credentials, or the call fails instead of running a partial analysis.
• Malformed cross-reference. Reconstruction may fail on a severely corrupted file. Repair the PDF before you re-submit it.
• Tool absent. Without nextpdf/premium, the Enterprise forensic tool is not registered, and the call fails with an unknown-tool error.

Performance

The front-matter budget is a documentation cap. Very large documents may exceed the tool’s analysis size limit. In that case, the tool returns a size-limit error instead of truncating silently.

Security notes

The shadow-attack indicators are heuristic and include confidence scores. They flag patterns; they do not prove intent. A “clean” verdict means the tool detected no modification within the analysis performed. It is not a tamper-proof guarantee. Do not log the document path or the full report at an externally shipped log level.

Conformance

Claim	Clause	reference_id
Modification after signing is detectable against the signed byte range	ISO 32000-2 §12.8
A signature does not cover content added by a later incremental update	ISO 32000-2 §12.8
The revision chain is reconstructable from cross-reference sections	ISO 32000-2 §7.5

Support for forensic analysis is not a certification of document integrity. An independent examiner interprets the evidence.

Commercial context

The forensic-analysis tool is Enterprise-tier and registers only when nextpdf/premium is installed alongside the server.

Connect specifics

Transport availability (MCP / REST / gRPC)

Invoke the tool the same way over Model Context Protocol (MCP) tools/call, the Representational State Transfer (REST) tool endpoint, and the gRPC service through the shared tool executor.

HITL risk tier

The analysis is read-only and not approval_required by default. An operator override can only raise its risk level. See /connect/hitl-risk-tiers/ for details.

Confirmation gate JSON envelope

The tool does not trigger the gate unless an operator override raises it to approval_required. The envelope and single-use token contract is in /connect/hitl-risk-tiers/.

See also

• /cookbook/connect/compliance-check/ — validate against named standards.
• /cookbook/connect/ltv-health-check/ — inspect long-term validation material.
• /connect/tool-catalog/ — compute the tool set for each tier.
• /connect/hitl-risk-tiers/ — review the risk model and the gate.