Audit: ส่งออกหลักฐานการปฏิบัติตามข้อกำหนดแบบดีเทอร์มินิสติก

ภาพรวมโดยย่อ

โมดูล Audit แปลงชุดข้อมูล conformance-claims ของเอนจินเป็นชุดหลักฐานแบบดีเทอร์มินิสติกที่ผ่านการลบ PII และเหมาะสำหรับผู้ตรวจสอบการปฏิบัติตามข้อกำหนด โมดูลจะเรียงลำดับทุกคอลเล็กชันเพื่อให้ผลลัพธ์เสถียรในระดับไบต์ ตรวจสอบความถูกต้องของชุดข้อมูลกับสคีมา และฉายภาพชุดข้อมูลไปยังเวอร์ชันที่เสถียรได้

เสถียรภาพ: ทดลอง ตัวส่งออกเองทำงานแบบดีเทอร์มินิสติกและ ผ่านการทดสอบมาอย่างดี แต่ชุดข้อมูลต้นทาง claims.json ที่นำมาใช้เป็น เมทริกซ์การปฏิบัติตามข้อกำหนดที่ยังอยู่ระหว่างดำเนินการ (โดย _status ของชุดข้อมูลเองสะท้อนสถานะนี้) จนกว่า ไปป์ไลน์หลักฐานจะถึงระดับ GA ให้ถือว่าผลลัพธ์จากโมดูลนี้เป็นหลักฐานเชิงวิศวกรรม ไม่ใช่การรับรองอย่างเป็นทางการ

การติดตั้ง

composer require nextpdf/core:^3

ภาพรวมเชิงแนวคิด

AuditExporter คือจุดเข้าใช้งานหลักเพียงจุดเดียว buildBundle() รับชุดข้อมูล claims ที่ถอดรหัสแล้วพร้อม AuditExportContext และคืนค่า AuditExportBundle buildBundleFromFile() เป็นเมธอดช่วยสำหรับโหลดจากไฟล์ ส่วน encode() จะซีเรียลไลซ์ชุดข้อมูลเป็น JSON กระบวนการสร้างเป็นแบบ pure-functional เมื่อกำหนด AuditExportContext::generatedAt ให้คงที่ (เช่นผ่าน SOURCE_DATE_EPOCH) และมีชุดข้อมูล claims ที่เสถียร ผลลัพธ์จะเหมือนกันในระดับไบต์ในทุกรอบการทำงาน เพราะ claims[] ถูกเรียงลำดับตาม (standard, clause_id) evidence[] ตาม ref_id และ clause_hashes[] ตาม clause_id นี่คือเหตุผลที่โปรไฟล์การทำซ้ำได้เป็น bitwise

ชุดข้อมูลนี้เป็นโครงสร้างทรีที่กำหนดชนิดชัดเจน: AuditExportClaim (การกล่าวอ้างการปฏิบัติตามข้อกำหนด) AuditExportEvidence (ระเบียนหลักฐานสนับสนุน) AuditExportClauseHash (ไดเจสต์ของเนื้อหาข้อกำหนด) และ AuditExportContext (บริบทการสร้าง) แต่ละชนิดมี toArray() สำหรับการซีเรียลไลซ์

โมดูลนี้คำนึงถึงความเป็นส่วนตัวเป็นค่าเริ่มต้น คอนสตรักเตอร์จะติดตั้ง DefaultPiiSanitiser (implementation ของ PiiSanitiser) เพื่อลบสตริงเมทาดาทาของหลักฐานก่อนซีเรียลไลซ์ และสามารถฉีดตัวลบข้อมูลอื่นเข้ามาได้ ตัวส่งออกจะตรวจสอบความถูกต้องของแฮชข้อกำหนด ไดเจสต์หลักฐาน และจุดยึดการอ้างอิง RAG เทียบกับรูปแบบ SHA-256 แบบเลขฐานสิบหกตัวพิมพ์เล็ก 64 อักขระอย่างเข้มงวด และจะส่งคำเตือนแบบมีโครงสร้าง (แทนที่จะตัดทิ้งโดยไม่แจ้ง) เมื่อข้อกำหนดใดขาดแฮชที่ถูกต้องหรือเมทาดาทาของตัวประเมิน validateAgainstSchema() ตรวจสอบชุดข้อมูลที่สร้างขึ้น ส่วน projectToV1() สร้างการฉายภาพ v1 ที่เสถียร การออกแบบตัวส่งออกสอดคล้องกับ OWASP ASVS V8.3 NIST CSF 2.0 PR.PT-1 NIST SP 800-53 r5 AU-2/AU-3 และ ISO/IEC 27001 A.12.4 — รายการเหล่านี้เป็นความสอดคล้องเชิงการออกแบบที่ระบุไว้ในซอร์ส ไม่ใช่การกล่าวอ้างเชิงบรรทัดฐานที่อ้างอิงกับ chunk

