Audit: xuất bằng chứng tuân thủ tất định

Tổng quan nhanh

Mô-đun Audit biến tập dữ liệu conformance-claims của engine thành một gói bằng chứng tất định, đã làm sạch PII, phù hợp cho kiểm toán viên tuân thủ. Mô-đun sắp xếp mọi tập hợp để tạo kết quả ổn định theo từng byte, xác thực gói theo schema, và có thể chiếu gói sang một phiên bản ổn định.

Độ ổn định: thử nghiệm. Bản thân bộ xuất có tính tất định và được kiểm thử kỹ, nhưng tập dữ liệu claims.json ở thượng nguồn mà nó sử dụng là một ma trận tuân thủ đang trong quá trình hoàn thiện (_status của chính nó phản ánh điều đó). Cho đến khi pipeline bằng chứng đạt GA, hãy xem kết quả của mô-đun này là bằng chứng kỹ thuật chứ không phải một chứng thực đã được cấp chứng nhận.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

AuditExporter là điểm vào duy nhất. buildBundle() nhận một tập dữ liệu claims đã giải mã cùng một AuditExportContext và trả về một AuditExportBundle. buildBundleFromFile() là tiện ích nạp từ tệp. encode() tuần tự hóa gói thành JSON. Quá trình tạo dựng là thuần hàm. Với một AuditExportContext::generatedAt cố định (ví dụ qua SOURCE_DATE_EPOCH) và một tập dữ liệu claims ổn định, kết quả giống hệt nhau theo từng byte giữa các lần chạy vì claims[] được sắp xếp theo (standard, clause_id), evidence[] theo ref_id, và clause_hashes[] theo clause_id. Đó là lý do hồ sơ khả năng tái lập là bitwise.

Gói là một cây có kiểu: AuditExportClaim (một tuyên bố tuân thủ), AuditExportEvidence (bản ghi bằng chứng hỗ trợ), AuditExportClauseHash (digest nội dung điều khoản), và AuditExportContext (ngữ cảnh tạo). Mỗi loại đều có toArray() để tuần tự hóa.

Mô-đun mặc định bảo vệ quyền riêng tư. Hàm khởi tạo cài đặt một DefaultPiiSanitiser (một hiện thực của PiiSanitiser) để làm sạch các chuỗi metadata bằng chứng trước khi tuần tự hóa. Bạn có thể tiêm vào một bộ làm sạch khác. Bộ xuất xác thực hash điều khoản, digest bằng chứng và neo trích dẫn RAG theo một mẫu SHA-256 hex-thường 64 ký tự nghiêm ngặt, đồng thời phát ra cảnh báo có cấu trúc (thay vì âm thầm loại bỏ) khi một điều khoản thiếu hash hợp lệ hoặc metadata bộ đánh giá. validateAgainstSchema() kiểm tra gói đã tạo. projectToV1() tạo một phép chiếu v1 ổn định. Thiết kế của bộ xuất phù hợp với OWASP ASVS V8.3, NIST CSF 2.0 PR.PT-1, NIST SP 800-53 r5 AU-2/AU-3, và ISO/IEC 27001 A.12.4 — đây là các phù hợp về thiết kế được ghi nhận trong nguồn, không phải tuyên bố quy phạm gắn với chunk cụ thể.

Bề mặt API

Lớp	Thành viên chính	Vai trò
`AuditExporter`	`buildBundle()`, `buildBundleFromFile()`, `encode()`, `validateAgainstSchema()`, `projectToV1()`	Bộ builder/validator gói tất định
`AuditExportBundle`	`toArray()`	Gói bằng chứng đã lắp ráp
`AuditExportClaim`	`toArray()`	Một bản ghi tuyên bố tuân thủ
`AuditExportEvidence`	`toArray()`	Một bản ghi bằng chứng hỗ trợ
`AuditExportClauseHash`	`toArray()`	Một bản ghi digest nội dung điều khoản
`AuditExportContext`	`GENERATOR_VERSION`	Ngữ cảnh tạo (cố định dấu thời gian để có tính tất định)
`PiiSanitiser` (interface)	`sanitise(string): string`	Bộ làm sạch metadata bằng chứng có thể cắm thay (`@since 5.2.0`)
`DefaultPiiSanitiser`	`sanitise()`	Bộ làm sạch mặc định bảo vệ quyền riêng tư (`@since 5.2.0`)

