Analisi forense di un PDF firmato tramite Connect

In sintesi

Questa ricetta usa lo strumento di analisi forense tramite i trasporti di Connect per ricostruire la cronologia delle revisioni di un documento firmato e segnalare le modifiche al contenuto avvenute al di fuori degli intervalli di byte firmati. Lo strumento è di livello Enterprise: viene rilevato tramite una verifica class_exists() ed è registrato solo quando nextpdf/premium è installato insieme al server.

Lo strumento restituisce le prove osservate — revisioni, intervalli di byte, copertura della firma e indicatori euristici di attacchi shadow con punteggi di affidabilità. Un verdetto «pulito» indica che, nell’ambito dell’analisi eseguita dallo strumento, non sono state rilevate modifiche; non garantisce che il documento non sia stato manomesso. I risultati supportano un’indagine, ma non certificano l’integrità.

Installazione

composer require nextpdf/server

Confermare che lo strumento forense Enterprise sia disponibile con una chiamata tools/list. Vedere /connect/tool-catalog/.

Panoramica concettuale

Una firma copre un intervallo di byte; le modifiche successive alla firma sono rilevabili confrontando il documento con tale intervallo (ISO 32000-2 §12.8). Gli aggiornamenti incrementali aggiungono revisioni, e una firma non copre il contenuto aggiunto dopo di essa (ISO 32000-2 §12.8). La catena delle revisioni può essere ricostruita dalle sezioni di riferimento incrociato (ISO 32000-2 §7.5). Lo strumento attraversa queste strutture per costruire una cronologia e segnalare i contenuti modificati al di fuori della copertura della firma.

Superficie API

Verificare i nomi degli strumenti rispetto al registro in esecuzione con tools/list. Il catalogo di riferimento è /connect/tool-catalog/. Questa ricetta non replica il conteggio degli strumenti.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

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 risposta include una cronologia delle revisioni, la copertura della firma per ciascuna revisione, un elenco unsigned_modifications con offset di byte e gravità, indicatori euristici di attacchi shadow con punteggi di affidabilità e lacune nella copertura. Considerare il verdetto una prova da interpretare, non una conclusione.

Casi limite e insidie

Nessuna firma nel documento. Lo strumento restituisce un errore per assenza di firme. Usare il controllo di conformità agli standard per la validazione dei documenti non firmati.
Documento cifrato. Fornire le credenziali di decifratura; in caso contrario, la chiamata fallisce anziché eseguire un’analisi parziale.
Riferimento incrociato non valido. La ricostruzione può fallire su file gravemente danneggiati. Riparare il PDF prima di inviarlo di nuovo.
Strumento assente. Senza nextpdf/premium, lo strumento forense Enterprise non viene registrato e la chiamata fallisce con un errore di strumento sconosciuto.

Prestazioni

Il budget indicato nel front matter è un limite documentale. Documenti molto grandi possono superare il limite di dimensione dell’analisi dello strumento. In tal caso, lo strumento restituisce un errore di limite di dimensione anziché eseguire un troncamento silenzioso.

Note sulla sicurezza

Gli indicatori di attacchi shadow sono euristici e riportano punteggi di affidabilità. Segnalano pattern, ma non dimostrano l’intenzione. Un verdetto «pulito» significa che, nell’ambito dell’analisi eseguita, non è stata rilevata alcuna modifica — non è una garanzia di inviolabilità. Non registrare il percorso del documento o il report completo a un livello di log esposto all’esterno.

Conformità

Dichiarazione	Clausola	reference_id
Le modifiche successive alla firma sono rilevabili rispetto all’intervallo di byte firmato	ISO 32000-2 §12.8
Una firma non copre il contenuto aggiunto da un successivo aggiornamento incrementale	ISO 32000-2 §12.8
La catena delle revisioni è ricostruibile dalle sezioni di riferimento incrociato	ISO 32000-2 §7.5

Il supporto per l’analisi forense non certifica l’integrità del documento. Le prove devono essere interpretate da un esaminatore indipendente.

Contesto commerciale

Lo strumento di analisi forense è di livello Enterprise e viene registrato solo quando nextpdf/premium è installato insieme al server.

Specifiche di Connect

Disponibilità dei trasporti (MCP / REST / gRPC)

Viene invocato allo stesso modo tramite MCP tools/call, l’endpoint dello strumento REST e il servizio gRPC, usando l’esecutore di strumenti condiviso.

Livello di rischio HITL

L’analisi è di sola lettura e, per impostazione predefinita, non è approval_required. Un override dell’operatore può solo aumentarne il livello di rischio. Per i dettagli, vedere /connect/hitl-risk-tiers/.

Envelope JSON del gate di conferma

Lo strumento non attiva il gate, salvo che un override dell’operatore lo elevi a approval_required. Il contratto dell’envelope e del token monouso si trova in /connect/hitl-risk-tiers/.

Vedere anche

/cookbook/connect/compliance-check/ — validare rispetto a standard specifici.
/cookbook/connect/ltv-health-check/ — ispezionare il materiale di validazione a lungo termine.
/connect/tool-catalog/ — calcolare l’insieme di strumenti per ciascun livello.
/connect/hitl-risk-tiers/ — il modello di rischio e il gate.