OpenCRE

انتقل إلى https://www.opencre.org لرؤية OpenCRE وهو يعمل ولمزيد من الشرح. يرمز OpenCRE إلى تعداد المتطلبات المشتركة المفتوح (Open Common Requirement enumeration). وهي منصة تفاعلية لربط المحتوى بهدف توحيد المعايير والإرشادات الأمنية. توفّر وصولاً سهلاً وموثوقاً إلى المعلومات ذات الصلة عند تصميم وتطوير واختبار وشراء البرمجيات الآمنة.

يتكوّن OpenCRE من:

• التطبيق: تطبيق ويب وتطبيق أوامر (CLI) بلغة بايثون للوصول إلى البيانات، وهو يعمل علنياً على opencre.org
• بيانات الكتالوج: كتالوج للمتطلبات المشتركة (CREs)
• بيانات الربط: روابط من كل CRE إلى الأقسام ذات الصلة في مجموعة من المعايير
• أدوات وإرشادات للمساهمة في البيانات ولتشغيل التطبيق محلياً

المساهمة بالكود أو بخرائط الربط

لمعرفة كيف يمكنك المساهمة في التطبيق أو في البيانات (الكتالوج أو خرائط المعايير)، راجع المساهمة. نحن نرحّب بك حقاً!

التوثيق

