Audit: deterministischer Export von Compliance-Nachweisen

Auf einen Blick

Das Audit-Modul wandelt den Konformitäts-Claims-Datensatz der Engine in ein deterministisches, PII-bereinigtes Nachweis-Bundle um, das für Compliance-Auditoren geeignet ist. Es sortiert alle Sammlungen für eine byte-stabile Ausgabe, validiert das Bundle gegen ein Schema und kann es auf eine stabile Version projizieren.

Stabilität: experimentell. Der Exporter selbst ist deterministisch und gut getestet, aber der vorgelagerte claims.json-Datensatz, den er verarbeitet, ist eine noch in Arbeit befindliche Konformitätsmatrix (ihr eigener _status spiegelt das wider). Bis die Evidence-Pipeline GA erreicht hat, behandeln Sie die Ausgabe dieses Moduls als technischen Nachweis, nicht als zertifizierte Attestierung.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

AuditExporter ist der einzige Einstiegspunkt. buildBundle() nimmt einen dekodierten Claims-Datensatz und einen AuditExportContext entgegen und gibt ein AuditExportBundle zurück. buildBundleFromFile() ist die komfortable Methode zum Laden aus einer Datei. encode() serialisiert das Bundle nach JSON. Die Erstellung ist rein funktional. Mit einem festen AuditExportContext::generatedAt (zum Beispiel über SOURCE_DATE_EPOCH) und einem stabilen Claims-Datensatz ist die Ausgabe über alle Durchläufe hinweg byte-identisch, weil claims[] nach (standard, clause_id), evidence[] nach ref_id und clause_hashes[] nach clause_id sortiert werden. Deshalb ist das Reproduzierbarkeitsprofil bitwise.

Das Bundle ist ein typisierter Baum: AuditExportClaim (ein Konformitäts-Claim), AuditExportEvidence (der unterstützende Nachweisdatensatz), AuditExportClauseHash (die Prüfsumme des Klauselinhalts) und AuditExportContext (der Generierungskontext). Jeder Typ stellt für die Serialisierung ein toArray() bereit.

Das Modul ist datenschutzfreundlich voreingestellt (Privacy by Default). Der Konstruktor richtet einen DefaultPiiSanitiser (eine PiiSanitiser-Implementierung) ein, der Strings mit Nachweis-Metadaten vor der Serialisierung bereinigt. Ein anderer Sanitiser kann injiziert werden. Der Exporter validiert Klausel-Hashes, Nachweis-Prüfsummen und RAG-Zitatanker gegen ein striktes Muster für einen 64-stelligen SHA-256-Hexwert in Kleinbuchstaben und gibt eine strukturierte Warnung aus (statt den Eintrag stillschweigend zu verwerfen), wenn einer Klausel ein gültiger Hash oder Evaluator-Metadaten fehlen. validateAgainstSchema() prüft das erstellte Bundle. projectToV1() erzeugt eine stabile v1-Projektion. Das Design des Exporters ist auf OWASP ASVS V8.3, NIST CSF 2.0 PR.PT-1, NIST SP 800-53 r5 AU-2/AU-3 und ISO/IEC 27001 A.12.4 ausgerichtet — dies sind im Quellcode dokumentierte Design-Ausrichtungen, keine chunk-fixierten normativen Aussagen.

API-Oberfläche

Klasse	Wichtige Mitglieder	Rolle
`AuditExporter`	`buildBundle()`, `buildBundleFromFile()`, `encode()`, `validateAgainstSchema()`, `projectToV1()`	Deterministischer Bundle-Builder/-Validator
`AuditExportBundle`	`toArray()`	Das zusammengestellte Nachweis-Bundle
`AuditExportClaim`	`toArray()`	Ein Konformitäts-Claim-Datensatz
`AuditExportEvidence`	`toArray()`	Ein unterstützender Nachweisdatensatz
`AuditExportClauseHash`	`toArray()`	Ein Datensatz mit der Prüfsumme des Klauselinhalts
`AuditExportContext`	`GENERATOR_VERSION`	Generierungskontext (Zeitstempel für Determinismus festlegen)
`PiiSanitiser` (Schnittstelle)	`sanitise(string): string`	Austauschbarer Scrubber für Nachweis-Metadaten (`@since 5.2.0`)
`DefaultPiiSanitiser`	`sanitise()`	Datenschutzfreundlich voreingestellter Sanitiser (`@since 5.2.0`)

Führen Sie composer docs:generate-api-php -- --module=Audit aus, um die vollständige PHPDoc-Tabelle zu erhalten.

Codebeispiel — Schnellstart

Erzeugen und kodieren Sie ein Bundle aus einer Claims-Datei.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Audit\AuditExportContext;
use NextPDF\Audit\AuditExporter;

$exporter = new AuditExporter();

