Analiza śledcza

W skrócie

NextPDF Enterprise Forensics odczytuje historię aktualizacji przyrostowych pliku PDF i wytwarza ustrukturyzowany raport tylko do odczytu zawierający rewizje, sklasyfikowane zdarzenia oraz zmiany per obiekt. Wspiera procesy analizy śledczej. Nie jest pieczęcią odporną na manipulacje i nie stwierdza, że dokument jest autentyczny ani niezmieniony.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Instalacja

composer require nextpdf/enterprise:^3

Przegląd koncepcyjny

Plik PDF można zaktualizować, dopisując zmiany na końcu pliku, zamiast go przepisywać. Każda aktualizacja dodaje nową sekcję odwołań krzyżowych oraz nowy trailer, a pierwotne bajty pozostają na miejscu — ISO 32000-2:2020 §7.5.6. Gdy obiekt jest zmieniany, aktualizacja dopisuje nową kopię, a sekcja odwołań krzyżowych aktualizacji rejestruje przesunięcie bajtowe, które nadpisuje starsze przesunięcie; czytnik rozwiązuje najnowszą kopię — ISO 32000-2:2020 §7.5.6. Początkowa struktura pliku może zostać zmodyfikowana przez późniejsze aktualizacje — ISO 32000-2:2020 §7.5.4. Sekcja odwołań krzyżowych aktualizacji wymienia wyłącznie obiekty, które zostały dodane, zmodyfikowane lub usunięte w tej aktualizacji — ISO 32000-2:2020 §7.5.5.

Analizator odczytuje tę warstwową strukturę. Parsuje tabelę odwołań krzyżowych każdej rewizji, wyprowadza granice bajtowe rewizji i porównuje wpisy każdej rewizji z następną starszą rewizją, aby sklasyfikować każdy obiekt jako dodany, zmodyfikowany lub usunięty. Następnie grupuje zmiany obiektów w zdarzenia wyższego poziomu: dodano podpis, zaktualizowano katalog dokumentu, pojawił się słownik szyfrowania lub dodano, zmodyfikowano albo usunięto zbiór obiektów. Wyjściem jest jeden obiekt raportu, który niesie liczbę rewizji, łączny rozmiar, listę podsumowań per rewizja, sklasyfikowaną oś czasu zdarzeń oraz listę zmian per obiekt.

Analizator jest tylko do odczytu. Wykrywa istnienie rewizji podpisu na podstawie znaczników strukturalnych; nie waliduje żadnego podpisu, nie przelicza żadnego skrótu ani nie sprawdza żadnego certyfikatu. Walidacja podpisu to osobna możliwość Core. Wytworzony raport to strukturalny opis historii aktualizacji w postaci sparsowanej; nie jest rozstrzygnięciem, że dokument jest autentyczny, że zmiana była nieautoryzowana ani że każda modyfikacja została wykryta. Traktuj raport jako wykrywanie śladów manipulacji w zakresie sprawdzonym względem widoku łańcucha rewizji przez parser, a nie jako gwarancję śledczą ani poświadczenie dopuszczalne przed sądem.

Dlaczego działa w ten sposób

Analizator celowo zatrzymuje się na strukturze. Raportuje, co zawiera łańcuch rewizji, i nigdy nie twierdzi, że zmiana była autoryzowana ani że podpis jest ważny. Obecność strukturalna i ważność kryptograficzna to różne twierdzenia; ich połączenie pozwoliłoby wywołującemu pomylić ślady manipulacji z gwarancją. Ważność podpisu pozostaje zatem przy jednej powierzchni podpisywania Core, z którą Forensics się komponuje, a nie ją powiela. Raport to metadane strukturalne serializowalne do JSON, więc SIEM przyjmuje historię edycji bez dotykania treści dokumentu. Kontekst projektowy: Aktualizacje przyrostowe i dlaczego mają znaczenie.

Powierzchnia API

Typ	Rodzaj	Rola	Stabilność	Od wersji
ForensicAnalyzer	class	Parsuje plik PDF i zwraca raport śledczy (statyczne analyze)	stable	1.10.0
ForensicReport	class	Wynik analizy; JsonSerializable na potrzeby eksportu do SIEM	stable	1.10.0
RevisionSummary	class	Fakty per rewizja: liczba obiektów, rozmiar, granice bajtowe, flagi obecności	stable	1.10.0
ForensicEvent	class	Pojedyncze sklasyfikowane zdarzenie z listą obiektów, których dotyczy	stable	1.10.0
ForensicEventType	enum	Kategorie zdarzeń (dodano podpis, zaktualizowano katalog, dodano obiekty i inne)	stable	1.10.0
ObjectChange	class	Zapis zmiany jednego obiektu między dwiema rewizjami	stable	1.10.0
ObjectChangeType	enum	Added, Modified lub Deleted	stable	1.10.0

