Observability: hash-gekoppelde SIEM-log en weergaverapportage

In het kort

De module Observability levert de implementatie van de runtime-state: een manipulatiebestendige, hash-gekoppelde gebeurtenissenlog voor security information and event management (SIEM), aggregatie van weergave- en pilotrapporten, een hardware security module (HSM)-auditlog en volledige no-op-implementaties van metrics en traces, zodat instrumentatie altijd kan worden aangeroepen.

Eén canonieke pagina per onderwerp. De observability-contracten — ContextAwareExceptionInterface, SpectrumInterface, JobNotificationInterface en de enum DegradationPolicy — zijn gedocumenteerd op Contracts / Observability. Deze pagina documenteert de concrete implementatie van de runtime-state. De pagina’s zijn complementair, geen duplicaten: gebruik de contractenpagina voor de service provider interface (SPI), en deze pagina voor de SIEM-log, rapportage en auditonderdelen.

Installatie

composer require nextpdf/core:^3

Conceptueel overzicht

Deze module zet de runtime-state van de engine om in duurzame, verifieerbare uitvoer.

HashChainSiemEventLog is het beveiligingsonderdeel. Het implementeert het contract SiemEventEmitter en schrijft een JavaScript Object Notation (JSON) Lines-log waarin de hash van elk record gelijk is aan SHA-256(prev_hash_bytes || canonical_event_bytes). Die lineaire hash-keten maakt de log manipulatiebestendig: als er een byte verandert, een regel wordt verwijderd of regels van volgorde veranderen, breekt de keten. verifyIntegrity() doorloopt het bestand en geeft de index van het eerste inconsistente record terug, of null wanneer de keten intact is. readAll() streamt de records. Een adviserende flock(LOCK_EX) per proces beschermt de kritieke sectie voor het lezen van de bestandsstaart en daarna toevoegen, zodat gelijktijdige PHP-processen op hetzelfde bestand records niet door elkaar schrijven. De beperking is expliciet: dit is een lineaire hash-keten, geen Request for Comments (RFC) 6962 Merkle-boom. Het is toereikend voor manipulatiebestendigheid, niet voor efficiënte inclusion proofs. Ook de broncode vermeldt dit. SiemEvent draagt de getypeerde gebeurtenis met toCanonicalJson(). SiemEventSeverity en SiemEventType classificeren de gebeurtenis. CorrelationContext en CorrelationIdGenerator dragen een correlatie-id over gerelateerde gebeurtenissen heen.

RenderReportBuilder, RenderReport, PilotReportAggregator en PilotSummary vormen het rapportageonderdeel (@since 5.1.0). De aggregator verzamelt RenderReport-objecten en produceert een PilotSummary die wordt omgezet naar array, JSON of Markdown, in een vorm die bruikbaar is voor een operations review.

HsmAuditLogInterface / HsmAuditEvent registreren ondertekeningsbewerkingen die door de HSM worden ondersteund voor de beveiligingslaag. De MetricsCounterInterface, MetricsGaugeInterface, MetricsHistogramInterface en TraceSpanInterface definiëren de vormen voor metrics en traces. De NoOp*-implementaties bieden een volledig inerte fallback, zodat de engine metrics en spans kan emitteren zonder geconfigureerde backend.

Stabiliteit: experimenteel. De SIEM-log wordt intern voorzien van een cyclus-tag in plaats van een bevroren semantic versioning (semver) @since, en het rapportageonderdeel is @since 5.1.0. De onderdelen zijn functioneel en getest, maar de vormen van de application programming interface (API) kunnen nog veranderen. Behandel het log-formaat (canonieke JSON + hash-keten) als het stabiele contract en de PHP-API als nog niet uitgekristalliseerd.

API-oppervlak

Klasse	Belangrijkste members	Rol
HashChainSiemEventLog	emit(SiemEvent), verifyIntegrity(): ?int, readAll(): Generator	Manipulatiebestendige, hash-gekoppelde SIEM-log
SiemEvent	toCanonicalJson()	Getypeerde SIEM-gebeurtenis
SiemEventSeverity / SiemEventType (enums)	classificatie	Classificeert de ernst en het type van een gebeurtenis
CorrelationContext / CorrelationIdGenerator	correlatie-threading	Draagt correlatie over gerelateerde gebeurtenissen heen
RenderReportBuilder / RenderReport	rapportsamenstelling	Bouwt rapporten per weergave (@since 5.1.0)
PilotReportAggregator	addReport(), count(), getSummary(), toJson(), toMarkdown(), exportReportsJson()	Aggregeert weergaverapporten (@since 5.1.0)
PilotSummary	toArray(), toJson(), toMarkdown()	Vat de uitvoer van een operations review samen (@since 5.1.0)
HsmAuditLogInterface / HsmAuditEvent	HSM-auditrecord	Registreert auditgegevens van HSM-bewerkingen
NoOpSiemEventEmitter, NoOpMetricsCounter, NoOpTraceSpan, …	inerte fallbacks	Biedt volledige no-op-implementaties

