通过 Connect 对已签署 PDF 进行取证分析

概览

本示例演示如何通过 Connect 传输层使用取证分析工具，重建已签署文档的修订历史，并报告位于签署字节范围之外的内容变更。此工具属于 Enterprise 等级：它通过 class_exists() 探测发现，且只有与服务器一同安装 nextpdf/premium 时才会注册。

此工具会报告观测到的证据：修订版本、字节范围、签名覆盖范围，以及带有置信度分数的启发式影子攻击（shadow-attack）指标。「干净」的判定仅代表在此工具所执行的分析范围内未检测到修改；它并不保证文档未遭篡改。这些发现可以支持调查，但并不构成完整性认证。

安装

composer require nextpdf/server

通过 tools/list 调用确认 Enterprise 取证工具已存在。参见 /connect/tool-catalog/。

概念总览

签名覆盖一段字节范围；签署后的修改可通过将文档与该范围进行比对来检测（ISO 32000-2 §12.8）。增量更新会追加修订版本，而签名并不覆盖在其之后新增的内容（ISO 32000-2 §12.8）。修订链可从交叉引用区段重建（ISO 32000-2 §7.5）。此工具会遍历这些结构以构建时间轴，并标记在签名覆盖范围之外变更的内容。

API 接口

通过 tools/list 对照运行中的注册表验证工具名称。正式记录的目录是 /connect/tool-catalog/。本示例不重述工具数量。

代码示例——快速开始

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

代码示例——生产环境

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

响应内容包含修订时间轴、各修订版本的签名覆盖范围、带有字节偏移量与严重程度的 unsigned_modifications 列表、带有置信度分数的启发式影子攻击指标，以及覆盖范围缺口。请将判定视为需要解读的证据，而不是结论。

边界情况与陷阱

文档中没有签名。 此工具会返回无签名错误。对于未签署文档的验证，请使用标准检查。
加密文档。 请提供解密凭证，否则此调用会失败，而不会进行部分分析。
交叉引用格式错误。 对于严重损坏的文件，重建可能会失败。请先修复 PDF 再重新提交。
工具不存在。 若未安装 nextpdf/premium，Enterprise 取证工具不会注册，且此调用会以未知工具错误失败。

性能

front-matter 预算是一项文档层级的上限。非常大的文档可能会超出此工具的分析大小限制。在此情况下，此工具会返回大小限制错误，而不会静默截断。

安全性注意事项

影子攻击指标属于启发式，并带有置信度分数。它们会标记模式，但并不证明意图。「干净」的判定代表在所执行的分析范围内未检测到修改——它并非防篡改保证。请勿在会向外部传送的日志级别记录文档路径或完整报告。

符合性

声明	条款	reference_id
签署后的修改可对照已签署字节范围检测出来	ISO 32000-2 §12.8
签名不覆盖后续增量更新所新增的内容	ISO 32000-2 §12.8
修订链可从交叉引用区段重建	ISO 32000-2 §7.5

对取证分析的支持并非对文档完整性的认证。证据应由独立鉴定人员解读。

商业场景

取证分析工具属于 Enterprise 等级，且只有与服务器一同安装 nextpdf/premium 时才会注册。

Connect 细节

传输层可用性（MCP / REST / gRPC）

通过共享的工具执行器，可在 MCP tools/call、REST 工具端点与 gRPC 服务上以相同方式调用。

HITL 风险等级

此分析为只读，且默认不需要 approval_required。操作员覆盖只能提高其风险等级。详情参见 /connect/hitl-risk-tiers/。

确认门控 JSON 封装

除非操作员覆盖将其提高为 approval_required，否则此工具不会触发门控。封装与单次使用令牌约定定义于 /connect/hitl-risk-tiers/。

另请参阅

/cookbook/connect/compliance-check/ —— 对照具名标准进行验证。
/cookbook/connect/ltv-health-check/ —— 长期验证材料检查。
/connect/tool-catalog/ —— 各等级工具集的计算方式。
/connect/hitl-risk-tiers/ —— 风险模型与门控。