Gözlemlenebilirlik: karma zinciriyle bağlanan SIEM günlüğü ve işleme raporlaması

Bir bakışta

Gözlemlenebilirlik modülü, çalışma zamanı durumunun uygulamasını sağlar: kurcalamayı belli eden, karma zinciriyle bağlanan bir güvenlik bilgisi ve olay yönetimi (SIEM) olay günlüğü; işleme ve pilot rapor toplaması; bir donanım güvenlik modülü (HSM) denetim günlüğü ve enstrümantasyonun her zaman çağrılabilir kalması için eksiksiz işlemsiz ölçüm ve izleme uygulamaları.

Her konu için tek bir kanonik sayfa. Gözlemlenebilirlik sözleşmeleri — ContextAwareExceptionInterface, SpectrumInterface, JobNotificationInterface ve DegradationPolicy enum’u — Contracts / Observability sayfasında belgelenmiştir. Bu sayfa somut çalışma zamanı durumu uygulamasını belgeler. Sayfalar birbirini tamamlar, birbirini yinelemez: hizmet sağlayıcı arabirimi (SPI) için sözleşmeler sayfasını, SIEM günlüğü, raporlama ve denetim yüzeyleri için ise bu sayfayı kullanın.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Bu modül, motorun çalışma zamanı durumunu kalıcı ve doğrulanabilir çıktıya dönüştürür.

HashChainSiemEventLog, güvenlik sınıfında bir yüzeydir. SiemEventEmitter sözleşmesini uygular ve her kaydın karmasının SHA-256(prev_hash_bytes || canonical_event_bytes) olduğu bir JavaScript Object Notation (JSON) Lines günlüğü yazar. Bu doğrusal karma zinciri, günlüğü kurcalamayı belli eder hâle getirir: herhangi bir bayt değişirse, bir satır silinirse veya satırlar yeniden sıralanırsa zincir kırılır. verifyIntegrity() dosyayı baştan sona tarar; tutarsız ilk kaydın dizinini ya da zincir bozulmamışsa null döndürür. readAll() kayıtları akış halinde döndürür. İşlem başına tavsiye niteliğindeki bir flock(LOCK_EX), son satırı okuma ve ardından ekleme kritik bölümünü korur; böylece aynı dosya üzerindeki eşzamanlı PHP işlemleri kayıtları iç içe yazmaz. Sınır açıkça belirtilir: bu, bir doğrusal karma zinciridir, bir Request for Comments (RFC) 6962 Merkle ağacı değil. Kurcalamayı belli etmek için yeterlidir, verimli içerme kanıtları için değil. Kaynak bunu açıkça belirtir. SiemEvent, türlenmiş olayı toCanonicalJson() ile taşır. SiemEventSeverity ve SiemEventType onu sınıflandırır. CorrelationContext ve CorrelationIdGenerator, ilişkili olaylar arasında bir korelasyon kimliği taşır.

RenderReportBuilder, RenderReport, PilotReportAggregator ve PilotSummary raporlama yüzeyini oluşturur (@since 5.1.0). Toplayıcı, RenderReport kayıtlarını biriktirir ve bir operasyon incelemesinde kullanılabilecek biçimde diziye, JSON’a veya Markdown’a dönüştürülen bir PilotSummary üretir.

HsmAuditLogInterface / HsmAuditEvent, güvenlik katmanı için HSM destekli imzalama işlemlerini kaydeder. MetricsCounterInterface, MetricsGaugeInterface, MetricsHistogramInterface ve TraceSpanInterface ölçüm ve izleme biçimlerini tanımlar. NoOp* uygulamaları eksiksiz, etkisiz bir yedek sağlar; böylece motor, yapılandırılmış bir arka uç olmadan ölçümleri ve aralıkları yayımlayabilir.

Kararlılık: deneysel. SIEM günlüğü, dondurulmuş bir anlamsal sürümleme (semver) @since değeri taşımak yerine dahili bir döngü etiketiyle işaretlenmiştir ve raporlama yüzeyi @since 5.1.0 değerine sahiptir. Yüzeyler işlevsel ve test edilmiştir, ancak uygulama programlama arabirimi (API) biçimleri değişebilir. Günlük biçimini (kanonik JSON + karma zinciri) kararlı sözleşme, PHP API’sini ise henüz oturmakta olan bir yapı olarak değerlendirin.

API yüzeyi

Sınıf	Temel üyeler	Rol
HashChainSiemEventLog	emit(SiemEvent), verifyIntegrity(): ?int, readAll(): Generator	Kurcalamayı belli eden, karma zinciriyle bağlanan SIEM günlüğü
SiemEvent	toCanonicalJson()	Türlenmiş SIEM olayı
SiemEventSeverity / SiemEventType (enum’lar)	sınıflandırma	Olay önem derecesini ve türünü sınıflandırır
CorrelationContext / CorrelationIdGenerator	korelasyon aktarımı	İlişkili olaylar arasında korelasyonu izler
RenderReportBuilder / RenderReport	rapor oluşturma	İşleme başına raporlar oluşturur (@since 5.1.0)
PilotReportAggregator	addReport(), count(), getSummary(), toJson(), toMarkdown(), exportReportsJson()	İşleme raporlarını toplar (@since 5.1.0)
PilotSummary	toArray(), toJson(), toMarkdown()	Operasyon incelemesi çıktısını özetler (@since 5.1.0)
HsmAuditLogInterface / HsmAuditEvent	HSM denetim kaydı	HSM işlemlerinin denetim kayıtlarını tutar
NoOpSiemEventEmitter, NoOpMetricsCounter, NoOpTraceSpan, …	etkisiz yedekler	Eksiksiz işlemsiz uygulamalar sağlar

