ماسح PII بالذكاء الاصطناعي

أداة أمنية داخلية لاكتشاف المعلومات الشخصية القابلة للتعريف (PII) في قواعد بيانات PostgreSQL ومشاريع Jira

نظرة عامة

ماسح PII بالذكاء الاصطناعي هو أداة شاملة تركز على الأمان، مصممة لفرق أمن التطبيقات والخصوصية لاكتشاف وفهرسة المعلومات الشخصية القابلة للتعريف (PII). يدعم هدفين للمسح:

• قواعد بيانات PostgreSQL — اكتشاف PII على مستوى الأعمدة عبر مخططات تطبيقك
• Jira — مسح فوري أو مجدول للمشكلات والتعليقات بحثًا عن تعرّض عرضي لـ PII

يستخدم الاكتشاف خط أنابيب من ثلاث طبقات:

• الاكتشاف القائم على التعبيرات النمطية (Regex) — أنماط حتمية للبريد الإلكتروني والهاتف وSSN وبطاقات الائتمان وغيرها
• اكتشاف NER/ML — Microsoft Presidio أو spaCy للتعرّف على الكيانات (الأسماء والمواقع والتواريخ)
• تصنيف LLM اختياري — نماذج مستضافة ذاتيًا لتحليل النصوص الحرة الغامضة

الميزات الرئيسية

• اكتشاف PII متعدد الطبقات — يجمع بين regex وML وLLM الاختياري لتغطية شاملة
• تكامل Jira — مسح المشكلات والتعليقات الجديدة عبر الاستقصاء الدوري أو خطافات الويب الفورية
• مرشحات استثناء ذكية — كبت المحتوى المتوقع: @mentions وعناوين البريد الإلكتروني الخاصة بالشركة
• تقارير بطوابع زمنية — تُحفظ نتائج مسح Jira تلقائيًا في ملف JSON أو CSV مؤرخ عند كل تشغيل
• تصميم يضع الأمان أولًا — وصول قراءة فقط لقاعدة البيانات، لا استدعاءات API خارجية، احتفاظ أدنى بـ PII
• أخذ عينات ذكي — يحلل عينات بيانات تمثيلية لتقليل تأثير الأداء
• مسار تدقيق شامل — يُسجَّل كل مسح مع الإعدادات والطوابع الزمنية وإصدارات النماذج
• تسجيل آمن للخصوصية — تنقيح تلقائي لـ PII في جميع السجلات والعينات المخزنة

الأمان والخصوصية

حرج: صُممت هذه الأداة للاستخدام الداخلي فقط ضمن بيئة آمنة ومضبوطة.

ضابط الأمان	التنفيذ
منع تسريب البيانات	لا استدعاءات API من أطراف ثالثة؛ يجب أن تكون نقاط نهاية LLM مستضافة ذاتيًا
وصول بأقل صلاحية	دور قاعدة بيانات للقراءة فقط دون صلاحية كتابة على بيانات التطبيق
تقليل PII	تخزّن النتائج البيانات الوصفية فقط وعينات منقّحة بشدة
مسار التدقيق	تُسجَّل جميع عمليات المسح مع تفاصيل من/ماذا/متى/كيف
تسجيل آمن	سجلات منظمة مع تنقيح تلقائي لحقول PII
نقل مشفّر	SSL/TLS مطلوب لجميع اتصالات قاعدة البيانات
التحقق من خطافات الويب	التحقق من توقيع HMAC-SHA256 لأحداث Jira الواردة

جدول المحتويات

• التثبيت — مسح مخطط قاعدة البيانات
• التثبيت — مسح Jira
• الإعدادات
• الاستخدام — مسح قاعدة البيانات
• الاستخدام — تكامل Jira
• البنية
• طرق الاكتشاف
• مخطط قاعدة البيانات
• أمثلة
• استكشاف الأخطاء وإصلاحها
• مواضيع متقدمة
• المساهمة

---

التثبيت — مسح مخطط قاعدة البيانات

استخدم هذا إذا كنت تريد مسح قاعدة بيانات PostgreSQL بحثًا عن PII عبر الأعمدة.

الخطوة 1 — التثبيت الأساسي

# Clone the repository
cd PIIHunter

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download spaCy NER model (~800MB)
python -m spacy download en_core_web_lg

الخطوة 2 — إنشاء دور قاعدة بيانات للقراءة فقط

نفّذ هذا بصفتك مستخدمًا فائقًا في PostgreSQL:

CREATE ROLE pii_scanner_readonly WITH LOGIN PASSWORD 'your_secure_password';
GRANT CONNECT ON DATABASE your_database TO pii_scanner_readonly;
GRANT USAGE ON SCHEMA public, app_data TO pii_scanner_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public, app_data TO pii_scanner_readonly;

الخطوة 3 — تهيئة البيئة

cp .env.example .env
# Fill in DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD

الخطوة 4 — تهيئة مخطط البيانات الوصفية

