الرصد: سجل SIEM مقيَّد بسلسلة تجزئة وتقارير العرض

لمحة سريعة

توفّر وحدة الرصد تنفيذ حالة وقت التشغيل: سجل أحداث لإدارة معلومات الأمن والأحداث (⁨SIEM⁩) مقيَّد بسلسلة تجزئة ومقاوم للعبث، وتجميعاً لتقارير العرض والتجارب الرائدة، وسجل تدقيق لوحدة أمان الأجهزة (⁨HSM⁩)، وتنفيذات مقاييس وتتبُّع كاملة لا تُجري أي عملية، بحيث تبقى أدوات القياس قابلة للاستدعاء دائماً.

صفحة قانونية واحدة لكل شأن. عقود الرصد — ContextAwareExceptionInterface، SpectrumInterface، JobNotificationInterface، والتعداد DegradationPolicy — موثَّقة في العقود / الرصد. هذه الصفحة توثّق التنفيذ الفعلي لحالة وقت التشغيل. الصفحتان متكاملتان وليستا مكررتين: استخدم صفحة العقود لواجهة مزوّد الخدمة (⁨SPI⁩)، واستخدم هذه الصفحة لسطوح سجل ⁨SIEM⁩ وإعداد التقارير والتدقيق.

التثبيت

composer require nextpdf/core:^3

نظرة مفاهيمية

تحوّل هذه الوحدة حالة وقت التشغيل في المحرّك إلى مُخرَجات دائمة وقابلة للتحقق.

HashChainSiemEventLog هو السطح ذو الدرجة الأمنية. وهو يُنفِّذ عقد SiemEventEmitter ويكتب سجلّاً بصيغة سطور تدوين كائنات ⁨JavaScript⁩ (⁨JSON⁩) حيث تكون تجزئة كل سجل هي SHA-256(prev_hash_bytes || canonical_event_bytes). سلسلة التجزئة الخطية تلك تجعل السجل مقاوماً للعبث: إذا تغيّرت أي بايتة، أو حُذف سطر، أو أُعيد ترتيب السطور، تنكسر السلسلة. يجتاز verifyIntegrity() الملف ويُعيد فهرس أول سجل غير متّسق، أو null عندما تكون السلسلة سليمة. ويبثّ readAll() السجلات. يحمي قفل استشاري لكل عملية flock(LOCK_EX) المقطعَ الحرج، أي قراءة الذيل ثم الإلحاق، بحيث لا تتداخل سجلات عمليات ⁨PHP⁩ المتزامنة على الملف نفسه. والحدّ صريح: هذه سلسلة تجزئة خطية، وليست شجرة ⁨Merkle⁩ وفق طلب التعليقات (⁨RFC⁩) 6962. وهي كافية لإثبات العبث، لا للحصول على براهين إدراج فعّالة. يصرّح المصدر بذلك. يحمل SiemEvent الحدثَ المُصنَّف مع toCanonicalJson(). ويُصنّفه SiemEventSeverity وSiemEventType. ويحمل CorrelationContext وCorrelationIdGenerator معرّف ارتباط عبر الأحداث المرتبطة.

تكوّن RenderReportBuilder، وRenderReport، وPilotReportAggregator، وPilotSummary سطح إعداد التقارير (@since 5.1.0). يجمع المُجمِّع RenderReport⁨s⁩ ويُنتج PilotSummary يُعرَض كمصفوفة أو ⁨JSON⁩ أو ⁨Markdown⁩، بالصيغة التي يمكن لمراجعة العمليات استخدامها.

يسجّل HsmAuditLogInterface / HsmAuditEvent عمليات التوقيع المدعومة بوحدة ⁨HSM⁩ لطبقة الأمان. تُعرِّف MetricsCounterInterface، وMetricsGaugeInterface، وMetricsHistogramInterface، وTraceSpanInterface أشكال المقاييس والتتبُّع. وتُوفّر تنفيذات NoOp* بديلاً خاملاً كاملاً، بحيث يستطيع المحرّك بثّ المقاييس والنطاقات دون خلفية مُهيَّأة.

الثبات: تجريبي. سجل ⁨SIEM⁩ موسوم داخلياً بالدورة بدلاً من حمل @since ثابت بصيغة الإصدار الدلالي (⁨semver⁩)، أمّا سطح إعداد التقارير فهو @since 5.1.0. السطوح وظيفية ومُختبَرة، لكن أشكال واجهة برمجة التطبيقات (⁨API⁩) قد تتطوّر. عامِل صيغة السجل (⁨JSON⁩ القانوني + سلسلة التجزئة) بصفتها العقد المستقر، وواجهة ⁨PHP⁩ البرمجية كشيء لم يستقر بعد.

سطح ⁨API⁩

الفئة	الأعضاء الرئيسيون	الدور
HashChainSiemEventLog	emit(SiemEvent)، verifyIntegrity(): ?int، readAll(): Generator	سجل ⁨SIEM⁩ مقيَّد بسلسلة تجزئة ومقاوم للعبث
SiemEvent	toCanonicalJson()	حدث ⁨SIEM⁩ مُصنَّف
SiemEventSeverity / SiemEventType (تعدادان)	التصنيف	يُصنّف خطورة الحدث ونوعه
CorrelationContext / CorrelationIdGenerator	تتبُّع الارتباط	يربط الأحداث ذات الصلة عبر الارتباط
RenderReportBuilder / RenderReport	تجميع التقارير	يبني تقارير لكل عملية عرض (@since 5.1.0)
PilotReportAggregator	addReport()، count()، getSummary()، toJson()، toMarkdown()، exportReportsJson()	يُجمِّع تقارير العرض (@since 5.1.0)
PilotSummary	toArray()، toJson()، toMarkdown()	يُلخّص مُخرَجات مراجعة العمليات (@since 5.1.0)
HsmAuditLogInterface / HsmAuditEvent	سجل تدقيق ⁨HSM⁩	يسجّل تدقيقات عمليات ⁨HSM⁩
NoOpSiemEventEmitter، NoOpMetricsCounter، NoOpTraceSpan، …	بدائل خاملة	يوفّر تنفيذات كاملة لا تُجري أي عملية

