PII-Shield 🛡️

حاوية جانبية لتنظيف السجلات بدون أي كود لـ Kubernetes. يمنع تسرب البيانات (GDPR/SOC2) عبر إخفاء المعلومات الشخصية القابلة للتعريف (PII) من السجلات قبل مغادرتها البود.

يعمل PII-Shield داخل العملية نفسها — CLI أو Sidecar أو WASM. لا توجد واجهة برمجية مستضافة ولا خادم تُرسل إليه بياناتك.

"لا تدع PII تسمم نماذج الذكاء الاصطناعي الخاصة بك." يضمن PII-Shield ألا تصل البيانات الحساسة أبدًا إلى مجموعة بيانات التدريب الخاصة بك، مما يوفر عليك إعادة تدريب النموذج المفروضة بموجب GDPR.

[!WARNING] جارٍ الترقية إلى v2.0.0؟ لقد انتقلنا في توزيع المستخدم النهائي إلى التثبيتات القائمة على Helm والحاويات الجانبية الأصلية من نوع Distroless (Distroless Native Sidecars). لم يعد Kustomize مسار تثبيت إصدار مدعومًا لمستخدمي الإنتاج، على الرغم من أن مستودع المشغّل لا يزال يحتفظ بهياكل Kustomize للتطوير المحلي وتوليد المانيفست. لم يعد الوصول إلى /bin/sh داخل الحاوية الجانبية لـ PII-Shield مدعومًا. اقرأ دليل الترحيل (Migration Guide).

نموذجا النشر

يقدم PII-Shield طريقتين متميزتين للتكامل مع بنيتك التقنية:

1. مشغّل Kubernetes (بدون كود): نموذج النشر الرئيسي لدينا. مشغّل K8s آلي بالكامل يحقن حاوية جانبية (Sidecar) عالية الأمان من نوع Distroless في البودات الخاصة بك لاعتراض السجلات وتنظيفها أثناء التنقل.
2. WASM داخل العملية (للتكاملات الأساسية): للأداء الفائق، يمكن تضمين المحرك الأساسي مباشرة عبر WASM، مما يوفر زمن استجابة <1ms بدون قفزات شبكية.

حالة المشروع وخارطة الطريق

PII-Shield هو أداة أمنية مفتوحة المصدر قيد التطوير النشط في مرحلة تحصين الإنتاج. سلسلة إصدارات v2.x تُصدر قطعًا قابلة للاستخدام من CLI والحاوية و Helm/operator و WASM SDK. مسارات الإخفاء الأساسية جاهزة للنشر المتحكم به، بينما لا تزال بعض أوضاع النشر في Kubernetes وضمانات سلسلة التوريد قيد الاستقرار.

انظر KNOWN_LIMITATIONS.md للحدود الحالية لمرحلة تحصين الإنتاج.

لماذا PII-Shield؟

غالبًا ما ينسى المطورون إخفاء البيانات الحساسة. مرشحات regex التقليدية في Fluentd/Logstash بطيئة وصعبة الصيانة وتستهلك وحدات معالجة مركزية (CPU) مكلفة على مجمعات السجلات.

يعمل PII-Shield بجوار حاوية تطبيقك مباشرة:

• محرك أساسي مُحصّن للإنتاج: محسّن للحاويات الجانبية في Kubernetes مع تخصيصات ذاكرة منخفضة على المسارات الساخنة ومطابقة regex حتمية.
• تحليل الإنتروبيا المدرك للسياق: اكتشاف الأسرار عالية الإنتروبيا حتى بدون مفاتيح (مثل Error: ... 44saCk9...) عبر تحليل كلمات السياق.
• قواعد Regex مخصصة: إخفاء حتمي للبيانات المنظمة (UUIDs, IDs) يتجاوز فحوصات الإنتروبيا للأنماط المعروفة.
• تغطية الانحدار والتلغيم (Fuzz): مختبرة ضد حالات الضغط بما في ذلك القمامة الثنائية وتداخل JSON والسجلات متعددة اللغات.
• تجزئة حتمية (Deterministic Hashing): يستبدل الأسرار بتجزئات فريدة (مثل [HIDDEN:a1b2c])، مما يسمح لفريق ضمان الجودة (QA) بربط الأخطاء دون رؤية البيانات الخام.
• إدراج مباشر (Drop-in): لا يتطلب أي تغييرات في الكود. يعمل مع أي لغة (Node, Python, Java, Go).
• دعم القائمة البيضاء: يسمح صراحةً بأنماط آمنة (مثل تجزئات git ومعرفات النظام) باستخدام PII_SAFE_REGEX_LIST لمنع النتائج الإيجابية الخاطئة.

