> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# سجلات التدقيق

> تتبع جميع أنشطة واجهة برمجة التطبيقات (API) والأحداث الأمنية وتدقيق الامتثال.

تحتفظ Truthlocks بسجلات تدقيق شاملة لمراقبة الأمان، وتقارير الامتثال، واستكشاف الأخطاء التشغيلية وإصلاحها.

## ما يتم تسجيله

تولد كل عملية API حدث تدقيق. يشمل ذلك العمليات الناجحة، والمحاولات الفاشلة، والأحداث المتعلقة بالأمان.

> [card] عمليات API
>
> * سك التصديق \* إلغاء التصديق \* المُصدر
>   الإنشاء/التعديل \* تسجيل المفتاح

> [card] الأحداث الأمنية
>
> * فشل المصادقة \* رفض الإذن \* تجاوز حد المعدل \*
>   نشاط مشبوه

> [card] إجراءات الحوكمة
>
> * موافقة/رفض المُصدر \* تعليق المُصدر \* تعيينات الأدوار \* مفتاح API
>   الإدارة

> [card] نشاط المستخدم
>
> * تسجيل دخول/خروج المستخدم \* تغييرات كلمة المرور \* دعوات المستخدمين \* تغييرات الأدوار

## هيكل حدث التدقيق

يحتوي كل حدث تدقيق على سياق مفصل حول ما حدث ومن قام به ومتى:

```json theme={null}
{
  "id": "evt_abc123",
  "timestamp": "2026-01-13T12:34:56.789Z",
  "tenant_id": "tenant-uuid",
  "actor_type": "USER",
  "actor_id": "user-uuid",
  "action": "attestation.mint",
  "resource_type": "attestation",
  "resource_id": "attestation-uuid",
  "service": "trust-registry",
  "outcome": "SUCCESS",
  "metadata": {
    "issuer_id": "issuer-uuid",
    "subject": "user:12345",
    "claim": "email_verified"
  },
  "integrity_hash": "sha256:abc123..."
}
```

| الحقل | النوع | الوصف |
| - | - | - |
| `actor_type` | string | من قام بالإجراء: `USER`، `API_KEY`، أو `SERVICE` |
| `actor_id` | string | UUID للمستخدم أو مفتاح API أو الخدمة التي أطلقت الحدث |
| `action` | string | العملية التي تم تنفيذها (مثل `attestation.mint`) |
| `resource_type` | string | نوع المورد المتأثر (مثل `attestation`، `issuer`، `user`) |
| `resource_id` | string | UUID للمورد المتأثر |
| `service` | string | خدمة الواجهة الخلفية التي تعاملت مع الطلب (مثل `trust-registry`، `audit-service`) |
| `outcome` | string | `SUCCESS` أو `FAILURE` |
| `metadata` | كائن | سياق خاص بالإجراء مثل معرف المُصدر أو نوع المطالبة أو تفاصيل الخطأ |
| `integrity_hash` | string | تجزئة SHA-256 للتحقق من دليل التلاعب |

## الاستعلام عن سجلات التدقيق

### استعلام أساسي

```bash theme={null}
curl -X GET "https://api.truthlocks.com/v1/audit/events?limit=100" \
  -H "X-API-Key: tl_live_your_api_key"
```

### استعلام مفلتر

```bash theme={null}
curl -X GET "https://api.truthlocks.com/v1/audit/events" \
  -H "X-API-Key: tl_live_your_api_key" \
  -G \
  --data-urlencode "action=attestation.mint" \
  --data-urlencode "actor_id=user-uuid" \
  --data-urlencode "from=2026-01-01T00:00:00Z" \
  --data-urlencode "to=2026-01-31T23:59:59Z" \
  --data-urlencode "limit=50"
```

### معلمات التصفية

| المعلمة | النوع | الوصف |
| - | - | - |
| `action` | string | التصفية حسب نوع الإجراء (مثل `attestation.mint`) |
| `actor_id` | string | التصفية حسب المستخدم أو معرف مفتاح API |
| `resource_type` | string | التصفية حسب المورد (شهادة، مُصدر، مستخدم) |
| `from` | تاريخ ووقت | الأحداث بعد هذا الوقت (ISO 8601) |
| `to` | تاريخ ووقت | الأحداث قبل هذا الوقت (ISO 8601) |
| `limit` | عدد صحيح | الحد الأقصى للأحداث المراد إرجاعها (الافتراضي 50، الحد الأقصى 1000) |
| `cursor` | string | مؤشر ترقيم الصفحات للصفحة التالية |

## مسار تدقيق قرار السياسة

