الدليل

ما تقوم به فرق التطوير والأمن بعد تثبيت OSCAR، بالترتيب. استبدل العنوان https://oscar.example والمفتاح <API key> أدناه بقيم التثبيت لديك.

سير العمل العام

ترفع أنواع البناء الثلاثة قوائم SBOM بالخطوات الثلاث نفسها، لذا تبدو متماثلة في OSCAR أيًّا كان البناء الذي جاءت منه.

1. الرفع — POST /api/v1/bom (يُنشئ المشروع إن لم يكن موجودًا: autoCreate=true)
2. البحث — يعيد GET /api/v1/project/lookup?name=…&version=… معرّف المشروع
3. الوسم — يضبط PATCH /api/v1/project/{uuid} التصنيف والوصف والوسوم

الحصول على مفتاح API

يفتح مسؤول الأمن Administration → Access Management → Teams في OSCAR، ويختار فريقًا ويُنشئ مفتاح API. وتخصيص مفاتيح منفصلة لكل غرض يُبقي الصلاحيات محدودة.

على خوادم البناء وأجهزة المطورين، احفظ المفاتيح في متغيرات البيئة بدلًا من الملفات.

export SSEM_OSCAR_DTRACK_URL=https://oscar.example
export SSEM_OSCAR_DTRACK_API_KEY_TEAM_OSCAR=<API key>   # لعمليات البناء
export SSEM_OSCAR_DTRACK_API_KEY_MCP=<API key>          # لاستعلامات الذكاء الاصطناعي

مشاريع Maven

أضف إضافتين إلى pom.xml: تُنشئ cyclonedx-maven-plugin قائمة SBOM قبل التحزيم، وترفعها exec-maven-plugin في مرحلة install.

<plugin>
  <groupId>org.cyclonedx</groupId>
  <artifactId>cyclonedx-maven-plugin</artifactId>
  <version>2.9.1</version>
  <configuration>
    <schemaVersion>1.5</schemaVersion>
    <outputFormat>json</outputFormat>
    <outputName>${project.artifactId}-${project.version}.sbom</outputName>
  </configuration>
  <executions>
    <execution>
      <phase>prepare-package</phase>
      <goals><goal>makeBom</goal></goals>
    </execution>
  </executions>
</plugin>

الرفع أمر curl واحد (وهو الأمر نفسه الذي تشغّله exec-maven-plugin).

curl -X POST "$SSEM_OSCAR_DTRACK_URL/api/v1/bom" \
  -H "X-Api-Key: $SSEM_OSCAR_DTRACK_API_KEY_TEAM_OSCAR" \
  -F autoCreate=true \
  -F projectName=my-service -F projectVersion=1.0.0 \
  -F bom=@target/my-service-1.0.0.sbom.json

مشاريع npm

ضع ملف sbom-config.json في جذر المشروع وشغّل سكربت الرفع upload_sbom.py. وإذا كان ملف SBOM (bom.json) غير موجود، فإنه يشغّل أمر البناء المضبوط أولًا.

{
  "project_name": "mobile-web",
  "project_version": "5.0.2",
  "project_classifier": "APPLICATION",
  "bom_files": ["./bom.json"],
  "build_command": "npm run build",
  "tags": { "team": "front", "service-type": "frontend", "technology": "javascript",
            "build": "npm-webpack", "npm-managed": "" }
}

python3 upload_sbom.py

Ant · البناء اليدوي (ssemsbom)

للمشاريع التي لا تحتوي على pom.xml وفيها ملفات JAR فقط في lib/، تفحص أداة سطر الأوامر ssemsbom ملفات JAR، وتُنشئ SBOM بصيغة CycloneDX 1.5 وترفعها.

./install.sh                                   # يثبّت في ~/.ssemsbom ويضيفه إلى PATH
ssemsbom --config sbom-config.json             # إنشاء · رفع · وسم
ssemsbom --config sbom-config.json --no-upload # إنشاء الملف فقط

{
  "project_name": "loan-batch",
  "project_version": "2.4.1",
  "lib_dirs": ["./lib", "./ext-lib"],
  "output_file": "./build/sbom.json",
  "tags": { "team": "core", "build": "ant", "target-was": "tomcat", "ant-managed": "" }
}

كيف تُحدَّد الأسماء

تحمل ملفات JAR القديمة بيانات وصفية غير متسقة، لذا تُجرَّب المصادر من الأكثر موثوقية إلى الأقل. والقيمة التي تضبطها خطوة سابقة لا تستبدلها خطوة لاحقة أبدًا.