هل تدير PII-Shield عبر عشرات المجموعات (Clusters)؟

نحن نبني Control Plane مستضافًا مع إدارة مركزية للقواعد وتنبيهات عبر Slack وتحليلات الإخفاء.

التكاملات

البناء WASM داخل العملية لـ PII-Shield يُشحن داخل GuardSpine Code، وهو إجراء GitHub Action مفتوح المصدر لحوكمة كود الذكاء الاصطناعي، والذي يضمّن الثنائي وينسبه في ملف NOTICE الخاص به.

اعتبارات الأداء

بينما PII-Shield محسّن بدرجة عالية، يتطلب الفحص العميق للسجلات المعقدة عناية دقيقة بالإعدادات.

• السجلات النصية: سريعة للغاية (>100k سطر/ثانية).
• سجلات JSON: تحليل بدون تخصيص ذاكرة (بدون حمل encoding/json الإضافي). يوزع الماسح هياكل JSON يدويًا لضمان إنتاجية عالية (~7MB/s) بدون قفزات في الذاكرة.
• توصية: الاستخدام آمن للإنتاجية العالية. نستخدم ضمانات ضد العودية (recursion) لمنع تجاوز سعة المكدس على JSON المتداخل بعمق.

التثبيت

مخطط Helm (مشغّل Kubernetes)

الطريقة الرسمية والموصى بها لنشر PII-Shield في Kubernetes هي عبر مشغّلنا الآلي بالكامل:

helm repo add pii-shield https://pii-shield.github.io/pii-shield/
helm repo update
helm install pii-shield-operator pii-shield/pii-shield-operator -n operator-system --create-namespace

يقوم هذا بنشر مشغّل PII-Shield الذي يحقن تلقائيًا حاويات جانبية (Sidecars) عالية الأمان من نوع distroless في البودات الخاصة بك دون الحاجة إلى أي تغييرات في الكود أو Dockerfile.

Docker

احصل على أحدث صورة خفيفة الوزن من Docker Hub أو GHCR:

docker pull thelisdeep/pii-shield:2.2.0
# OR from GitHub Container Registry (Enterprise):
docker pull ghcr.io/pii-shield/pii-shield:2.2.0

البناء من المصدر

يمكنك بناء الثنائي مباشرة من الكود المصدري:

go build -o pii-shield ./cmd/cleaner/main.go

الإعدادات

انظر CONFIGURATION.md للحصول على قائمة كاملة بمتغيرات البيئة، بما في ذلك:

• PII_SALT: ملح HMAC مخصص (مطلوب للإنتاج).
• PII_ADAPTIVE_THRESHOLD: تفعيل خطوط الأساس الديناميكية للإنتروبيا.
• PII_DISABLE_BIGRAM_CHECK: تحسين للسجلات غير الإنجليزية.
• PII_CUSTOM_REGEX_LIST: قواعد regex مخصصة للإخفاء الحتمي.
• PII_SAFE_REGEX_LIST: قواعد regex للقائمة البيضاء يتم تجاهلها (تُرجع التطابقات كما هي).

جدول حساسية الإنتروبيا (العتبة الافتراضية: 3.6)

بدء سريع

1. اختبر محليًا (CLI) يمكنك تمرير أي مخرجات سجل عبر PII-Shield لرؤيته يعمل فورًا:

# Emulate a log with a sensitive password
echo "Error: User password=MySecretPass123! failed login" | docker run -i --rm ghcr.io/pii-shield/pii-shield:2.2.0

# Output: Error: User password=[HIDDEN:8f3a11] failed login

2. Kubernetes (الحقن التلقائي للحاوية الجانبية) مع تثبيت مشغّل PII-Shield، تصبح حماية أحد التطبيقات أمرًا بسيطًا مثل إنشاء PiiPolicy ووضع العلامات على البودات الخاصة بك.

إنشاء سياسة:

apiVersion: core.pii-shield.io/v1alpha1
kind: PiiPolicy
metadata:
  name: strict-policy
  namespace: default
spec:
  injectionMode: "file"