Chạy composer docs:generate-api-php -- --module=Audit để xem bảng PHPDoc đầy đủ.

Mã ví dụ — bắt đầu nhanh

Tạo và mã hóa một gói từ một tệp 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));

Mã ví dụ — sản xuất

Xác thực gói và xử lý các cảnh báo về schema hoặc hash như một cổng chặn cứng.

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

Trường hợp biên & điểm cần lưu ý

Tính tất định đòi hỏi một AuditExportContext::generatedAt đã được cố định. Nếu không có nó, dấu thời gian sẽ thay đổi và kết quả không ổn định theo từng byte, làm vô hiệu hồ sơ bitwise.
Một điều khoản thiếu clause_hash 64-hex hợp lệ hoặc metadata bộ đánh giá sẽ bị bỏ qua kèm một cảnh báo có cấu trúc, chứ không được âm thầm đưa vào. Hãy kiểm tra các cảnh báo; một điều khoản bị bỏ qua nghĩa là thiếu bằng chứng, chứ không phải đạt.
Bộ PiiSanitiser mặc định sẽ chạy trừ khi bạn tiêm vào một bộ khác. Tắt việc làm sạch là một lựa chọn có chủ đích kèm theo hậu quả về quyền riêng tư — đừng làm vậy với một bản xuất chịu quy định pháp lý.
validateAgainstSchema() chỉ mang tính tư vấn trừ khi bạn hành động dựa trên giá trị trả về của nó. Hãy xem một kết quả không rỗng là một lỗi chặn xuất bản trong môi trường sản xuất.
Gói phản ánh mức độ trưởng thành của tập dữ liệu đầu vào. Một tập dữ liệu claims đang dở dang tạo ra một gói dở dang; bộ xuất không nâng cấp chất lượng bằng chứng.

Hiệu năng

Quá trình tạo dựng tuyến tính theo số lượng claims và bản ghi bằng chứng, chủ yếu do việc sắp xếp chi phối. Không có I/O trong buildBundle() (phía gọi sở hữu việc truy cập tệp). Khối lượng công việc tham chiếu mặc định nằm trong ngân sách 1500 ms thời gian thực / đỉnh 64 MB. Theo thiết kế, hồ sơ khả năng tái lập là bitwise khi có ngữ cảnh cố định và đầu vào ổn định.

Lưu ý bảo mật

Mô-đun này xử lý bằng chứng tuân thủ, vốn có thể chứa metadata nhạy cảm. Việc làm sạch PII được bật theo mặc định (phù hợp với GDPR Điều 32). Hãy giữ tính năng này bật cho bất kỳ gói nào được chia sẻ ra bên ngoài. Bộ xuất xác thực mọi digest và neo trích dẫn theo một mẫu SHA-256 nghiêm ngặt, nên hash sai định dạng hoặc bị cắt cụt sẽ bị từ chối thay vì được tin cậy. Hãy xem tập dữ liệu claims đầu vào là gốc tin cậy: bộ xuất tuần tự hóa trung thực những gì được cung cấp, nên bằng chứng chỉ đáng tin cậy ở mức tương ứng với tập dữ liệu đó. Xem mô hình mối đe dọa của engine tại /modules/core/security/.

Tuân thủ

Mô-đun này không khẳng định bất kỳ tuyên bố quy phạm nào của đặc tả PDF. Nó xuất bằng chứng về sự tuân thủ; bản thân nó không hiện thực một điều khoản PDF được trích dẫn. Những phù hợp về thiết kế của mô-đun (OWASP ASVS V8.3, NIST CSF 2.0, NIST SP 800-53 r5, ISO/IEC 27001 A.12.4) được ghi nhận trong nguồn và là các phù hợp với khung kiểm soát, không phải trích dẫn PDF gắn với chunk cụ thể. Sự tuân thủ mà gói báo cáo được tạo ra và xác thực bởi các bộ oracle và golden được mô tả trong /modules/core/conformance/.

Xem thêm

Mô-đun Compliance — tạo ra các claims mà mô-đun này xuất.
Mô-đun Metadata — bộ phát trường audit XMP nhúng gói vào trong tài liệu.
Tổng quan về tuân thủ
Mô hình bảo mật của engine