跳到內容
NextPDF

稽核：具確定性的合規證據匯出

概覽

標題為「概覽」的區段

稽核模組會將引擎的合規宣告資料集轉換為具確定性、已淨化 PII 的證據組包，適合提供給合規稽核人員。它會排序每個集合以產生位元組穩定的輸出，依結構描述驗證該組包，並可將組包投影為穩定版本。

穩定性：實驗性。 匯出器本身具確定性且經過完整測試，但它所取用的上游 claims.json 資料集是一份仍在進行中的合規矩陣（其自身的 _status 即反映此點）。在證據管線達到 GA 之前，請將本模組的輸出視為工程證據， 而非經認證的證明。

安裝

標題為「安裝」的區段
Terminal window
composer require nextpdf/core:^3

概念總覽

標題為「概念總覽」的區段

AuditExporter 是唯一入口。buildBundle() 接收一份已解碼的 claims 資料集以及一個 AuditExportContext，並回傳一個 AuditExportBundle。buildBundleFromFile() 是載入檔案的便利方法。encode() 會將組包序列化為 JSON。此建構過程採純函式式設計。在 AuditExportContext::generatedAt 固定（例如透過 SOURCE_DATE_EPOCH）且 claims 資料集穩定的情況下，由於 claims[] 依 (standard, clause_id) 排序、evidence[] 依 ref_id 排序，且 clause_hashes[] 依 clause_id 排序，因此每次執行的輸出都會位元組相同。這正是再現性設定檔為 bitwise 的原因。

此組包是一棵型別化的樹：AuditExportClaim（一筆合規宣告）、AuditExportEvidence（支持性證據紀錄）、AuditExportClauseHash（條款內容摘要）以及 AuditExportContext（產生上下文）。每一項都帶有一個用於序列化的 toArray()。

本模組以隱私為預設。其建構式會安裝一個 DefaultPiiSanitiser（一個 PiiSanitiser 實作），在序列化前清除證據中介資料字串。你也可以注入不同的淨化器。匯出器會依嚴格的 64 字元小寫十六進位 SHA-256 樣式驗證條款雜湊、證據摘要與 RAG 引用錨點；若某條款缺少有效雜湊或評估器中介資料，則發出結構化警告（而非無聲丟棄）。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 對齊；這些是原始碼中記載的設計對齊，並非綁定特定區塊的規範性宣告。

API 介面

標題為「API 介面」的區段
類別主要成員角色
AuditExporterbuildBundle(), buildBundleFromFile(), encode(), validateAgainstSchema(), projectToV1()確定性組包 builder/validator
AuditExportBundletoArray()已組裝完成的證據組包
AuditExportClaimtoArray()一筆合規宣告紀錄
AuditExportEvidencetoArray()一筆支持性證據紀錄
AuditExportClauseHashtoArray()一筆條款內容摘要紀錄
AuditExportContextGENERATOR_VERSION產生上下文（固定時間戳記以達成確定性）
PiiSanitiser（介面）sanitise(string): string可插拔的證據中介資料清除器（@since 5.2.0）
DefaultPiiSanitisersanitise()以隱私為預設的淨化器（@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 設定檔失效。
  • 缺少有效 64 字元十六進位 clause_hash 或評估器中介資料的條款會連同結構化警告一併略過，而非無聲納入。請檢查這些警告；被略過的條款代表缺少證據，並不等於通過。
  • 除非你注入另一個，否則會執行預設的 PiiSanitiser。停用淨化是一個會造成隱私後果的明確選擇；對於受規管的匯出，請不要這麼做。
  • 除非你對其回傳值採取行動，否則 validateAgainstSchema() 僅供參考。在生產環境中，請將非空的結果視為會阻擋發布的錯誤。
  • 組包會反映輸入資料集的成熟度。一份仍在進行中的 claims 資料集會產生一份仍在進行中的組包；匯出器並不會提升證據品質。

效能

標題為「效能」的區段

此建構過程與 claims 及證據紀錄的數量呈線性關係，主要由排序主導。buildBundle() 中沒有任何 I/O（檔案存取由呼叫端負責）。預設的參考工作負載遠低於 1500 ms 牆鐘 / 64 MB 峰值的預算範圍。在固定上下文與穩定輸入的前提下，再現性設定檔依設計為 bitwise。

安全性注意事項

標題為「安全性注意事項」的區段

本模組會處理合規證據，其中可能帶有敏感的中介資料。PII 淨化預設為開啟（與 GDPR 第 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 引用。組包所回報的合規，是由 /modules/core/conformance/ 中所述的 oracle 與黃金測試套件所產生並驗證。

另請參閱

標題為「另請參閱」的區段