$bundle = $exporter->buildBundleFromFile(
    '/srv/nextpdf/claims.json',
    new AuditExportContext(/* pin generatedAt for determinism */),
);

file_put_contents('/srv/out/audit-bundle.json', $exporter->encode($bundle));

Codebeispiel — Produktion

Validieren Sie das Bundle und behandeln Sie Schema- oder Hash-Warnungen als hartes Gate.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Audit\AuditExportContext;
use NextPDF\Audit\AuditExporter;
use Psr\Log\LoggerInterface;

final readonly class EvidenceGate
{
    public function __construct(
        private AuditExporter $exporter,
        private LoggerInterface $logger,
    ) {}

    /** @param array<string, mixed> $claims Decoded claims dataset. */
    public function export(array $claims, AuditExportContext $context): string
    {
        $bundle = $this->exporter->buildBundle($claims, $context);
        $errors = $this->exporter->validateAgainstSchema($bundle->toArray());

        if ($errors !== []) {
            $this->logger->error('Audit bundle failed schema validation.', ['errors' => $errors]);

            throw new \RuntimeException('Audit evidence bundle is not schema-valid; refusing to publish.');
        }

        return $this->exporter->encode($bundle);
    }
}

Sonderfälle & Fallstricke

Determinismus erfordert ein festgelegtes AuditExportContext::generatedAt. Ohne festgelegten Wert variiert der Zeitstempel, und die Ausgabe ist nicht byte-stabil, was das bitwise-Profil zunichtemacht.
Eine Klausel ohne gültigen 64-stelligen Hex-clause_hash oder ohne Evaluator-Metadaten wird mit einer strukturierten Warnung übersprungen, nicht stillschweigend aufgenommen. Prüfen Sie die Warnungen; eine übersprungene Klausel bedeutet fehlenden Nachweis, kein Bestehen.
Der Standard-PiiSanitiser läuft, sofern Sie keinen anderen injizieren. Das Deaktivieren der Bereinigung ist eine bewusste Entscheidung mit Datenschutzfolgen — tun Sie dies nicht für einen regulierten Export.
validateAgainstSchema() ist nur beratend, sofern Sie nicht auf den Rückgabewert reagieren. Behandeln Sie ein nicht leeres Ergebnis in der Produktion als veröffentlichungsblockierenden Fehler.
Das Bundle spiegelt den Reifegrad des Eingabedatensatzes wider. Ein WIP-Claims-Datensatz erzeugt ein WIP-Bundle; der Exporter wertet die Nachweisqualität nicht auf.

Performance

Die Erstellung ist linear in der Anzahl der Claims- und Nachweisdatensätze und wird vom Sortieren dominiert. In buildBundle() findet keine E/A statt (der Aufrufer ist für den Dateizugriff verantwortlich). Die standardmäßige Referenzlast liegt deutlich innerhalb des Budgets von 1500 ms Wall-Zeit / 64 MB Spitzenwert. Das Reproduzierbarkeitsprofil ist bei festgelegtem Kontext und stabiler Eingabe per Design bitwise.

Sicherheitshinweise

Dieses Modul verarbeitet Compliance-Nachweise, die sensible Metadaten enthalten können. Die PII-Bereinigung ist standardmäßig aktiviert (Ausrichtung an DSGVO Art. 32). Lassen Sie sie für jedes extern geteilte Bundle aktiviert. Der Exporter validiert jede Prüfsumme und jeden Zitatanker gegen ein striktes SHA-256-Muster, sodass ein fehlerhafter oder abgeschnittener Hash abgelehnt wird, statt dass ihm vertraut wird. Behandeln Sie den Eingabe-Claims-Datensatz als Vertrauensanker: Der Exporter serialisiert exakt das, was ihm übergeben wird, sodass der Nachweis nur so vertrauenswürdig ist wie dieser Datensatz. Siehe das Bedrohungsmodell der Engine unter /modules/core/security/.

Konformität

Dieses Modul erhebt keinen normativen Anspruch auf Konformität mit der PDF-Spezifikation. Es exportiert Nachweise über Konformität; es implementiert nicht selbst eine zitierte PDF-Klausel. Seine Design-Ausrichtungen (OWASP ASVS V8.3, NIST CSF 2.0, NIST SP 800-53 r5, ISO/IEC 27001 A.12.4) sind im Quellcode dokumentiert und stellen Ausrichtungen an Kontroll-Frameworks dar, keine chunk-fixierten PDF-Zitate. Die Konformität, die das Bundle meldet, wird von den Oracle- und Golden-Suites erzeugt und validiert, die unter /modules/core/conformance/ beschrieben sind.

Siehe auch

Compliance-Modul — erzeugt die Claims, die dieses Modul exportiert.
Metadata-Modul — der XMP-Audit-Feld-Emitter bettet das Bundle im Dokument ein.
Konformitätsüberblick
Sicherheitsmodell der Engine