Eksiksiz PHPDoc tablosunu oluşturmak için composer docs:generate-api-php -- --module=Observability komutunu çalıştırın.

Kod örneği — hızlı başlangıç

Bir olay yayımlayın ve günlüğün bütünlüğünü doğrulayın.

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

Kod örneği — üretim

Yayımlayıcıyı sarmalayın; böylece imzalama sıcak yolundaki bir günlükleme hatası yakalanmamış bir istisnaya dönüşmez, yerel olarak verilecek bir karar olarak kalır.

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

Uç durumlar ve püf noktaları

• emit(), yazma hatalarında SiemEmitterException fırlatır. İmzalama sıcak yolundaki çağıran bunu sarmalamalı ve hatayı yutma, yeniden deneme veya iptal etme kararını yerel olarak vermelidir. Yayımlayıcı sizin yerinize karar vermez.
• verifyIntegrity(), bozulmuş ilk kaydın dizinini veya null döndürür. Null olmayan bir sonuç, günlüğün o noktadan itibaren ele geçirildiği anlamına gelir. O noktadaki ve sonrasındaki kayıtlara güvenmeyin.
• Tavsiye niteliğindeki flock, işlem başına ve aynı dosya için geçerlidir. Ana bilgisayarlar arası eşzamanlılık, syslog iletme gibi bant dışı bir hedef gerektirir. Dosya kilidinin makineler arasında eşgüdüm sağladığını varsaymayın.
• Bu, doğrusal bir karma zinciridir; Merkle ağacı değildir. Kurcalamayı belli etmeyi sağlar, verimli içerme kanıtlarını değil. Bunu verimli içerme kanıtı sağlıyor gibi pazarlamayın.
• Yedek NoOp* uygulamaları eksiksiz ve etkisizdir. “İşten tasarruf” için arka uç kullanılabilirliğine göre dallanmayın. İşlemsiz olan zaten hiçbir maliyet getirmez.

Performans

emit(), önceki kaydın karmasını okur ve bir dosya kilidi altında tek bir satır ekler: olay başına O(1), artı kilit maliyeti. verifyIntegrity(), tüm zinciri dolaştığı için kayıt sayısına göre O(n) karmaşıklığındadır. Bunu sıcak yolda değil, zamanlanmış olarak çalıştırın. Raporlama toplaması rapor sayısında doğrusaldır. Yeniden üretilebilirlik profili structural şeklindedir: olaylar ve raporlar zaman damgaları ile korelasyon kimlikleri taşır; bu nedenle iki çalıştırmada bu alanlar farklılık gösterir, zincir yapısı ise belirlenimci kalır.

Güvenlik notları

SIEM günlüğü bir güvenlik denetimidir. Kurcalamayı belli etmesi, hem günlük dosyasının hem de doğrulama adımının korunmasına bağlıdır: dosyayı eklemeye uygun, erişim denetimli bir depolamada saklayın, verifyIntegrity() işlevini zamanlanmış olarak çalıştırın ve bir ana bilgisayar ele geçirildiğinde geçmişin sessizce yeniden yazılamaması için kayıtları bant dışı iletin. Olaylar hassas bağlam taşıyabilir. Projenin günlük temizleme yükümlülüğünü, olayı zincire ekledikten sonra değil, oluşturmadan önce uygulayın; çünkü sonradan temizlenerek yapılan yeniden yazma zinciri kırar. HSM denetim günlüğü imzalama işlemlerini kaydeder ve kendisi de güvenlik açısından önemlidir. Bu günlüğü de aynı korumalarla ele alın. Motorun tehdit modeli için /modules/core/security/ sayfasına bakın.

Uyumluluk

Bu modül, PDF teknik özellikleri hakkında normatif bir iddiada bulunmaz. Tasarımı, NIST SP 800-92 belgesindeki günlük yönetimi ve bütünlük doğrulama uygulamalarıyla uyumlu günlük bütünlüğü ve gözlemlenebilirlik mekanizmalarını uygular. Bu denetim çerçevesi uyumu kaynakta belgelenmiştir; öbeğe sabitlenmiş bir PDF alıntısı değildir. Motorun ürettiği belgelerin uyumluluğu, /modules/core/conformance/ sayfasında açıklanan oracle ve golden paketleriyle doğrulanır.

Ayrıca bakınız

• Contracts / Observability — hizmet sağlayıcı arabirimi (SPI): yapılandırılmış istisnalar, Spectrum ve bozulma ilkesi.
• Telemetry modülü — harici arka uçlar için OpenTelemetry köprüsü.
• Audit modülü — SIEM günlüğüyle eşleşen uyumluluk kanıtı dışa aktarıcısı.
• Security modülü — HSM denetim günlüğü tarafından kaydedilen imzalama işlemleri.
• Uyumluluk genel bakışı