ForensicReport udostępnia hasIncrementalUpdates(), hasAnySignature(), getEventsByType(), getChangesForRevision() oraz jsonSerialize(). Flaga hasSignature w podsumowaniu rewizji to sygnał obecności strukturalnej, a nie wynik ważności.

Przykład kodu — szybki start

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() raportuje, że rewizja podpisu jest obecna w strukturze. Nie stwierdza, że podpis jest ważny.

Przykład kodu — produkcja

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

Zapis logu niesie wyłącznie liczby i rozmiary. Nie niesie tekstu dokumentu. Blok catch ponownie zgłasza wyjątek; nie połyka niepowodzenia parsowania.

Przypadki brzegowe i pułapki

• Dokument z jedną rewizją nie ma historii przyrostowej. Lista zmian jest pusta; nie jest to dowód autentyczności.
• Zdarzenie SignatureAdded oznacza, że rewizja podpisu jest strukturalnie obecna. Nie jest wynikiem ważności podpisu. Zwaliduj podpis za pomocą powierzchni podpisywania Core.
• Ponowne użycie obiektu jest normalne: zaktualizowany obiekt zachowuje swój numer obiektu, a nowa kopia jest dopisywana. Analizator raportuje to jako Modified, a nie jako usunięcie i ponowne utworzenie.
• Klasyfikacja Deleted to przejście na wpis wolny w łańcuchu odwołań krzyżowych. Czytnik może nadal rozwiązać starszą kopię tego obiektu; usunięcie na poziomie struktury nie gwarantuje nieodtwarzalności.
• Analizator raportuje to, co zaobserwował parser. Dokument spreparowany tak, aby zmylić parser, może dać raport niezgodny z widokiem innego narzędzia. Raport nie jest twierdzeniem, że wykryto każdą modyfikację.
• Wejście jest ograniczone. Dokument zbyt duży lub o nadmiernej liczbie rewizji zawodzi fail-closed z typizowanym wyjątkiem parsowania, zamiast zużywać nieograniczoną pamięć.

Wydajność

Koszt analizy skaluje się wraz z liczbą rewizji oraz liczbą obiektów, a nie ze złożonością renderowanej strony. Budżet zegarowy 1500 ms obejmuje typowy wielorewizyjny dokument biznesowy. Profil odtwarzalności to structural: raport jest deterministyczny dla danego wejścia, ale bezwzględne przesunięcia bajtowe odzwierciedlają dokładny plik wejściowy i nie są przenośne między ponownie zapisanymi kopiami.

Uwagi dotyczące bezpieczeństwa

Analizator jest tylko do odczytu i nigdy nie zapisuje do wejścia. Jest powierzchnią analityczną, a nie transformacyjną. Wykrywa istnienie znaczników podpisu i szyfrowania, ale nie wykonuje żadnej operacji kryptograficznej, więc nie formułuje żadnego twierdzenia o FIPS. Raport opisuje sparsowaną historię aktualizacji; nie jest twierdzeniem o autentyczności i nie wolno go przedstawiać jako odpornego na manipulacje, gwarantowanego śledczo ani dopuszczalnego przed sądem. To operator wyciąga wnioski; biblioteka raportuje strukturę.

Rezydencja danych i środki ograniczające dla danych osobowych (PII)

Analiza działa w obrębie procesu na hoście przechowującym plik PDF. Żadna treść dokumentu nie opuszcza hosta. Raport niesie numery obiektów, indeksy rewizji, rozmiary, granice bajtowe oraz kategorie zdarzeń — metadane strukturalne, a nie tekst dokumentu ani wykryte dane osobowe. To, czy wejściowy plik PDF lub sam raport zawiera dane osobowe i gdzie każde z nich jest przechowywane, jest odpowiedzialnością wdrożenia poza granicą biblioteki.

Bezpieczna telemetria i czyszczenie logów

Biblioteka zgłasza typizowane wyjątki z komunikatami strukturalnymi i nie umieszcza bajtów dokumentu w tekście wyjątku. Wdrożenie, które loguje wokół analizy, powinno logować liczby i kategorie z raportu — jak pokazano w przykładzie produkcyjnym — i nie może logować surowego ładunku PDF do logów ani backendu APM. Bezpiecznym artefaktem do przekazania do SIEM jest raport JSON.

Zachowanie w trybie FIPS

W tym module nie zachodzi żadna operacja kryptograficzna, więc nie ma zachowania właściwego dla trybu FIPS. Walidacja podpisu, która jest kryptograficzna, to osobna możliwość Core i jest udokumentowana w tamtym miejscu.

Zgodność ze standardami

