Audit: esportazione deterministica delle evidenze di conformità

In sintesi

Il modulo Audit trasforma il dataset delle dichiarazioni di conformità del motore in un bundle di evidenze deterministico, ripulito dai dati personali e adatto a un revisore della conformità. Ordina ogni raccolta per produrre un output stabile a livello di byte, valida il bundle rispetto a uno schema e può proiettarlo in una versione stabile.

Stabilità: sperimentale. L’esportatore in sé è deterministico e ben testato, ma il dataset claims.json a monte da cui dipende è una matrice di conformità in corso di sviluppo (come indica il relativo _status). Finché la pipeline delle evidenze non raggiunge la versione GA, considerare l’output di questo modulo come evidenza tecnica, non come attestazione certificata.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

AuditExporter è l’unico punto di ingresso. buildBundle() riceve un dataset di dichiarazioni decodificato insieme a un AuditExportContext e restituisce un AuditExportBundle. buildBundleFromFile() è la funzione di utilità per il caricamento da file. encode() serializza il bundle in JSON. La costruzione è puramente funzionale. Con un AuditExportContext::generatedAt fisso (ad esempio tramite SOURCE_DATE_EPOCH) e un dataset di dichiarazioni stabile, l’output rimane identico a livello di byte tra un’esecuzione e l’altra, perché i claims[] sono ordinati per (standard, clause_id), gli evidence[] per ref_id e i clause_hashes[] per clause_id. Per questo motivo il profilo di riproducibilità è bitwise.

Il bundle è una struttura ad albero tipizzata: AuditExportClaim (una dichiarazione di conformità), AuditExportEvidence (il record di evidenza di supporto), AuditExportClauseHash (il digest del contenuto della clausola) e AuditExportContext (il contesto di generazione). Ciascuno espone un toArray() per la serializzazione.

Il modulo tutela la privacy per impostazione predefinita. Il costruttore installa un DefaultPiiSanitiser (un’implementazione di PiiSanitiser) che ripulisce le stringhe dei metadati delle evidenze prima della serializzazione. È possibile iniettare un sanitizer diverso. L’esportatore valida gli hash delle clausole, i digest delle evidenze e gli ancoraggi delle citazioni RAG rispetto a un pattern SHA-256 rigoroso, esadecimale minuscolo a 64 caratteri, ed emette un avviso strutturato (anziché un’eliminazione silenziosa) quando una clausola è priva di un hash valido o dei metadati del valutatore. validateAgainstSchema() verifica il bundle costruito. projectToV1() produce una proiezione v1 stabile. Il design dell’esportatore è allineato a OWASP ASVS V8.3, NIST CSF 2.0 PR.PT-1, NIST SP 800-53 r5 AU-2/AU-3 e ISO/IEC 27001 A.12.4: si tratta di allineamenti di design documentati nel sorgente, non di dichiarazioni normative ancorate a chunk.

Superficie API

Classe	Membri principali	Ruolo
AuditExporter	buildBundle(), buildBundleFromFile(), encode(), validateAgainstSchema(), projectToV1()	Costruttore/validatore deterministico di bundle
AuditExportBundle	toArray()	Bundle di evidenze assemblato
AuditExportClaim	toArray()	Un record di dichiarazione di conformità
AuditExportEvidence	toArray()	Un record di evidenza di supporto
AuditExportClauseHash	toArray()	Un record di digest del contenuto della clausola
AuditExportContext	GENERATOR_VERSION	Contesto di generazione (fissare il timestamp per il determinismo)
PiiSanitiser (interfaccia)	sanitise(string): string	Strumento collegabile a plugin per ripulire i metadati delle evidenze (@since 5.2.0)
DefaultPiiSanitiser	sanitise()	Sanitizer predefinito orientato alla privacy (@since 5.2.0)

Eseguire composer docs:generate-api-php -- --module=Audit per ottenere la tabella PHPDoc completa.

Esempio di codice — Avvio rapido

Creare e codificare un bundle a partire da un file di dichiarazioni.

<?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));

Esempio di codice — Produzione

Validare il bundle e trattare gli avvisi relativi a schema o hash come condizioni bloccanti.

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

Casi limite e insidie

• Il determinismo richiede un AuditExportContext::generatedAt fissato. Senza di esso il timestamp varia e l’output non è stabile a livello di byte, vanificando il profilo bitwise.
• Una clausola priva di un clause_hash valido a 64 esadecimali o dei metadati del valutatore viene saltata con un avviso strutturato, non inclusa silenziosamente. Controllare gli avvisi: una clausola saltata è priva di evidenze, non equivale a un superamento.
• Il PiiSanitiser predefinito viene eseguito a meno che non se ne inietti un altro. Disabilitare la sanitizzazione è una scelta esplicita con conseguenze sulla privacy: non farlo per un’esportazione regolamentata.
• validateAgainstSchema() ha valore solo indicativo a meno che non si agisca sul suo valore di ritorno. In produzione, trattare un risultato non vuoto come un errore che blocca la pubblicazione.
• Il bundle riflette la maturità del dataset di input. Un dataset di dichiarazioni in corso di sviluppo produce un bundle in corso di sviluppo; l’esportatore non migliora la qualità delle evidenze.

Prestazioni

La costruzione è lineare rispetto al numero di dichiarazioni e di record di evidenza ed è dominata dall’ordinamento. Non viene eseguito I/O in buildBundle() (l’accesso al file è di competenza del chiamante). Il workload di riferimento predefinito rientra ampiamente nel budget di 1500 ms di wall time / 64 MB di picco. Il profilo di riproducibilità è bitwise con un contesto fissato e un input stabile, per progettazione.

Note sulla sicurezza

Questo modulo gestisce evidenze di conformità, che possono contenere metadati sensibili. La sanitizzazione dei dati personali è attiva per impostazione predefinita (allineamento all’art. 32 del GDPR). Mantenerla attiva per qualsiasi bundle condiviso esternamente. L’esportatore valida ogni digest e ogni ancoraggio di citazione rispetto a un pattern SHA-256 rigoroso, in modo che un hash malformato o troncato venga rifiutato anziché ritenuto attendibile. Trattare il dataset di dichiarazioni di input come radice di fiducia: l’esportatore serializza fedelmente ciò che riceve, quindi le evidenze sono attendibili solo quanto quel dataset. Consultare il modello delle minacce del motore in /modules/core/security/.

Conformità

Questo modulo non formula alcuna dichiarazione normativa sulla specifica PDF. Esporta evidenze sulla conformità; non implementa direttamente una clausola PDF citata. I suoi allineamenti di design (OWASP ASVS V8.3, NIST CSF 2.0, NIST SP 800-53 r5, ISO/IEC 27001 A.12.4) sono documentati nel sorgente e sono allineamenti a framework di controllo, non citazioni PDF ancorate a chunk. La conformità che il bundle riporta è prodotta e validata dalle suite oracle e golden descritte in /modules/core/conformance/.

Vedere anche

• Modulo Compliance — produce le dichiarazioni esportate da questo modulo.
• Modulo Metadata — il componente che emette campi di audit XMP incorpora il bundle nel documento.
• Panoramica della conformità
• Modello di sicurezza del motore