1. اسم الملف — commons-lang3-3.12.0.jar ← الاسم والإصدار الافتراضيان
2. pom.properties — إن وُجد، تُؤخذ منه المجموعة والاسم والإصدار جميعًا (الأكثر موثوقية)
3. MANIFEST.MF — يضيف الإصدار فقط عند غياب pom
4. جدول استنتاج المجموعة — يملأ المجموعة من أسماء المكتبات واسعة الاستخدام
5. Implementation-Vendor-Id — فقط إن بقيت فارغة وبدا كاسم نطاق
6. البحث بالتجزئة في Maven Central — فقط مع --resolve-central (يحتاج إلى شبكة)

إذا لم ينجح شيء، تبقى المجموعة unknown. الاسم الخاطئ لا يظهر كخطأ بل كـ «0 ثغرات»، لذا لا يخمّن OSCAR.

الوسوم القياسية

يجب أن تستخدم أنواع البناء الثلاثة المفاتيح نفسها لتُجمَّع معًا في الواجهة وفي إجابات الذكاء الاصطناعي. أما الوسوم بلا قيمة (ant-managed وغيرها) فتُرفق بالاسم فقط.

يُرجى إبقاء قيم الوسوم مطابقة للنشر الفعلي. فمنها تُجاب أسئلة مثل «ما الذي يعمل على أي خادم تطبيقات؟».

ربط الذكاء الاصطناعي (MCP)

خادم OSCAR MCP ملف jar واحد يعمل على Java 21. يشغّله عميل الذكاء الاصطناعي ويتواصل معه عبر STDIO. يستخدم Claude Desktop ملف إعداداته (claude_desktop_config.json)؛ ويستخدم Claude Code ملف .mcp.json الخاص بالمشروع بالشكل نفسه.

{
  "mcpServers": {
    "oscar": {
      "command": "java",
      "args": ["-jar", "/path/to/dtrack-mcp-server.jar"],
      "env": {
        "SSEM_OSCAR_DTRACK_URL": "https://oscar.example",
        "SSEM_OSCAR_DTRACK_API_KEY_MCP": "<API key>"
      }
    }
  }
}

بعد الربط، اسأل أسئلة مثل:

• «ما المشاريع التي فيها ثغرات Critical؟»
• «هل يتأثر أي مشروع بـ CVE-2021-44228؟»
• «لخّص مخالفات سياسة التراخيص في payment-api.»
• «كيف تغيّرت المشاريع الموسومة team:core منذ الأسبوع الماضي؟»

مع 47 أداة، اختر نموذجًا داخليًا يدعم استدعاء الأدوات. فالنماذج التي لا تدعمه تجيب بالتخمين بدلًا من استدعاء الأدوات.

محرك ترجمة التراخيص

تُترجَم نصوص التراخيص الكاملة بواسطة أحد ثلاثة محركات، يُختار عند التثبيت بما يناسب سياستك.

تُضاف الترجمة بالشكل 【الترجمة】 + 【النص الأصلي】. وإذا تعذّر الوصول إلى المحرك، يُعرض النص الأصلي فقط.

الأسئلة الشائعة

هل تُرفع الشيفرة المصدرية إلى OSCAR؟

لا. تحتوي SBOM على أسماء المكتبات وإصداراتها وتجزئاتها فقط.

هل يعمل في الشبكات المعزولة؟

نعم. يعمل OSCAR في الشبكة الداخلية ولا يُجلب عبر جسر الشبكة إلا بيانات الثغرات. ولا يوجد مسار لخروج البيانات الداخلية.

ماذا لو أجاب الذكاء الاصطناعي خطأً؟

يستدعي الذكاء الاصطناعي الأدوات فقط لجلب بيانات المحرك، ولا يحكم من تلقاء نفسه. وتُعرض أسماء الأدوات المستخدمة مع الإجابة، فيمكنك التحقق من البيانات نفسها على الشاشة.

هل يمكن ترقية محرك التحليل (Dependency-Track)؟

نعم. يعمل OSCAR أمام المحرك دون تعديله، لذا تثبّت الإصدارات الرسمية كما هي. يقرأ سجل الرفع جزءًا من قاعدة بيانات المحرك، لذا تحقّق مرة بعد الترقية من أن السجل يستمر في التراكم.

ماذا عن ملفات JAR التجارية أو الداخلية؟

المكونات التي لا تتوفر عنها معلومات في المستودعات العامة أو داخل ملف JAR لا يمكن التعرف عليها وتبقى unknown. وقد تفوتها مطابقة الثغرات، لذا تتبّعها بشكل منفصل.

أسئلة أخرى؟ راسلنا على halo@levelupsoft.com.