Auditoría: exportación determinista de evidencias de conformidad

De un vistazo

El módulo Audit convierte el conjunto de datos de declaraciones de conformidad del motor en un paquete determinista de evidencias, depurado de PII y apto para una auditoría de conformidad. Ordena cada colección para producir una salida estable a nivel de bytes, valida el paquete contra un esquema y puede proyectarlo a una versión estable.

Estabilidad: experimental. El exportador es determinista y cuenta con pruebas sólidas, pero el conjunto de datos claims.json de origen que consume es una matriz de conformidad en desarrollo (su propio _status lo refleja). Hasta que el flujo de evidencias alcance la GA, conviene tratar la salida de este módulo como evidencia de ingeniería, no como una certificación acreditada.

Instalación

composer require nextpdf/core:^3

Visión conceptual

AuditExporter es el único punto de entrada. buildBundle() recibe un conjunto de datos de declaraciones decodificado y un AuditExportContext, y devuelve un AuditExportBundle. buildBundleFromFile() es la utilidad auxiliar que carga el archivo. encode() serializa el paquete a JSON. La construcción es puramente funcional. Con un AuditExportContext::generatedAt fijo (por ejemplo, mediante SOURCE_DATE_EPOCH) y un conjunto de datos de declaraciones estable, la salida es idéntica a nivel de bytes entre ejecuciones, porque claims[] se ordenan por (standard, clause_id), evidence[] por ref_id y clause_hashes[] por clause_id. Por eso el perfil de reproducibilidad es bitwise.

El paquete es una estructura tipada en forma de árbol: AuditExportClaim (una declaración de conformidad), AuditExportEvidence (el registro de evidencia de respaldo), AuditExportClauseHash (el resumen de contenido de cláusula) y AuditExportContext (el contexto de generación). Cada uno expone un toArray() para la serialización.

El módulo aplica privacidad por defecto. El constructor instala un DefaultPiiSanitiser (una implementación de PiiSanitiser) que depura las cadenas de metadatos de evidencia antes de serializarlas. Se puede inyectar un depurador distinto. El exportador valida los hashes de cláusula, los resúmenes de evidencia y los anclajes de cita RAG contra un patrón SHA-256 estricto de 64 caracteres hexadecimales en minúsculas, y emite una advertencia estructurada (en lugar de descartar en silencio) cuando a una cláusula le falta un hash válido o metadatos del evaluador. validateAgainstSchema() comprueba el paquete construido. projectToV1() produce una proyección v1 estable. El diseño del exportador está alineado con 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 — se trata de alineaciones de diseño documentadas en el código fuente, no de declaraciones normativas ancladas a fragmentos.

Superficie de la API

Clase	Miembros clave	Rol
AuditExporter	buildBundle(), buildBundleFromFile(), encode(), validateAgainstSchema(), projectToV1()	Constructor/validador determinista de paquetes
AuditExportBundle	toArray()	El paquete de evidencias ensamblado
AuditExportClaim	toArray()	Un registro de declaración de conformidad
AuditExportEvidence	toArray()	Un registro de evidencia de respaldo
AuditExportClauseHash	toArray()	Un registro de resumen de contenido de cláusula
AuditExportContext	GENERATOR_VERSION	Contexto de generación (fijar la marca de tiempo para el determinismo)
PiiSanitiser (interfaz)	sanitise(string): string	Depurador de metadatos de evidencia conectable (@since 5.2.0)
DefaultPiiSanitiser	sanitise()	Depurador con privacidad por defecto (@since 5.2.0)

Ejecutar composer docs:generate-api-php -- --module=Audit para obtener la tabla PHPDoc completa.

Ejemplo de código — Inicio rápido

Construir y codificar un paquete a partir de un archivo de declaraciones.

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

Ejemplo de código — Producción

Validar el paquete y tratar las advertencias de esquema o de hash como una barrera estricta.

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

Casos límite y trampas

• El determinismo requiere fijar AuditExportContext::generatedAt. Sin él, la marca de tiempo varía y la salida deja de ser estable a nivel de bytes, lo que anula el perfil bitwise.
• Si a una cláusula le falta un clause_hash válido de 64 caracteres hexadecimales o metadatos del evaluador, se omite con una advertencia estructurada; no se incluye en silencio. Revisar las advertencias: una cláusula omitida es evidencia ausente, no una aprobación.
• El PiiSanitiser por defecto se ejecuta salvo que se inyecte otro. Desactivar la depuración es una decisión explícita con consecuencias de privacidad: no debe hacerse en una exportación regulada.
• validateAgainstSchema() es solo informativa salvo que se actúe sobre su valor de retorno. Un resultado no vacío debe tratarse como un error que bloquea la publicación en producción.
• El paquete refleja la madurez del conjunto de datos de entrada. Un conjunto de datos de declaraciones en desarrollo produce un paquete en desarrollo; el exportador no eleva la calidad de la evidencia.

Rendimiento

La construcción es lineal con respecto al número de declaraciones y registros de evidencia, y la ordenación domina el coste. No hay E/S en buildBundle() (el llamador es responsable del acceso a archivos). La carga de trabajo de referencia por defecto queda holgadamente dentro del presupuesto de 1500 ms de tiempo de pared / 64 MB de pico. El perfil de reproducibilidad es bitwise por diseño, dado un contexto fijado y una entrada estable.

Notas de seguridad

Este módulo maneja evidencias de conformidad que pueden contener metadatos sensibles. La depuración de PII está activada por defecto (alineación con el art. 32 del RGPD). Debe mantenerse activada para cualquier paquete compartido externamente. El exportador valida cada resumen y anclaje de cita contra un patrón SHA-256 estricto, de modo que un hash malformado o truncado se rechaza en lugar de darse por válido. El conjunto de datos de declaraciones de entrada debe tratarse como la raíz de confianza: el exportador serializa fielmente lo que se le entrega, por lo que la evidencia solo es tan fiable como ese conjunto de datos. Consultar el modelo de amenazas del motor en /modules/core/security/.

Conformidad

Este módulo no formula ninguna declaración normativa de la especificación PDF. Exporta evidencias sobre la conformidad; no implementa por sí mismo una cláusula PDF citada. Sus alineaciones de diseño (OWASP ASVS V8.3, NIST CSF 2.0, NIST SP 800-53 r5, ISO/IEC 27001 A.12.4) están documentadas en el código fuente y son alineaciones con marcos de control, no citas PDF ancladas a fragmentos. La conformidad sobre la que el paquete informa la producen y validan el oráculo y las suites de referencia descritas en /modules/core/conformance/.

Véase también

• Módulo Compliance — produce las declaraciones que exporta este módulo.
• Módulo Metadata — el emisor de campos de auditoría XMP incrusta el paquete en el documento.
• Visión general de la conformidad
• Modelo de seguridad del motor