يتم تسجيل كل تقييم [issuance policy](https://docs.truthlocks.com/ar/guides/issuance-policies.md) تلقائيًا كحدث تدقيق. يسجل كل سجل `decision_id`، وإصدار السياسة، والقواعد المطابقة، ووقت التقييم، وتجزئة SHA-256 للمدخلات لإثبات عدم التلاعب. استعلم عن قرارات السياسة عن طريق التصفية على `resource_type=policy_decision`:

```bash theme={null}
curl "https://api.truthlocks.com/v1/audit/events?resource_type=policy_decision&resource_id=dec_7f3a1b" \
  -H "X-API-Key: tl_live_..."
```

راجع [مسار تدقيق القرار](https://docs.truthlocks.com/ar/guides/issuance-policies.md#decision-audit-trail) للحصول على القائمة الكاملة للحقول المسجلة.

## حالات الاستخدام الشائعة

### التحقيق الأمني

البحث عن جميع محاولات المصادقة الفاشلة لممثل معين:

```http theme={null}
GET /v1/audit/events
  ?action=auth.failure
  &actor_id=user-uuid
  &from=2026-01-12T00:00:00Z
```

### تقرير الامتثال

تصدير جميع عمليات الإثبات لفترة زمنية:

```http theme={null}
GET /v1/audit/events
  ?resource_type=attestation
  &from=2026-01-01T00:00:00Z
  &to=2026-01-31T23:59:59Z
  &limit=1000
```

### مراجعة نشاط المستخدم

شاهد كل ما فعله مستخدم معين:

```http theme={null}
GET /v1/audit/events
  ?actor_id=employee-uuid
  &limit=100
```

## الاحتفاظ بالسجلات

| المستوى | الاحتفاظ الافتراضي | تنسيق التصدير |
| - | - | - |
| مجاني | 7 أيام | JSON فقط |
| المبتدئ | 30 يومًا | JSON, CSV |
| احترافي | 90 يومًا | JSON، CSV، تكامل SIEM |
| المؤسسة | سنة واحدة (مخصص متاح) | جميع التنسيقات + البث في الوقت الفعلي |

> [!NOTE]
>
> لمتطلبات الامتثال التي تتجاوز مستوى الفئة الخاص بك
> فترة الاحتفاظ، قم بتكوين تكامل SIEM لتدفق السجلات إلى نظامك الخاص
> البنية التحتية.

### سياسات استبقاء مخصصة

يمكنك تكوين مدة الاحتفاظ بسجلات التدقيق وما إذا كانت السجلات المنتهية الصلاحية مؤرشفة أو محذوفة بشكل دائم. قم بتعيين سياسات الاحتفاظ عالميًا أو لكل بيئة.

| الحقل | النوع | الوصف |
| :- | :- | :- |
| `retention_days` | integer | عدد الأيام للاحتفاظ بسجلات التدقيق (30-3,650) |
| `hard_delete` | boolean | إذا كان `true`، فاحذف السجلات منتهية الصلاحية بشكل دائم. إذا كان `false`، فأرشيفها. |
| `export_allowed` | boolean | ما إذا كانت صادرات التدقيق مسموح بها لهذا النطاق |
| `environment_id` | string | اختياري. طبق هذه السياسة على بيئة محددة فقط. |

تحتفظ السياسة الافتراضية بالسجلات لمدة 365 يومًا، وتؤرشف (تحذف بشكل ناعم) السجلات المنتهية الصلاحية، وتسمح بالتصدير.

**احصل على سياسة الاستبقاء الحالية الخاصة بك:**

```bash theme={null}
curl https://api.truthlocks.com/v1/audit/retention \
  -H "X-API-Key: tl_live_..."
```

```json theme={null}
{
  "retention_days": 365,
  "hard_delete": false,
  "export_allowed": true,
  "environment_id": null
}
```

**تحديث سياسة الاستبقاء:**

```bash theme={null}
curl -X PUT https://api.truthlocks.com/v1/audit/retention \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "retention_days": 730,
    "hard_delete": false,
    "export_allowed": true
  }'
```

عند وجود سياسة خاصة بالبيئة، فإنها تحل محل السياسة العالمية. إذا لم يتم تعيين سياسة خاصة بالبيئة، تُطبق السياسة العالمية.

> [!WARNING]
>
> يؤدي تغيير `hard_delete` إلى `true` إلى إزالة السجلات بشكل دائم بمجرد تجاوزها نافذة الاستبقاء. لا يمكن التراجع عن هذا الإجراء. تأكد من تصدير أي سجلات تحتاجها قبل تمكين الحذف الصارم.

يتطلب تحديث إعدادات الاحتفاظ إذن `tenant.audit.retention.manage`. يتطلب عرض الإعدادات `tenant.audit.retention.read`.

## تكامل SIEM

يمكن لعملاء المؤسسات بث سجلات التدقيق في الوقت الفعلي إلى أنظمة معلومات الأمان وإدارة الأحداث (SIEM) الخارجية.

### الموفرون المدعومون

| المزود | النقل | التنسيق |
| :- | :- | :- |
| **Splunk** | جامع أحداث HTTP (HEC) | JSON |
| **Datadog** | واجهة برمجة تطبيقات إدارة السجلات | JSON |
| **AWS CloudWatch** | اشتراك السجلات | JSON |
| **Elastic/ELK** | استيعاب Elasticsearch | JSON |
| **خطاف ويب مخصص** | HTTP POST | JSON |

قم بتكوين وجهة تدفق من **الإعدادات > التدقيق > SIEM** في وحدة التحكم، أو قم بإدارة الوجهات برمجيًا من خلال [واجهة برمجة تطبيقات تكوين SIEM](https://docs.truthlocks.com/ar/api-reference/audit/siem/create.md). للحصول على إرشادات إعداد المزود خطوة بخطوة، راجع [دليل تكامل SIEM](https://docs.truthlocks.com/ar/guides/siem-integration.md).

### إنشاء وجهة SIEM

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/audit/siem \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "splunk",
    "endpoint": "https://hec.splunk.example.com:8088/services/collector",
    "token": "your-hec-token",
    "enabled": true
  }'
```

```json theme={null}
{
  "id": "siem_abc123",
  "provider": "splunk",
  "endpoint": "https://hec.splunk.example.com:8088/services/collector",
  "enabled": true,
  "created_at": "2026-06-30T12:00:00Z",
  "status": "active"
}
```

استبدل `provider` بأحد الخيارات التالية: `splunk`، `datadog`، `cloudwatch`، `elastic`، أو `webhook`. يتطلب كل مزود `endpoint` وجهة وبيانات اعتماد للمصادقة (`token` لـ Splunk وDatadog وElastic؛ `access_key_id` و`secret_access_key` لـ CloudWatch؛ `secret` لـ webhooks المخصصة).

### قائمة وجهات SIEM

استرداد جميع وجهات البث المكونة لمستأجرك.

```bash theme={null}
curl https://api.truthlocks.com/v1/audit/siem \
  -H "X-API-Key: tl_live_..."
```

### تحديث وجهة SIEM

تغيير نقطة النهاية أو بيانات الاعتماد أو الحالة الممكّنة لوجهة موجودة.

```bash theme={null}
curl -X PUT https://api.truthlocks.com/v1/audit/siem/siem_abc123 \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://hec-new.splunk.example.com:8088/services/collector",
    "token": "your-new-hec-token",
    "enabled": true
  }'
```

### حذف وجهة SIEM

إزالة وجهة تدفق. يتم تفريغ الأحداث قيد التنفيذ قبل حذف الوجهة.

```bash theme={null}
curl -X DELETE https://api.truthlocks.com/v1/audit/siem/siem_abc123 \
  -H "X-API-Key: tl_live_..."
```

### التسليم والتخزين المؤقت

بمجرد التمكين، يتم بث كل حدث تدقيق إلى وجهتك في الوقت الفعلي جنبًا إلى جنب مع السجل القياسي داخل النظام الأساسي. إذا كانت الوجهة غير قابلة للوصول، يتم تخزين الأحداث مؤقتًا وإعادة محاولتها مع تراجع أسي لمدة تصل إلى 24 ساعة. يمكنك مراقبة صحة التسليم في حقل `status` الذي يتم إرجاعه بواسطة نقطة نهاية القائمة — القيم المحتملة هي `active`، `degraded` (إعادة المحاولة)، و `failed`.

> [!WARNING]
>
> **ميزة المؤسسات:** يتطلب تدفق السجلات في الوقت الفعلي فئة المؤسسات.
> اتصل بالمبيعات للحصول على مساعدة في الإعداد.

## الخطوات التالية

> [card] [تكامل SIEM](https://docs.truthlocks.com/guides/siem-integration.md)
>
> بث أحداث التدقيق إلى Splunk أو Datadog أو CloudWatch أو Elastic أو خطاف ويب مخصص.

> [card] [صادرات الامتثال](https://docs.truthlocks.com/guides/compliance-exports.md)
>
> تصدير بيانات التدقيق بتنسيقات SOC 2 و GDPR و HIPAA.

> [card] [تعزيز ضد إساءة الاستخدام](https://docs.truthlocks.com/security/abuse-hardening.md)
>
> اكتشاف ومنع إساءة الاستخدام باستخدام بيانات التدقيق.

> [card] [حدود المعدل](https://docs.truthlocks.com/ops/limits.md)
>
> فهم سلوك تحديد المعدل في سجلات التدقيق.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.