Twierdzenie	Standard	Klauzula
Późniejsze aktualizacje dopisują dodatkowe elementy na końcu pliku; pierwotna struktura jest modyfikowana przez późniejsze aktualizacje.	ISO 32000-2:2020	§7.5.6
Zaktualizowany obiekt jest dopisywany jako nowa kopia, a wpis odwołania krzyżowego aktualizacji nadpisuje wcześniejsze przesunięcie bajtowe; czytnik rozwiązuje najnowszą kopię.	ISO 32000-2:2020	§7.5.6
Początkowa struktura pliku może zostać zmodyfikowana przez późniejsze aktualizacje.	ISO 32000-2:2020	§7.5.4
Sekcja odwołań krzyżowych aktualizacji zawiera wpisy wyłącznie dla obiektów dodanych, zmodyfikowanych lub usuniętych.	ISO 32000-2:2020	§7.5.5
Słownik podpisu rejestruje to, co jest podpisane.	ISO 32000-2:2020	§12.8.1
ByteRange definiuje zakres bajtów objęty podpisem (walidacja podpisu to osobna możliwość Core).	ISO 32000-2:2020	§12.8.1
Document Security Store przechowuje materiał walidacji długoterminowej w późniejszej rewizji.	ISO 32000-2:2020	§12.8.4

Wszystkie klauzule są sparafrazowane. NextPDF nie odtwarza tekstu normatywnego. W sprawie miarodajnego brzmienia skonsultuj się z opublikowanym standardem. NextPDF nie formułuje żadnego twierdzenia o certyfikacji śledczej; raport opisuje sparsowaną strukturę aktualizacji, a nie certyfikowane rozstrzygnięcie integralności dokumentu.

Kontrakt zachowania

• Analizator jest tylko do odczytu: nigdy nie zapisuje do dokumentu wejściowego i nie wykonuje żadnej operacji kryptograficznej.
• Parsuje tabelę odwołań krzyżowych każdej rewizji, wyprowadza granice bajtowe rewizji i klasyfikuje każdy obiekt jako dodany, zmodyfikowany lub usunięty, następnie grupuje zmiany w sklasyfikowaną oś czasu zdarzeń.
• Zdarzenie SignatureAdded oznacza, że rewizja podpisu jest strukturalnie obecna; nie jest wynikiem ważności podpisu — walidacja to osobna możliwość Core.
• Dokument z jedną rewizją ma pustą listę zmian (nie jest to dowód autentyczności); klasyfikacja Deleted to przejście na wpis wolny, a nie gwarantowana nieodtwarzalność.
• Wejście jest ograniczone: dokument zbyt duży lub o nadmiernej liczbie rewizji zawodzi fail-closed z typizowanym wyjątkiem parsowania. Raport to wykrywanie śladów manipulacji w zakresie sprawdzonym, a nie gwarancja śledcza ani poświadczenie dopuszczalne przed sądem.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Rozwiązanie awaryjne w Core

NextPDF Core (Apache-2.0) nie ma analizatora śledczego historii rewizji — żadnego; ta możliwość nie ma odpowiednika na poziomie Core. Core dostarcza miarodajną powierzchnię walidacji podpisu, z którą analizator się komponuje, ale której nie zastępuje.

Rozwiązanie awaryjne w Pro

NextPDF Pro nie ma analizatora śledczego historii rewizji — żadnego; ta możliwość nie ma odpowiednika na poziomie Pro. Raportowanie rewizji i zmian per obiekt tylko do odczytu oraz raport SIEM serializowalny do JSON są dostarczane wyłącznie w pakiecie nextpdf/enterprise.

Uwaga o granicy Enterprise

Parser rewizji, klasyfikacja zmian oraz oś czasu zdarzeń są opisane na poziomie zachowania. Mechanizmy wewnętrzne parsera oraz wszelkie szczegóły wewnętrznej klasyfikacji są poza zakresem powierzchni publicznej. Ważność podpisu celowo nie jest tu w zakresie — należy do odpowiedzialności powierzchni podpisywania Core.

Granica wdrożenia

Analiza działa w obrębie procesu na hoście przechowującym plik PDF; żadna treść dokumentu nie opuszcza hosta. To, czy wejściowy plik PDF lub raport zawiera dane osobowe i gdzie każde z nich jest przechowywane, jest odpowiedzialnością wdrożenia poza granicą biblioteki. Operator wyciąga wnioski z raportu; biblioteka raportuje strukturę i nie stwierdza autentyczności dokumentu.

Granica zgodności prawnej

Do powierzchni Forensics nie ma zastosowania żadne ograniczenie kontroli eksportu. Raportu nie wolno przedstawiać jako odpornego na manipulacje, gwarantowanego śledczo ani dopuszczalnego przed sądem. Niniejsza dokumentacja nie stanowi opinii prawnej; skonsultuj się z własnymi doradcami ds. zgodności i prawnymi.

Zobacz także

• Analiza śledcza — pełna referencja — wyprowadzanie granic rewizji oraz reguły klasyfikacji zmian obiektów.
• Core signing — miarodajna powierzchnia walidacji podpisu.
• Evidence bundles — artefakty wyjściowe łańcucha pieczy.
• NextPDF Enterprise — pełna powierzchnia funkcji Enterprise.
• Core AST — model sparsowanego dokumentu.
• Aktualizacja przyrostowa · Tabela odwołań krzyżowych · DSS — terminy ze słownika.