شغّل composer docs:generate-api-php -- --module=Observability لإنشاء جدول ⁨PHPDoc⁩ الكامل.

مثال برمجي — بداية سريعة

أرسِل حدثاً وتحقّق من سلامة السجل.

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

مثال برمجي — الإنتاج

غلّف الباعث بحيث يبقى فشل التسجيل في المسار الساخن للتوقيع قراراً محلياً، بدلاً من أن يتحول إلى استثناء غير مُلتقَط.

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

الحالات الحدّية والمزالق

• يُطلق emit() الاستثناء SiemEmitterException عند أخطاء الكتابة. على المُستدعي في المسار الساخن للتوقيع أن يغلّفه وأن يقرّر محلياً ما إذا كان سيبتلعه أو سيعيد المحاولة أو سيُجهض. الباعث لا يقرّر نيابةً عنك.
• يُعيد verifyIntegrity() فهرس أول سجل مكسور، أو null. تعني النتيجة غير الفارغة أنّ السجل مُخترَق من تلك النقطة فصاعداً. لا تثق بالسجلات عندها أو بعدها.
• يكون القفل الاستشاري flock لكل عملية وعلى الملف نفسه. يحتاج التزامن عبر المضيفين إلى وجهة خارج النطاق، مثل إعادة توجيه ⁨syslog.⁩ لا تفترض أنّ قفل الملف يُنسّق عبر الأجهزة.
• هذه سلسلة تجزئة خطية، وليست شجرة ⁨Merkle.⁩ وهي توفّر إثبات العبث، لا براهين إدراج فعّالة. لا تُسوِّقها على أنّها الأخيرة.
• بدائل NoOp* كاملة وخاملة. لا تتفرّع بناءً على توافر الخلفية بهدف “توفير العمل”. فالعملية التي لا تُجري شيئاً لا تكلّف أصلاً.

الأداء

يقرأ emit() تجزئة السجل السابق ويُلحِق سطراً واحداً تحت قفل ملف: ⁨O⁩(1) لكل حدث إضافةً إلى القفل. أمّا verifyIntegrity() فهو ⁨O⁩(⁨n⁩) في عدد السجلات لأنّه يجتاز السلسلة بأكملها. شغّله وفق جدول زمني، لا في المسار الساخن. يكون تجميع التقارير خطياً في عدد التقارير. مِلف قابلية إعادة الإنتاج هو structural: تحمل الأحداث والتقارير طوابع زمنية ومعرّفات ارتباط، لذلك قد يختلف تشغيلان في تلك الحقول بينما تظلّ بنية السلسلة حتمية.

ملاحظات الأمان

سجل ⁨SIEM⁩ ضابط أمان. يعتمد إثباته للعبث على حماية كلٍّ من ملف السجل وخطوة التحقق: خزّن الملف على تخزين ملائم للإلحاق ومُتحكَّم بالوصول إليه، وشغّل verifyIntegrity() وفق جدول زمني، وأعِد توجيه السجلات خارج النطاق بحيث لا يستطيع اختراق المضيف إعادة كتابة التاريخ بصمت. يمكن للأحداث أن تحمل سياقاً حسّاساً. طبّق التزام المشروع بتنظيف السجلات قبل بناء الحدث، لا بعد ربطه بالسلسلة، لأنّ أي إعادة كتابة مُنظَّفة ستكسر السلسلة. يسجّل سجل تدقيق ⁨HSM⁩ عمليات التوقيع، وهو نفسه ذو صلة بالأمان. عامِله بالحماية نفسها. انظر نموذج تهديد المحرّك في /modules/core/security/.

المطابقة

لا تُقدّم هذه الوحدة أي ادعاء معياري بشأن مواصفات ⁨PDF.⁩ وهي تُنفّذ آليات سلامة السجل والرصد التي يتوافق تصميمها مع ممارسات إدارة السجلات والتحقق من السلامة في ⁨NIST SP 800-92.⁩ توافق إطار الضبط هذا موثَّق في المصدر؛ وهو ليس استشهاد ⁨PDF⁩ مثبَّتاً على مقطع. تُتحقَّق مطابقة المستندات التي يُنتجها المحرّك عبر مجموعتي الأوراكل والمرجع الذهبي الموصوفتين في /modules/core/conformance/.

انظر أيضاً

• العقود / الرصد — واجهة مزوّد الخدمة (⁨SPI⁩): الاستثناءات المُهيكَلة، و⁨Spectrum⁩، وسياسة التدهور.
• وحدة القياس عن بُعد — جسر ⁨OpenTelemetry⁩ للخلفيات الخارجية.
• وحدة التدقيق — مُصدِّر أدلّة الامتثال الذي يقترن بسجل ⁨SIEM.⁩
• وحدة الأمان — عمليات التوقيع التي يسجّلها سجل تدقيق ⁨HSM.⁩
• نظرة عامة على المطابقة