ينشئ مخطط security_pii حيث يتم تخزين نتائج الفحص. شغّله مرة واحدة:

python -m pii_scanner.cli init-schema

الخطوة 5 — تشغيل أول فحص لك

# Preview candidate columns (no data read)
python -m pii_scanner.cli discover

# Run PII detection
python -m pii_scanner.cli scan --sample-size 1000

# View results
python -m pii_scanner.cli report

التحقق من الاتصال في أي وقت

python -m pii_scanner.cli test-connection

---

التثبيت — فحص Jira

استخدم هذا إذا كنت تريد فحص مشكلات Jira والتعليقات بحثًا عن تعرّض معلومات التعريف الشخصية (PII) عن طريق الخطأ.

التثبيت الأساسي (الخطوة 1 أعلاه) مطلوب أولًا. إعداد قاعدة البيانات (الخطوات 2–4) غير مطلوب إذا كنت تريد فحص Jira فقط.

القسم الفرعي أ — REST API (الاستقصاء الدوري)

يستقصي Jira عند الطلب بحثًا عن النشاط في آخر N ساعة. لا حاجة إلى خادم.

الخطوة 1 — التثبيت الأساسي (إذا لم يكن قد تم بالفعل)

cd PIIHunter
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m spacy download en_core_web_lg

الخطوة 2 — إنشاء رمز API لـ Jira

1. انتقل إلى https://id.atlassian.com → Security → API tokens
2. انقر على Create API token، وأعطِه اسمًا، وانسخ الرمز

الخطوة 3 — تهيئة البيئة

cp .env.example .env

قم بتحرير .env واملأ تفاصيل Jira الخاصة بك:

JIRA_URL=https://yourcompany.atlassian.net
[email protected]
JIRA_API_TOKEN=your_api_token_here

# Optional — leave empty to scan all projects
# JIRA_PROJECT_KEYS=ENG,OPS,SUPPORT

# Emails from these domains will NOT be flagged as PII
COMPANY_EMAIL_DOMAINS=yourcompany.com

الخطوة 4 — اختبار الاتصال

يتحقق من بيانات الاعتماد الخاصة بك، ويسرد المشاريع التي يمكن الوصول إليها، ويجلب عينة من المشكلات الأخيرة:

python -m pii_scanner.cli jira test

Expected output:

Testing connection to https://yourcompany.atlassian.net...

  Auth          ✓  logged in as Jane Smith ([email protected])
  Projects      ✓  3 accessible: ENG, OPS, SUPPORT
  Project ENG   ✓  accessible

  Recent issues (no time filter):
    ENG-101  Fix login timeout on mobile
    ENG-100  Update password policy

إذا فشل هذا، تحقق من رمز API الخاص بك ومن أن JIRA_EMAIL يطابق الحساب الذي تم إنشاء الرمز له.

الخطوة 5 — تشغيل فحص

# Scan last 24 hours
python -m pii_scanner.cli jira scan

# Custom lookback window
python -m pii_scanner.cli jira scan --hours 48

---

القسم الفرعي ب — Webhook (الوقت الفعلي)

يبدأ خادم HTTP يستقبل أحداث Jira ويفحصها فورًا عند وصولها. يتطلب نقطة نهاية يمكن الوصول إليها علنًا.

الخطوة 1 — التثبيت الأساسي + إعداد REST API (أكمل الخطوات 1–4 من القسم الفرعي أ أولاً)

الخطوة 2 — تثبيت تبعيات webhook

pip install fastapi uvicorn

الخطوة 3 — أضف إعداد webhook إلى .env

# Secret used to verify requests genuinely come from Jira
JIRA_WEBHOOK_SECRET=your_webhook_secret
JIRA_WEBHOOK_PORT=8080

الخطوة 4 — تشغيل خادم webhook

python -m pii_scanner.cli jira webhook

# Custom port
python -m pii_scanner.cli jira webhook --port 9090

الخطوة 5 — تسجيل الـ webhook في Jira

1. في Jira انتقل إلى Project Settings → Webhooks → Create webhook
2. اضبط URL على http://yourserver:8080/webhook
3. ضمن Events اختر:
   • Issue → created
   • Comment → created
4. اضبط السر ليطابق JIRA_WEBHOOK_SECRET في ملف .env الخاص بك
5. احفظ

سيقوم Jira الآن بإرسال POST إلى خادمك لكل مشكلة وتعليق جديد. يعالج الماسح الضوئي كل واحد منها فورًا.

نقاط النهاية المتاحة:

نقطة النهاية	الغرض
POST /webhook	يستقبل أحداث Jira
GET /health	يؤكد أن الخادم يعمل

ملاحظة الإنتاج: لا تعرّض uvicorn مباشرةً للإنترنت. راجع قسم إعداد Webhook للإنتاج ضمن المواضيع المتقدمة.

---

الإعدادات

تُدار جميع الإعدادات عبر متغيرات البيئة في .env. انسخ .env.example للبدء.

اتصال قاعدة البيانات