وضع علامة على Deployment الخاص بك:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: secure-app
spec:
  template:
    metadata:
      labels:
        pii-shield.io/inject: "true"
      annotations:
        pii-shield.io/policy: "strict-policy"
# ...

سيقوم المشغّل تلقائيًا بحقن pii-shield-agent باستخدام نمط الحاوية الجانبية الأصلية (Native Sidecar) (K8s 1.28+) وإخفاء جميع السجلات بشكل آمن!

📋 مجانًا: قائمة مراجعة من 25 نقطة لتدقيق PII في سجلات Kubernetes — أين تتسرب PII من البودات، وأي مسارات سجلات تتجاوز عوامل التصفية لديك، وكيف تتحقق من أن الإخفاء يعمل فعليًا. احصل على قائمة المراجعة →

📦 حزم الامتثال (GDPR/HIPAA/PCI) قريبًا — احصل على وصول مبكر →

💬 هل تستخدم PII-Shield؟ أخبرنا عن نشرك → — دقيقتان، وهذا يشكل ما سيُبنى بعد ذلك.

التحقق

تم التحقق من هذا المشروع بمجموعة اختبارات متنامية تهدف إلى رفع الثقة قبل تحصين الإنتاج:

1. اختبارات الوحدة: تغطي الحالات الحدودية والدعم متعدد اللغات وسلامة JSON بتغطية >85%.
2. التلغيم (Fuzzing): التلغيم الأصلي في Go يضمن الأمان ضد الانهيار مع الإدخالات الثنائية غير الصالحة والعشوائية.
3. اختبارات الدخان (Smoke Testing): ./scripts/test-smoke.sh يختبر أحمال عمل مختلطة ويبلغ عن دقة الاكتشاف.
4. الاختبارات الشاملة من النهاية إلى النهاية (E2E): مجموعة operator/tests/run_e2e.sh تنفذ تحققًا كامل المكدس باستخدام Minikube و Helm. تبني صورًا محلية، وتجهز المشغّل بدون cert-manager، وتنشر وظائف (Jobs) مستهدفة، وتتحقق من الإخفاء الفعلي للسجلات عن طريق اعتراض مخرجات الحاوية الجانبية.

معايير الأداء

لمقارنة إنتاجية CLI الشاملة من النهاية إلى النهاية بين الفرع الحالي ومرجع أساسي:

./benchmark/run_benchmarks.sh

افتراضيًا، تقارن المعايير HEAD مع origin/main، وتحدّث origin/main، وتولّد مجموعة سجلات مختلطة، وتتبادل ترتيب التشغيل القديم/الجديد، وتبلغ عن الوسيط (median) وp95 والحد الأدنى/الأقصى وMiB/s:

BASE_REF=origin/main RUNS=9 LINES=500000 ./benchmark/run_benchmarks.sh

يقيس هذا مسار CLI الكامل من stdin إلى stdout. لمعايير مصغرة خاصة بالماسح فقط، شغّل:

go test -bench=. -benchmem ./pkg/scanner

اختبارات تكامل المشغّل

يبقي المشغّل اختبارات الوحدة السريعة منفصلة عن اختبارات تكامل Kubernetes API. لا تبدأ اختبارات المشغّل العادية خادم API محليًا:

cd operator
go test ./...

لتشغيل مجموعة تكامل وحدة التحكم القائمة على envtest:

./scripts/test-operator-integration.sh

تبدأ هذه الاختبارات خادم Kubernetes API محليًا و etcd عبر envtest، لذلك تتطلب إذنًا للارتباط بـ 127.0.0.1. في البيئات المعزولة (sandboxes) المقيدة، شغّلها في شل محلي أو بيئة Docker أو مشغل CI يسمح بالارتباط على localhost.

الدعم

PII-Shield هو بنية تحتية مفتوحة المصدر لسجلات تحافظ على الخصوصية. إذا كان هذا المشروع مفيدًا لك أو لمؤسستك، يمكنك دعم تطويره عبر GitHub Sponsors.

التحقق من الإصدار

إرشادات التحقق من المجموع الاختباري (checksum) وتجزئة الصورة (image digest) للإصدارات موثقة في docs/release-verification.md. الإصدارات المدعومة بالتوقيعات ومنشأ (provenance) تُتتبع كجزء من خارطة طريق تحصين سلسلة التوريد.

الترخيص

موزع بموجب رخصة Apache 2.0. انظر LICENSE لمزيد من المعلومات.