ส่วนที่เปิดให้ใช้งานของ API

คลาส	สมาชิกหลัก	บทบาท
AuditExporter	buildBundle(), buildBundleFromFile(), encode(), validateAgainstSchema(), projectToV1()	builder/validator สำหรับชุดข้อมูลแบบดีเทอร์มินิสติก
AuditExportBundle	toArray()	ชุดหลักฐานที่ประกอบขึ้น
AuditExportClaim	toArray()	ระเบียนการกล่าวอ้างการปฏิบัติตามข้อกำหนดหนึ่งรายการ
AuditExportEvidence	toArray()	ระเบียนหลักฐานสนับสนุนหนึ่งรายการ
AuditExportClauseHash	toArray()	ระเบียนไดเจสต์ของเนื้อหาข้อกำหนด
AuditExportContext	GENERATOR_VERSION	บริบทการสร้าง (ตรึงไทม์สแตมป์เพื่อให้ได้ผลแบบดีเทอร์มินิสติก)
PiiSanitiser (อินเทอร์เฟซ)	sanitise(string): string	ตัวลบเมทาดาทาของหลักฐานแบบเสียบปลั๊กได้ (@since 5.2.0)
DefaultPiiSanitiser	sanitise()	ตัวลบข้อมูลที่คำนึงถึงความเป็นส่วนตัวเป็นค่าเริ่มต้น (@since 5.2.0)

เรียกใช้ composer docs:generate-api-php -- --module=Audit เพื่อดูตาราง PHPDoc ฉบับเต็ม

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

สร้างและเข้ารหัสชุดข้อมูลจากไฟล์ claims

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

ตัวอย่างโค้ด — การใช้งานจริง

ตรวจสอบความถูกต้องของชุดข้อมูล และถือว่าคำเตือนเกี่ยวกับสคีมาหรือแฮชเป็นเงื่อนไขกั้นที่เข้มงวด

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

กรณีขอบและข้อควรระวัง

• ความเป็นดีเทอร์มินิสติกจำเป็นต้องตรึง AuditExportContext::generatedAt ไว้ หากไม่ตรึง ไทม์สแตมป์จะเปลี่ยนแปลงและผลลัพธ์จะไม่เสถียรในระดับไบต์ ซึ่งทำให้โปรไฟล์ bitwise ใช้ไม่ได้
• ข้อกำหนดที่ขาด clause_hash แบบเลขฐานสิบหก 64 หลักที่ถูกต้อง หรือขาดเมทาดาทาของตัวประเมิน จะถูก ข้ามไปพร้อมคำเตือนแบบมีโครงสร้าง ไม่ใช่รวมเข้าไปโดยไม่แจ้ง ให้ตรวจสอบคำเตือน ข้อกำหนดที่ถูกข้ามคือข้อกำหนดที่ขาดหลักฐาน ไม่ใช่ข้อกำหนดที่ผ่าน
• ค่าเริ่มต้น PiiSanitiser จะทำงานเว้นแต่จะฉีดตัวอื่นเข้ามา การปิดการลบข้อมูลเป็นทางเลือกโดยเจตนาที่มีผลกระทบต่อความเป็นส่วนตัว — อย่าทำเช่นนั้นสำหรับการส่งออกที่อยู่ภายใต้ข้อบังคับ
• validateAgainstSchema() เป็นเพียงคำแนะนำเว้นแต่จะนำค่าที่คืนมาไปจัดการ ในการใช้งานจริง ให้ถือว่าผลลัพธ์ที่ไม่ว่างเป็นข้อผิดพลาดที่ต้องขัดขวางการเผยแพร่
• ชุดข้อมูลสะท้อนความพร้อมของข้อมูลขาเข้า ชุดข้อมูล claims ที่ยังอยู่ระหว่างดำเนินการจะให้ชุดข้อมูลที่ยังอยู่ระหว่างดำเนินการ ตัวส่งออกไม่ยกระดับคุณภาพของหลักฐาน

