Audit: ekspor bukti kepatuhan deterministik

Sekilas

Modul Audit mengubah dataset klaim kesesuaian yang dikelola mesin menjadi bundel bukti deterministik dan bebas PII yang cocok untuk auditor kepatuhan. Modul ini mengurutkan setiap koleksi agar keluarannya stabil pada tingkat byte, memvalidasi bundel terhadap skema, dan dapat memproyeksikan bundel tersebut ke versi stabil.

Stabilitas: eksperimental. Pengekspor itu sendiri bersifat deterministik dan teruji dengan baik, tetapi dataset claims.json hulu yang dikonsumsinya adalah matriks kesesuaian yang masih dalam pengerjaan (_status sendiri mencerminkan hal itu). Sampai alur bukti mencapai GA, perlakukan keluaran modul ini sebagai bukti rekayasa, bukan atestasi tersertifikasi.

Instalasi

composer require nextpdf/core:^3

Tinjauan konseptual

AuditExporter adalah satu-satunya titik masuk. buildBundle() menerima dataset klaim yang telah didekode beserta sebuah AuditExportContext dan mengembalikan sebuah AuditExportBundle. buildBundleFromFile() menyediakan metode bantu untuk memuat dataset dari berkas. encode() melakukan serialisasi bundel ke JSON. Proses pembangunannya bersifat fungsional murni. Dengan AuditExportContext::generatedAt yang tetap (misalnya melalui SOURCE_DATE_EPOCH) dan dataset klaim yang stabil, keluarannya identik di tingkat byte pada setiap eksekusi karena claims[] diurutkan berdasarkan (standard, clause_id), evidence[] berdasarkan ref_id, dan clause_hashes[] berdasarkan clause_id. Karena itu, profil reproduktibilitasnya adalah bitwise.

Bundel ini berupa pohon bertipe: AuditExportClaim (klaim kesesuaian), AuditExportEvidence (catatan bukti pendukung), AuditExportClauseHash (intisari konten klausa), dan AuditExportContext (konteks pembuatan). Masing-masing menyediakan toArray() untuk serialisasi.

Modul ini mengutamakan privasi secara default. Konstruktor memasang sebuah DefaultPiiSanitiser (implementasi PiiSanitiser) yang membersihkan string metadata bukti sebelum serialisasi. Sanitiser lain dapat diinjeksikan. Pengekspor memvalidasi hash klausa, intisari bukti, dan jangkar kutipan RAG terhadap pola SHA-256 hex-huruf-kecil sepanjang 64 karakter yang ketat, lalu menghasilkan peringatan terstruktur (bukan menggugurkan secara diam-diam) ketika sebuah klausa tidak memiliki hash yang valid atau metadata evaluator. validateAgainstSchema() memeriksa bundel yang telah dibangun. projectToV1() menghasilkan proyeksi v1 yang stabil. Desain pengekspor selaras dengan OWASP ASVS V8.3, NIST CSF 2.0 PR.PT-1, NIST SP 800-53 r5 AU-2/AU-3, dan ISO/IEC 27001 A.12.4 — semua ini adalah keselarasan desain yang didokumentasikan di sumber, bukan klaim normatif yang ditambatkan ke chunk.

Permukaan API

Kelas	Anggota utama	Peran
`AuditExporter`	`buildBundle()`, `buildBundleFromFile()`, `encode()`, `validateAgainstSchema()`, `projectToV1()`	Builder/validator bundel deterministik
`AuditExportBundle`	`toArray()`	Bundel bukti yang telah dirakit
`AuditExportClaim`	`toArray()`	Satu catatan klaim kesesuaian
`AuditExportEvidence`	`toArray()`	Satu catatan bukti pendukung
`AuditExportClauseHash`	`toArray()`	Catatan intisari konten klausa
`AuditExportContext`	`GENERATOR_VERSION`	Konteks pembuatan (tetapkan stempel waktu demi determinisme)
`PiiSanitiser` (antarmuka)	`sanitise(string): string`	Pembersih metadata bukti yang dapat dipasang (`@since 5.2.0`)
`DefaultPiiSanitiser`	`sanitise()`	Sanitiser yang mengutamakan privasi secara default (`@since 5.2.0`)