Voer composer docs:generate-api-php -- --module=Observability uit om de volledige PHPDoc-tabel te genereren.

Codevoorbeeld — Snelstart

Emitteer een gebeurtenis en verifieer de integriteit van de log.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Observability\Siem\HashChainSiemEventLog;
use NextPDF\Observability\Siem\SiemEvent;

$log = new HashChainSiemEventLog('/var/log/nextpdf/siem.jsonl');
$log->emit(new SiemEvent(/* type, severity, payload */));

$firstBroken = $log->verifyIntegrity();
echo $firstBroken === null
    ? "SIEM chain intact.\n"
    : "Tamper detected at record {$firstBroken}.\n";

Codevoorbeeld — Productie

Verpak de emitter zodat een logfout in het hot path van ondertekening een lokale beslissing blijft, in plaats van te eindigen als een niet-afgevangen exceptie.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Observability\Siem\HashChainSiemEventLog;
use NextPDF\Observability\Siem\Exception\SiemEmitterException;
use NextPDF\Observability\Siem\SiemEvent;
use Psr\Log\LoggerInterface;

final readonly class AuditedSiemSink
{
    public function __construct(
        private HashChainSiemEventLog $log,
        private LoggerInterface $fallback,
    ) {}

    public function record(SiemEvent $event): void
    {
        try {
            $this->log->emit($event);
        } catch (SiemEmitterException $e) {
            // Do not let SIEM I/O abort the signing path; record and continue.
            $this->fallback->critical('SIEM emit failed; event not chained.', [
                'error' => $e->getMessage(),
            ]);
        }
    }
}

Randgevallen en valkuilen

• emit() gooit SiemEmitterException bij schrijffouten. Een aanroeper in het hot path van ondertekening moet deze afvangen en lokaal beslissen: negeren, opnieuw proberen of afbreken. De emitter beslist dat niet voor je.
• verifyIntegrity() geeft de index van het eerste defecte record terug, of null. Een niet-null-resultaat betekent dat de log vanaf dat punt is gecompromitteerd. Vertrouw records op of na dat punt niet.
• De adviserende flock geldt per proces en voor hetzelfde bestand. Gelijktijdigheid tussen hosts vereist een out-of-band-sink, zoals syslog-forwarding. Ga er niet van uit dat de bestandsvergrendeling tussen machines coördineert.
• Dit is een lineaire hash-keten, geen Merkle-boom. Het biedt manipulatiebestendigheid, geen efficiënte inclusion proofs. Presenteer het niet als dat laatste.
• De NoOp*-fallbacks zijn volledig en inert. Vertak niet op de beschikbaarheid van de backend om “werk te besparen”. De no-op kost al niets.

Prestaties

emit() leest de hash van het vorige record en voegt één regel toe onder een bestandsvergrendeling: O(1) per gebeurtenis plus de vergrendeling. verifyIntegrity() is O(n) in het aantal records, omdat het de hele keten doorloopt. Voer het volgens een planning uit, niet in het hot path. De rapportageaggregatie is lineair in het aantal rapporten. Het reproduceerbaarheidsprofiel is structural: gebeurtenissen en rapporten dragen timestamps en correlatie-id’s, waardoor twee runs in die velden verschillen terwijl de ketenstructuur deterministisch blijft.

Beveiligingsnotities

De SIEM-log is een beveiligingsmaatregel. De manipulatiebestendigheid hangt af van het beschermen van zowel het logbestand als de verificatiestap: sla het bestand op in append-vriendelijke, toegangsgecontroleerde opslag, voer verifyIntegrity() volgens een planning uit en stuur records out-of-band door, zodat een gecompromitteerde host de geschiedenis niet stilzwijgend kan herschrijven. Gebeurtenissen kunnen gevoelige context bevatten. Pas de log-scrubbingverplichting van het project toe voordat je de gebeurtenis opbouwt, niet nadat die in de keten is opgenomen; een geschoonde herschrijving zou de keten namelijk breken. De HSM-auditlog registreert ondertekeningsbewerkingen en is zelf beveiligingsrelevant. Behandel deze met dezelfde beschermingsmaatregelen. Zie het threat model van de engine in /modules/core/security/.

Conformiteit

Deze module doet geen normatieve uitspraak over PDF-specificaties. Het implementeert mechanismen voor logintegriteit en observability waarvan het ontwerp aansluit bij de praktijken voor logbeheer en integriteitsverificatie in NIST SP 800-92. Die afstemming op het control-framework is in de broncode gedocumenteerd; het is geen chunk-gepinde PDF-citatie. De conformiteit van documenten die de engine produceert, wordt gevalideerd door de oracle- en golden-suites die zijn beschreven in /modules/core/conformance/.

Zie ook

• Contracts / Observability — de service provider interface (SPI): gestructureerde excepties, Spectrum en degradatiebeleid.
• Telemetry module — de OpenTelemetry-brug voor externe backends.
• Audit module — de exporteur van compliancebewijs die samenwerkt met de SIEM-log.
• Security module — de ondertekeningsbewerkingen die door de HSM-auditlog worden geregistreerd.
• Conformiteitsoverzicht