• وثائق داخل التطبيق — بدء الاستخدام، الأسئلة الشائعة، ومرجع تفاعلي لواجهة برمجة التطبيقات (API)
• الأسئلة الشائعة — الأسئلة المتكررة (تُعرض أيضاً على /docs#faq)
• مواصفة OpenAPI — واجهة REST API العامة (/rest/v1/openapi.yaml عند التشغيل)

خارطة الطريق

بالنسبة لخارطة الطريق، يرجى الاطلاع على القضايا (issues).

تشغيل OpenCRE خاص بك

أنت حر في استخدام تطبيق opencre العام على opencre.org. بالإضافة إلى ذلك، يمكنك تشغيل نسختك الخاصة إذا أردت تضمين معاييرك وإرشاداتك الأمنية الخاصة، على سبيل المثال. نطلق على هذا اسم myOpenCRE.

محلياً

Docker

أسهل طريقة لتشغيل OpenCRE محلياً هي عبر تشغيل حاوية docker المنشورة. يمكنك القيام بذلك بتنفيذ:

docker run -p 5000:5000 ghcr.io/owasp/opencre/opencre:latest

بعد أن تنتهي الحاوية من تنزيل المعلومات البعيدة، يمكنك الوصول إليها على http://127.0.0.1:5000.

إذا أردت التطوير على OpenCRE أو لم يكن docker متوفراً في بيئتك، يمكنك بدلاً من ذلك تشغيله عبر CLI.

سطر الأوامر

للتشغيل خارج Docker، تحتاج إلى تثبيت OpenCRE. لتثبيت هذا التطبيق تحتاج إلى python3 وyarn وvirtualenv.

استنسخ المستودع:

git clone https://github.com/OWASP/OpenCRE

(موصى به) أنشئ وفعّل بيئة Python افتراضية:

python3 -m venv venv
source venv/bin/activate

ثبّت التبعيات:

make install

نزّل أحدث رسم بياني لـ CRE من المصدر العلوي (upstream) بتنفيذ:

make upstream-sync

يمكنك حساب ذاكرة التخزين المؤقت لتحليل الفجوات محلياً مسبقاً بعد الاستيرادات باستخدام:

make backfill-gap-analysis

لتشغيل CRE محلياً، يمكنك بعد ذلك تنفيذ:

make dev-flask

لتشغيل تطبيق CLI، يمكنك تنفيذ:

python cre.py --help

لتصدير تصنيف CRE + المعايير إلى CSV (مناسب للـ CI)، نفّذ:

python cre.py --export --csv <path/to/output.csv>

مثال:

python cre.py --export --csv artifacts/cres_and_standards.csv

ملاحظات:

• --export هو وضع تصدير مخصص وينتهي بعد كتابة ملف CSV.
• --csv مطلوب عند استخدام --export.
• يقوم هذا الوضع بتصدير بيانات التقارير من OpenCRE API ولا يعدّل قاعدة البيانات المحلية.

لتنزيل جدول بيانات CRE بعيد محلياً، يمكنك تنفيذ:

python cre.py --review --from_spreadsheet <google sheets url>

لإضافة جدول بيانات بعيد إلى قاعدة بياناتك المحلية، يمكنك تنفيذ:

python cre.py --add --from_spreadsheet <google sheets url>

لتشغيل تطبيق الويب لأغراض التطوير، يمكنك تنفيذ:

make start-containers
make start-worker

# in a separate shell
make dev-flask

بدلاً من ذلك، يمكنك استخدام ملف dockerfile مع:

make docker && make docker-run

تتطلب بعض الميزات مثل تحليل الفجوات (Gap Analysis) تشغيل قاعدة بيانات neo4j، ويمكنك تشغيلها باستخدام:

make docker-neo4j

لتشغيل التعبئة الخلفية لأزواج تحليل الفجوات المفقودة فقط (بدون تشغيل Flask)، استخدم:

RUN_COUNT=8 bash scripts/backfill_gap_analysis.sh

عمليات قاعدة بيانات الإنتاج (opencreorg)

فضّل البرامج النصية المخصصة في scripts/db/ لعمليات الإنتاج. تفرض هذه البرامج النصية ضوابط أمان وتلتقط دائماً نسخة احتياطية جديدة قبل إجراء تغييرات على قاعدة البيانات.

• النسخ الاحتياطي فقط:
  • APP_NAME=opencreorg scripts/db/backup-opencreorg.sh
• مزامنة Postgres المحلي إلى Heroku:
  • APP_NAME=opencreorg SOURCE_DB_URL="postgresql://cre:[email protected]:5432/cre" scripts/db/sync-local-to-opencreorg.sh
• تدخل SQL موجّه:
  • APP_NAME=opencreorg scripts/db/surgery-opencreorg.sh --sql-file ./tmp/change.sql

للتدخلات التدميرية (DELETE, DROP, TRUNCATE, ALTER غير القابل للعكس)، استخدم:

APP_NAME=opencreorg \
CONFIRM_DESTRUCTIVE=I_UNDERSTAND_OPENCREORG_PROD_DB_DESTRUCTIVE_ACTION \
scripts/db/surgery-opencreorg.sh --sql-file ./tmp/destructive-change.sql --destructive

أدلة التشغيل (Runbooks):

• docs/runbooks/opencreorg-db-sync-and-surgery.md
• docs/runbooks/opencreorg-db-destructive-ops-checklist.md

متغيرات البيئة لتوصيل التطبيق بقاعدة بيانات neo4jDB (الافتراضي):

• NEO4J_URL (neo4j//neo4j:password@localhost:7687)

لتشغيل تطبيق الويب للإنتاج، تحتاج إلى gunicorn ويمكنك التشغيل من داخل مجلد cre_sync:

make prod-run

ملاحظات macOS (Apple Silicon وIntel)

OpenCRE مدعوم بالكامل على macOS. الملاحظات التالية اختيارية وتهدف إلى مساعدة المساهمين في تشغيل OpenCRE محلياً على أنظمة macOS.

المتطلبات الأساسية

ثبّت الأدوات المطلوبة باستخدام Homebrew:

brew install [email protected] yarn make

ملاحظة: يُنصح باستخدام Python 3.11. قد تسبب إصدارات Python الأحدث تعارضات في التبعيات.

تحقق من إصدار Python:

python3 --version

إعداد البيئة الافتراضية

أنشئ وفعّل بيئة افتراضية صراحةً باستخدام Python 3:

python3 -m venv venv
source venv/bin/activate

قم بترقية pip:

pip install --upgrade pip

تثبيت التبعيات

ثبّت التبعيات باستخدام سير العمل القياسي:

make install

إذا واجهت مشكلات في البناء، تأكد من تثبيت Xcode Command Line Tools:

xcode-select --install

التشغيل محلياً

زامن بيانات CRE العلوية (يتطلب اتصالاً بالإنترنت):

make upstream-sync

ثم ابدأ الخادم المحلي:

make dev-flask

سيكون التطبيق متاحاً على:

http://127.0.0.1:5000

نصيحة: بالنسبة لمعظم مستخدمي macOS، يُعد التشغيل عبر Docker أبسط الطرق وأكثرها موثوقية.

استخدام OpenCRE API

راجع دليل مستخدم myOpenCRE حول استخدام OpenCRE API، على سبيل المثال، لإضافة إرشاداتك ومعاييرك الأمنية الخاصة.

بناء Docker وتشغيله

يمكنك بناء صور docker للإنتاج أو للتطوير باستخدام:

make docker-prod
make docker-dev

متغيرات البيئة المستخدمة من قبل OpenCRE هي:

إعداد البيئة

انسخ ملف الإعدادات النموذجي:

cp .env.example .env

ثم حرّر .env وقدّم القيم المناسبة لبيئتك.

المتغيرات

• قاعدة البيانات: DEV_DATABASE_URL
• Neo4j: NEO4J_URL
• Redis: REDIS_HOST, REDIS_PORT, REDIS_URL, REDIS_NO_SSL
• Flask: FLASK_CONFIG, INSECURE_REQUESTS
• التضمينات (Embeddings): NO_GEN_EMBEDDINGS, CRE_EMBED_MODEL, CRE_EMBED_EXPECTED_DIM, CRE_VALIDATE_EMBED_DIM_ON_INIT
• نماذج/إعادة محاولات LLM: CRE_LLM_CHAT_MODEL, CRE_EMBED_ALIGN_MODEL, ,

راجع .env.example للقائمة الكاملة والقيم الافتراضية.

الواجهة الخلفية LiteLLM (اختياري)

يستخدم OpenCRE LiteLLM لاستدعاءات LLM. قم بإعداد النماذج وبيانات اعتماد المزود عبر متغيرات البيئة.

مثال أدنى موصى به:

# Chat / completion models (LiteLLM model strings)
CRE_LLM_CHAT_MODEL=gemini/gemini-2.5-flash
CRE_EMBED_ALIGN_MODEL=gemini/gemini-2.5-flash

# Embedding model used for persisted vectors
CRE_EMBED_MODEL=gemini/gemini-embedding-001
CRE_EMBED_EXPECTED_DIM=3072
CRE_VALIDATE_EMBED_DIM_ON_INIT=1

# Retry policy
CRE_LLM_MAX_RETRIES=2
CRE_LLM_RETRY_SLEEP_SECONDS=15

# Provider credential (example for Gemini)
GEMINI_API_KEY=your-key

ملاحظات:

• تعامل مع التغييرات على CRE_EMBED_MODEL أو CRE_EMBED_EXPECTED_DIM كحدث ترحيل بيانات (يتطلب عادةً إعادة التضمين).
• CRE_EMBED_EXPECTED_DIM هو حارس أمان: تفشل عمليات الكتابة بسرعة عند عدم تطابق الأبعاد.
• أبقِ نماذج الدردشة/المحاذاة ونموذج التضمين قابلة للتهيئة بشكل مستقل؛ يجب أن تظل التضمينات فقط متوافقة في الأبعاد مع المتجهات المخزنة.

يمكنك تشغيل الحاويات باستخدام:

make docker-prod-run
make docker-dev-run

التطوير

يمكنك تشغيل اختبارات الواجهة الخلفية باستخدام:

make test

يمكنك الحصول على تقرير التغطية باستخدام:

make cover

حاول إبقاء التغطية فوق 70%.