Jalankan composer docs:generate-api-php -- --module=Audit untuk tabel PHPDoc lengkap.

Contoh kode — Mulai cepat

Bangun lalu enkode sebuah bundel dari berkas klaim.

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

Contoh kode — Produksi

Validasi bundel dan jadikan peringatan skema atau hash sebagai gerbang ketat.

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

Kasus tepi & jebakan

Determinisme membutuhkan AuditExportContext::generatedAt yang dipatok. Tanpa itu, stempel waktu akan bervariasi dan keluaran tidak stabil di tingkat byte, sehingga menggagalkan profil bitwise.
Klausa yang tidak memiliki clause_hash 64-hex yang valid atau metadata evaluator akan dilewati dengan peringatan terstruktur, bukan disertakan secara diam-diam. Periksa peringatannya; klausa yang dilewati berarti kekurangan bukti, bukan kelulusan.
PiiSanitiser default akan berjalan kecuali Anda menginjeksikan yang lain. Menonaktifkan sanitasi adalah pilihan eksplisit dengan konsekuensi privasi — jangan lakukan itu untuk ekspor yang teregulasi.
validateAgainstSchema() hanya bersifat panduan kecuali Anda menindaklanjuti nilai kembaliannya. Perlakukan hasil yang tidak kosong sebagai galat yang memblokir penerbitan di lingkungan produksi.
Bundel mencerminkan tingkat kematangan dataset masukan. Dataset klaim yang masih dalam pengerjaan menghasilkan bundel yang masih dalam pengerjaan; pengekspor tidak meningkatkan kualitas bukti.

Performa

Proses pembangunan bersifat linear terhadap jumlah catatan klaim dan bukti, dan didominasi oleh pengurutan. Tidak ada I/O di dalam buildBundle() (akses berkas dikelola oleh pemanggil). Beban kerja referensi default berada jauh di bawah anggaran 1500 ms wall / 64 MB puncak. Profil reproduktibilitasnya adalah bitwise dengan konteks yang dipatok dan masukan yang stabil, sesuai desain.

Catatan keamanan

Modul ini menangani bukti kepatuhan yang dapat memuat metadata sensitif. Sanitasi PII aktif secara default (selaras dengan GDPR Pasal 32). Biarkan tetap aktif untuk bundel apa pun yang dibagikan secara eksternal. Pengekspor memvalidasi setiap intisari dan jangkar kutipan terhadap pola SHA-256 yang ketat, sehingga hash yang cacat atau terpotong akan ditolak, bukan dipercaya. Perlakukan dataset klaim masukan sebagai akar kepercayaan: pengekspor melakukan serialisasi secara apa adanya atas apa pun yang diberikan kepadanya, sehingga tingkat kepercayaan bukti hanya setara dengan tingkat kepercayaan dataset tersebut. Lihat model ancaman mesin di /modules/core/security/.

Kesesuaian

Modul ini tidak menegaskan klaim normatif spesifikasi PDF apa pun. Modul ini mengekspor bukti tentang kesesuaian; modul ini sendiri tidak mengimplementasikan klausa PDF yang dikutip. Keselarasan desainnya (OWASP ASVS V8.3, NIST CSF 2.0, NIST SP 800-53 r5, ISO/IEC 27001 A.12.4) didokumentasikan di sumber dan merupakan keselarasan kerangka kontrol, bukan kutipan PDF yang ditambatkan ke chunk. Kesesuaian yang dilaporkan oleh bundel dihasilkan dan divalidasi oleh oracle dan suite golden yang dijelaskan di /modules/core/conformance/.

Lihat juga

Modul Compliance — menghasilkan klaim yang diekspor modul ini.
Modul Metadata — XMP audit-field emitter menyematkan bundel di dalam dokumen.
Tinjauan kesesuaian
Model keamanan mesin