ประสิทธิภาพ

กระบวนการสร้างมีความซับซ้อนเชิงเส้นตามจำนวน claims และระเบียนหลักฐาน โดยมีการเรียงลำดับเป็นปัจจัยหลัก ไม่มี I/O ใน buildBundle() (ผู้เรียกเป็นผู้จัดการการเข้าถึงไฟล์) ภาระงานอ้างอิงค่าเริ่มต้นอยู่ภายในงบประมาณ 1500 ms wall / 64 MB peak ได้อย่างสบาย โปรไฟล์การทำซ้ำได้คือ bitwise เมื่อมีบริบทที่ตรึงไว้และข้อมูลขาเข้าที่เสถียร ซึ่งเป็นไปตามการออกแบบ

หมายเหตุด้านความปลอดภัย

โมดูลนี้จัดการหลักฐานการปฏิบัติตามข้อกำหนด ซึ่งอาจมีเมทาดาทาที่ละเอียดอ่อน การลบ PII เปิดใช้งานโดยค่าเริ่มต้น (สอดคล้องกับ GDPR Art. 32) ให้เปิดใช้งานไว้สำหรับชุดข้อมูลทุกชุดที่แบ่งปันสู่ภายนอก ตัวส่งออกจะตรวจสอบความถูกต้องของทุกไดเจสต์และจุดยึดการอ้างอิงเทียบกับรูปแบบ SHA-256 อย่างเข้มงวด ดังนั้นแฮชที่ผิดรูปแบบหรือถูกตัดให้สั้นจึงถูกปฏิเสธแทนที่จะได้รับความเชื่อถือ ให้ถือว่าชุดข้อมูล claims ขาเข้าเป็นรากแห่งความเชื่อถือ ตัวส่งออกจะซีเรียลไลซ์สิ่งที่ได้รับอย่างซื่อตรง ดังนั้นหลักฐานจะน่าเชื่อถือได้เพียงเท่าที่ชุดข้อมูลนั้นน่าเชื่อถือเท่านั้น โปรดดูแบบจำลองภัยคุกคามของเอนจินที่ /modules/core/security/ ประกอบ

การปฏิบัติตามข้อกำหนด

โมดูลนี้ไม่ได้กล่าวอ้างเชิงบรรทัดฐานใด ๆ ตามข้อกำหนด PDF โมดูลส่งออกหลักฐาน เกี่ยวกับ การปฏิบัติตามข้อกำหนด แต่ไม่ได้พัฒนาข้อกำหนด PDF ที่อ้างถึงด้วยตนเอง ความสอดคล้องเชิงการออกแบบของโมดูล (OWASP ASVS V8.3 NIST CSF 2.0 NIST SP 800-53 r5 ISO/IEC 27001 A.12.4) ระบุไว้ในซอร์ส และเป็นความสอดคล้องกับเฟรมเวิร์กการควบคุม ไม่ใช่การอ้างอิง PDF ที่อ้างอิงกับ chunk การปฏิบัติตามข้อกำหนดที่ชุดข้อมูล รายงาน ถูกสร้างและตรวจสอบความถูกต้องโดย oracle และ golden suites ตามที่อธิบายไว้ใน /modules/core/conformance/ ประกอบ

ดูเพิ่มเติม

• โมดูล Compliance — สร้าง claims ที่โมดูลนี้ส่งออก
• โมดูล Metadata — ตัวปล่อยฟิลด์ XMP audit ที่ฝังชุดข้อมูลไว้ในเอกสาร
• ภาพรวมการปฏิบัติตามข้อกำหนด
• แบบจำลองความปลอดภัยของเอนจิน