sbomlyze

# sbomlyze

**`git diff` لملف SBOM الخاص بك.** قارن بين قائمتي مواد برمجية (Software Bills of Materials) واطّلع على ما تغيّر بين عمليات البناء والإصدارات والإطلاقات.

يقارن sbomlyze تجزئات المكوّنات (component hashes)، وليس سلاسل الإصدارات فقط. عندما يستبدل مهاجم حزمة دون رفع رقم إصدارها، يكشفه sbomlyze. تفوت المولّدات (generators) وماسحات الثغرات (vulnerability scanners) هذا الأمر.

[![CI][ci-img]][ci]
[![GitHub Marketplace][marketplace-img]][marketplace]
[![GitHub Release][release-img]][release]
[![Go Report Card][go-report-img]][go-report]
[![OpenSSF Scorecard][scorecard-img]][scorecard]
[![OpenSSF Best Practices][best-practices-img]][best-practices]
[![License: Apache-2.0][license-img]][license]
[![Downloads][download-img]][download]


[![SBOMlyze blocks a same-version hash change in a real pull request](https://assets.kitploit.com/production/public/readmes/12637/f834b700f00b5ee71103f6f5787595d834978432449ca3e794c3c9a0b3ffcb4c.gif)](https://github.com/rezmoss/sbomlyze-go-spdx-demo/pull/2)

اطّلع على سبب اختلاف هذه الإشارة عن فرق بيان الحزمة (manifest diff) أو فرق المكوّنات العادي في
[Manifest diff vs. SBOM diff vs. integrity drift](https://github.com/rezmoss/sbomlyze/blob/main/docs/manifest-vs-sbom-vs-integrity-drift.md).


> تصنع المولّدات ملفات SBOM وتجد الماسحات ثغرات CVE. يخبرك sbomlyze بما تغيّر بين ملفَي SBOM وما إذا كان ينبغي الوثوق به.
> شغّله بعد المولّد الخاص بك: `syft image:tag -o cyclonedx-json | sbomlyze - --compliance` يحلّل ملف SBOM المُولَّد ويقيّمه دون ملف مؤقت. قارنه بخط أساس (baseline) لتصنيف الانحراف (drift) وضبط بوابة خط أنابيبك (pipeline).

## البدء السريع مع GitHub Action

أضف [SBOMlyze Diff from GitHub Marketplace][marketplace] لمقارنة ملف SBOM مُودَع في المستودع
أو مُولَّد بشكل منفصل مع خط أساسه في git. الـ SHA غير القابل للتغيير أدناه هو
إجراء `v0.5.1` المنشور:```yaml
steps:
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    with:
      fetch-depth: 0

  - uses: rezmoss/sbomlyze@31503690611fda8ebba4ed2bd186eda000442594 # v0.5.1
    with:
      sbom-path: build/sbom.cdx.json
```
يكتب الـ Action ملخّص Job بشكل افتراضي ويمكنه فرض السياسة، والإبلاغ عن
انحراف السلامة، ورفع SARIF، أو الحفاظ على تعليق واحد على طلب السحب. راجع
[مرجع الـ Action الكامل](https://github.com/rezmoss/sbomlyze/blob/main/ACTION.md) للمدخلات والمخرجات والأذونات
وإرشادات الأمان. راجع
[مستودع العرض التوضيحي المباشر](https://github.com/rezmoss/sbomlyze-action-demo)
للاطلاع على تحديث تبعية ناجح وتغيير hash محظور لنفس الإصدار، مع
تشغيلات سير عمل عامة وأدلة SARIF.

للاستخدام التجريبي الخاص بكل صيغة، استخدم مثال
[Go + SPDX](https://github.com/rezmoss/sbomlyze-go-spdx-demo)،
أو [Node + CycloneDX](https://github.com/rezmoss/sbomlyze-node-cyclonedx-demo)، أو
[container](https://github.com/rezmoss/sbomlyze-container-demo). يحتوي كل منها
على خمسة سيناريوهات مراجعة قابلة لإعادة الإنتاج. يجمع
[دليل النسخة التجريبية في 10 دقائق](https://github.com/rezmoss/sbomlyze/blob/main/BETA.md) أربعة أسئلة مركّزة حول التنشيط
وجودة الإشارات.

لا يلزم إيداع ملفات SBOM المُنشأة: يسترجع `baseline: workflow-artifact`
أحدث artifact مطابق من تشغيل ناجح على الفرع الافتراضي. يُظهر
[سير عمل Syft المرافق المثبّت](https://github.com/rezmoss/sbomlyze/blob/main/examples/workflows/syft-companion.yml)
عملية الإنشاء ونشر baseline بينما يظل SBOMlyze مسؤولاً عن المراجعة والسياسة.

## لماذا sbomlyze؟

تولّد العديد من الأدوات ملفات SBOM. لكن القليل منها يقارنها، وقليل منها يخبرك
ما إذا كان التغيير روتينياً أم إشارة حمراء في سلسلة التوريد. يسدّ sbomlyze هذه الفجوة.

| القدرة | **sbomlyze** | cyclonedx-cli | sbomqs | syft / trivy |
|---|:---:|:---:|:---:|:---:|
| **diff** بين SBOM وSBOM | ✅ | أساسي | ❌ | ❌ |
| انحراف **السلامة / التلاعب** (تغيّر hash دون تغيّر الإصدار) | ✅ | ❌ | ❌ | ❌ |
| diff رسم التبعيات + مخاطر العمق العابر | ✅ | ❌ | ❌ | ❌ |
| تقييم الامتثال **NTIA / CISA / BSI** | ✅ | ❌ | ✅ | ❌ |
| تحويل الصيغ (Syft / CycloneDX / SPDX) | ✅ | ✅ | ❌ | جزئي |
| مستكشفات **TUI + Web UI** | ✅ | ❌ | ❌ | ❌ |
| بوابة السياسة + SARIF / JUnit / Markdown / HTML / Patch | ✅ | جزئي | جزئي | جزئي |

## الميزات

- **مقارنة SBOM (diffing)**: قارن بين ملفي SBOM واطّلع على المكوّنات المضافة والمحذوفة والمتغيّرة بنظرة واحدة
- **تصنيف الانحراف**: ميّز بين انحراف الإصدار و**انحراف السلامة** (تغيّر hash دون تغيّر الإصدار، مما يشير إلى تلاعب) وانحراف البيانات الوصفية
- **تقييم الامتثال**: قيّم أي SBOM مقابل العناصر الدنيا لـ **NTIA** و**CISA 2025** و**BSI TR-03183**
- **diff رسم التبعيات**: تتبّع التبعيات العابرة وعمق سلسلة التوريد
- **دعم صيغ متعددة**: Syft، CycloneDX، SPDX (JSON)
- **تحويل الصيغ**: التحويل بين صيغ CycloneDX وSPDX وSyft
- **مطابقة هوية قوية**: أسبقية PURL → CPE → BOM-ref → namespace/name
- **وضع الإحصاءات**: تحليل ملفات SBOM فردية لمقاييس التراخيص والتبعيات والسلامة
- **وضع TUI التفاعلي**: استكشف ملفات SBOM بالتنقل عبر لوحة المفاتيح والبحث
- **وضع Web UI**: مستكشف SBOM قائم على المتصفح مع رفع بالسحب والإفلات
- **محرّك السياسات**: فرض قواعد الانحراف والتراخيص ودرجة الامتثال في خطوط أنابيب CI
- **إجراء GitHub Marketplace**: بوّب طلبات السحب على انحراف SBOM مع Job Summary وSARIF ومخرجات تعليق اختيارية
- **كشف التكرار والتعارض**: اعثر على إصدارات متعددة من الحزمة نفسها ومطابقات الهوية الملتبسة
- **صيغ مخرجات متعددة**: Text، JSON، SARIF، JUnit XML، Markdown، HTML، JSON Patch
- **تحليل متسامح**: تابع عند وجود أخطاء مع تحذيرات منظّمة

## التثبيت

### Homebrew (macOS/Linux)```bash
brew install rezmoss/sbomlyze/sbomlyze
```
### نص التثبيت

يقوم نص التثبيت بتنزيل الملف التنفيذي الصحيح لنظام التشغيل/البنية الخاصة بك:```bash
# Install to ./bin
curl -sSfL https://raw.githubusercontent.com/rezmoss/sbomlyze/main/install.sh | sh

# Install to /usr/local/bin (requires sudo)
curl -sSfL https://raw.githubusercontent.com/rezmoss/sbomlyze/main/install.sh | sudo sh -s -- -b /usr/local/bin

# Install specific version
curl -sSfL https://raw.githubusercontent.com/rezmoss/sbomlyze/main/install.sh | sh -s -- -v 0.4.0
```
**خيارات المُثبِّت:**

| الخيار | الوصف |
|--------|-------------|
| `-b <dir>` | دليل التثبيت (الافتراضي: `./bin`) |
| `-d` | تمكين مخرجات التصحيح |
| `-v <ver>` | تثبيت إصدار محدد (الافتراضي: الأحدث) |

يتحقق المُثبِّت دائمًا من checksum الإصدار. عند تثبيت GitHub CLI متوافق،
يتحقق أيضًا من مصدر بناء الإصدار ويفشل بشكل مغلق إذا
لم تنجح عملية التحقق تلك.

### التثبيت عبر Go```bash
go install github.com/rezmoss/sbomlyze/cmd/sbomlyze@latest
```
### من إصدار ثنائي

قم بتنزيل أحدث إصدار ثنائي من [إصدارات GitHub](https://github.com/rezmoss/sbomlyze/releases).

بدءًا من الإصدار v0.3.7، يتم نشر أرشيفات الإصدار مع شهادات
مصنوعات GitHub. تحقق من التنزيل بشكل مستقل باستخدام:```bash
gh attestation verify ./sbomlyze_0.4.0_Linux_x86_64.tar.gz \
  --repo rezmoss/sbomlyze \
  --signer-workflow rezmoss/sbomlyze/.github/workflows/release.yml
```
تمت إزالة تعليمات مستودعات apt وrpm وapk غير الموقّعة حتى تدعم المستودعات التحقق من التوقيع الأصلي لمدير الحزم.

**مستخدمو macOS:** أزل علامة الحجر الصحي بعد التنزيل:```bash
xattr -d com.apple.quarantine ./sbomlyze
chmod +x ./sbomlyze
```
### البناء من المصدر```bash
git clone https://github.com/rezmoss/sbomlyze.git
cd sbomlyze
go build -o sbomlyze ./cmd/sbomlyze
```
## البدء السريع```bash
# Compare two SBOMs (the headline use case)
sbomlyze before.json after.json

# Analyze a single SBOM
sbomlyze image.json

# Read an SBOM from standard input
syft image:tag -o cyclonedx-json | sbomlyze -

# Use standard input on either side of a diff
syft image:tag -o cyclonedx-json | sbomlyze baseline.json -

# Score an SBOM against NTIA / CISA / BSI minimum elements
sbomlyze image.json --compliance

# Interactive TUI explorer
sbomlyze image.json -i

# Web UI (opens browser)
sbomlyze -web

# Convert between SBOM formats
sbomlyze convert syft.json --to spdx
sbomlyze convert cdx.json --to syft -o output.json

# JSON output for CI integration
sbomlyze before.json after.json --json

# SARIF output for GitHub Code Scanning
sbomlyze before.json after.json --format sarif

# Markdown report for PR comments
sbomlyze before.json after.json --format markdown

# Apply policy checks
sbomlyze before.json after.json --policy policy.json
```
## الاستخدام```
sbomlyze <sbom1|-> [sbom2|-] [options]
sbomlyze convert <sbom|-> --to <format> [-o output]

Modes:
  Single file:  sbomlyze <sbom> [--json]            Show statistics
  Interactive:  sbomlyze <sbom> -i                  Interactive explorer
  Convert:      sbomlyze convert <sbom> --to <fmt>  Convert SBOM format
  Web server:   sbomlyze -web [--port 8080]         Web UI explorer
  Two files:    sbomlyze <sbom1> <sbom2> [...]      Show diff

Use `-` in place of one SBOM path to read it from standard input.

Options:
  -i, --interactive   Interactive TUI explorer
  -web, --web         Start web UI server
  --port <port>       Web server port (default 8080)
  --json              Output in JSON format (shortcut for --format json)
  --format <format>   Output format: text, json, sarif, junit, markdown, html, patch
  --compliance        Show NTIA/CISA/BSI compliance scoring
  --policy <file>     Policy file for CI checks
  --strict            Fail on parse warnings
  --tolerant          Continue on parse warnings (default)
  --no-pager          Disable automatic paging of output
  --to <format>       Target format for convert: cyclonedx (cdx), spdx, syft
  -o, --output <file> Output file for convert (default: stdout)
  --version, -v       Show version information
  --help, -h          Show this help message
```
## الأوامر

### وضع الإحصائيات (ملف واحد)

تحليل SBOM للحصول على رؤى حول المكونات والتراخيص والتبعيات.```bash
sbomlyze image.json
```
يتضمن المخرجات سياق الفحص، والنتائج الرئيسية المكتشفة تلقائيًا، والإحصائيات:```
Scan Context:
  Tool:               syft 1.40.1
  Schema:             16.0.18
  Scan Scope:         all-layers
  Source Type:        image
  Source:             alpine:latest

Key Findings:
  💻 OS/Distro: Alpine Linux v3.21
  📦 Dominated by apk: 71 of 71 packages (100.0%)
  📂 8,542 files tracked on filesystem
  🔗 Relationships: 71 containment + 64 dependency
  📜 License profile: 72% permissive, 20% copyleft
  ⚠️  Low hash coverage: 0.0% (71 of 71 missing)
  🔍 Top catalogers: apkdb-cataloger (71)

📦 SBOM Statistics
==================

Total Components: 71

By Package Type:
  apk          71

Licenses:
  With license:    71
  Without license: 0

  Top Licenses:
    MIT                            17
    BSD-3-Clause                   8
    GPL-2.0-only                   8

Integrity:
  With hashes:    0
  Without hashes: 71

Dependencies:
  Components with deps: 65
  Total dep relations:  176
```
#### النتائج الرئيسية

يقوم sbomlyze تلقائيًا بإنشاء رؤى حول SBOM الخاص بك. بالنسبة لتحليل ملف واحد، تشمل هذه:

| النتيجة | الوصف |
|---------|-------------|
| **كشف نظام التشغيل/التوزيعة** | يحدد نظام التشغيل أو التوزيعة من بيانات SBOM الوصفية |
| **النظام البيئي المهيمن** | يُبلّغ عندما يهيمن نوع حزمة واحد (>60% من جميع الحزم) |
| **البصمة على نظام الملفات** | عدد الملفات المتتبَّعة على نظام الملفات |
| **كثافة العلاقات** | عدد علاقات الاحتواء والتبعية |
| **نقاط الموقع الساخنة** | أهم المجلدات التي توجد فيها المكونات |
| **ملف مخاطر التراخيص** | تفصيل نسب التراخيص المتساهلة/الحقوق المتروكة/غير المعروفة |
| **تحذيرات جودة البيانات** | تنبيهات عندما تكون تغطية الترخيص (<50%) أو التجزئة (<50%) أو PURL (<80%) منخفضة |
| **تحذيرات التكرار** | يُشير إلى مجموعات المكونات المكررة |
| **تفصيل الفهرسة** | أهم الماسحات/الفهارس التي اكتشفت المكونات (Syft SBOMs) |

#### مقاييس التغطية

يحسب وضع الإحصاءات نسب التغطية لتقييم جودة البيانات:

| المقياس | الوصف |
|--------|-------------|
| **تغطية PURL** | نسبة المكونات التي تحتوي على Package URLs |
| **تغطية CPE** | نسبة المكونات التي تحتوي على CPEs (جاهزية فحص الثغرات) |
| **تغطية الترخيص** | نسبة المكونات التي تحتوي على ترخيص واحد على الأقل |
| **تغطية التجزئة** | نسبة المكونات التي تحتوي على تجزئات السلامة |

#### تصنيف التراخيص

تُصنَّف التراخيص تلقائيًا إلى:

| الفئة | أمثلة |
|----------|----------|
| **الحقوق المتروكة** | GPL, LGPL, AGPL, MPL, EPL, CDDL |
| **المتساهلة** | MIT, BSD, Apache, ISC, Zlib, Unlicense |
| **الملكية العامة** | إهداءات الملكية العامة |
| **غير معروفة** | تراخيص غير معروفة أو مفقودة |

### وضع التحويل

حوّل SBOMs بين صيغ CycloneDX وSPDX وSyft JSON. يُكتشف تنسيق الإدخال تلقائيًا.```bash
# CycloneDX to SPDX
sbomlyze convert image.cdx.json --to spdx

# Syft to CycloneDX (cdx is an alias for cyclonedx)
sbomlyze convert syft-output.json --to cdx

# SPDX to Syft, writing to a file
sbomlyze convert spdx-output.json --to syft -o converted.json
```
#### صيغ الأهداف المدعومة

| الصيغة | قيمة `--to` | المخرجات |
|--------|-------------|--------|
| CycloneDX 1.5 | `cyclonedx` أو `cdx` | CycloneDX JSON مع البيانات الوصفية والتبعيات والخصائص |
| SPDX 2.3 | `spdx` | SPDX JSON مع الحزم والعلاقات والمراجع الخارجية |
| Syft | `syft` | Syft JSON مع العناصر والعلاقات والمصدر ومعلومات التوزيعة |

#### ما الذي يتم الحفاظ عليه

يحافظ التحويل على أسماء المكونات والإصدارات وPURLs وCPEs والتراخيص والتجزئات ومعلومات المورد وعلاقات التبعية. يتم نقل الحقول الخاصة بالصيغة (مثل لغة Syft وfoundBy والمواقع) عبر خصائص CycloneDX عند التحويل إلى CDX.

### وضع الفروقات (ملفان)

قارن بين ملفي SBOM لمعرفة ما تغير بين الإصدارات.```bash
sbomlyze v1.0.json v2.0.json
```
#### نظرة عامة على الفروقات

يبدأ الفرق بمقارنة بيانات وصفية جنبًا إلى جنب (أسماء الملفات، الأحجام، معلومات نظام التشغيل، معلومات الأداة، عدد المكونات) متبوعة بتفاصيل سياق الفحص عند توفرها.

#### المخرجات```
📊 Drift Summary:
  📦 Version drift:   58 components
  ⚠️  Integrity drift: 1 component (hash changed without version change!)
  📝 Metadata drift:  2 components

🔑 Key Findings:
  📈 Attack surface: +5 packages (7.0%), +120 files (3.2%)
  🚨 2 version downgrades detected: openssl 3.1.4→3.0.2, curl 8.5.0→8.4.0
  🔄 56 version upgrades (2 major, 12 minor, 42 patch) among 65 shared packages
  ⚠️  Integrity drift (1 total): 1 npm (review recommended)
  ❌ python ecosystem entirely removed (15 → 0 packages)
  ➕ New ecosystem: golang (8 packages)
  ✅ Core system packages stable: apk (71) unchanged

+ Added (2):
  + libgcrypt 1.10.3-r0
  + libgpg-error 1.49-r0

- Removed (3):
  - libapk 3.0.3-r1
  - libgcc 15.2.0-r2
  - nghttp3 1.13.1-r0

~ Changed (58):
  ~ nginx
      version: 1.29.4-r1 -> 1.27.3-r1
  ~ suspicious-pkg ⚠️  [INTEGRITY]
      hash[SHA256]: abc123 -> def456

>> Added dependencies:
  pkg:apk/alpine/libxslt: +[so:libgcrypt.so.20]

<< Removed dependencies:
  pkg:apk/alpine/libcurl: -[so:libnghttp3.so.9]

🔗 New transitive dependencies (3):
  + pkg:npm/lodash (depth 2)
    via: [pkg:npm/my-app pkg:npm/express pkg:npm/lodash]
  + pkg:npm/underscore (depth 3)
    via: [pkg:npm/my-app pkg:npm/express pkg:npm/lodash pkg:npm/underscore]

📊 New deps by depth:
  Depth 2:              1
  Depth 3+ (risky):     2 ⚠️
```
#### النتائج الرئيسية للفرق

في وضع الفرق، يقوم sbomlyze بإنشاء رؤى أغنى تلقائيًا تقارن كلا الـ SBOM:

| النتيجة | الوصف |
|---------|-------------|
| **عدم تطابق سياق الفحص** | يحذر إذا تغيّر إصدار المخطط أو نطاق الفحص بين الـ SBOM |
| **دلتا سطح الهجوم** | تغييرات عدد الحزم والملفات والعلاقات مع النسب المئوية |
| **أنظمة بيئية اختفت/ظهرت** | أنواع الحزم التي ظهرت أو اختفت بالكامل |
| **ترحيل نظام التشغيل/التوزيعة** | يكتشف التغييرات في نظام التشغيل بين عمليات الفحص |
| **تحليل تغيير الإصدار** | يحصي الترقيات مقابل التخفيضات، ويصنف التغييرات كرئيسية/ثانوية/تصحيحية |
| **تخفيضات الإصدار** | يضع علامة على التخفيضات كإشارة أمنية مع تفاصيل المكوّن |
| **سياق انحراف السلامة** | يفصّل انحراف السلامة حسب نوع الحزمة مع إرشادات المخاطر |
| **أنماط المسار السائدة** | التغييرات المركّزة حسب النوع ومسار نظام الملفات |
| **نقاط الإزالة/الإضافة الساخنة** | أهم المجلدات المتأثرة بالتغييرات |
| **الأنواع المستقرة** | أنواع الحزم ذات الأعداد المتطابقة (النواة غير المتغيرة) |
| **تحولات فئة الترخيص** | التغييرات في توازن الحقوق المتروكة/التساهمية |
| **فجوات المفهرِس** | الماسحات التي وجدت حزمًا في Before ولكن لا شيء في After |

#### عينات الحزم حسب النوع

يتم تجميع المكونات المضافة والمزالة حسب نوع الحزمة مع قوائم العينات، مما يسهّل رؤية ما تغيّر في كل نظام بيئي.

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

قيّم أي SBOM مقابل أطر العناصر الدنيا الثلاثة الرئيسية للإجابة على السؤال الذي يطرحه المدققون وفرق المشتريات باستمرار: **"هل هذا الـ SBOM مكتمل بما يكفي؟"**```bash
# Score a single SBOM
sbomlyze image.json --compliance

# Score alongside a diff
sbomlyze before.json after.json --compliance

# As JSON for CI
sbomlyze image.json --compliance --json
```
### الأطر المُقيَّمة

| الإطار | الفحوصات | المتطلبات البارزة |
|-----------|--------|----------------------|
| **NTIA Minimum Elements** (2021) | 7 | الاسم، الإصدار، المورّد، المعرّفات الفريدة (PURL/CPE)، علاقات التبعية، مؤلف SBOM، الطابع الزمني |
| **CISA 2025 Minimum Elements** (مسودة أغسطس 2025) | 10 | يضيف منتج البرمجيات، معلومات الترخيص، **تجزئة المكوّن**، واسم الأداة فوق NTIA |
| **BSI TR-03183-2** (v2.1.0، 2025) | 9 | يتطلب معلومات الاتصال بمنشئ المكوّن، **تجزئة SHA-512**، تراخيص بصيغة SPDX، ومعلومات الاتصال بمنشئ SBOM |

### عرض النتيجة

يُبلّغ كل إطار عن نسبة مئوية (الفحوصات الناجحة / إجمالي الفحوصات) بالإضافة إلى درجة إجمالية (المتوسط عبر الأطر)، مع مؤشرات الحالة:

| المؤشر | النتيجة |
|-----------|-------|
| 🟢 | ≥ 90% |
| 🟡 | 70–89% |
| 🟠 | 50–69% |
| 🔴 | < 50% |

يتضمن مخرجات JSON (`--compliance --json`) التقرير الكامل مع تفاصيل نجاح/فشل كل فحص؛ ويُضمّن تنسيق HTML تقرير الامتثال في صفحة التقرير.

### تقييد الامتثال في CI

فرض حدود الامتثال من خلال [محرك السياسات](#policy-engine). يؤدي تعيين أي حد إلى تفعيل تقييم الامتثال دون الحاجة إلى العلامة `--compliance`:```json
{
  "min_ntia_score": 85,
  "min_cisa_score": 70,
  "min_bsi_score": 80,
  "min_overall_compliance": 75
}
```
## التثبيت

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

- Python 3.8 أو أحدث
- pip (مدير حزم Python)
- Git (اختياري، للاستنساخ)

### التثبيت السريع

```bash
# استنساخ المستودع
git clone https://github.com/yourusername/kitploit-tool.git
cd kitploit-tool

# إنشاء بيئة افتراضية
python3 -m venv venv
source venv/bin/activate  # على Windows: venv\Scripts\activate

# تثبيت التبعيات
pip install -r requirements.txt

# تثبيت الحزمة
pip install -e .
```

### التثبيت عبر pip

```bash
pip install kitploit-tool
```

### التثبيت عبر Docker

```bash
# سحب الصورة
docker pull kitploit/tool:latest

# تشغيل الحاوية
docker run -it --rm kitploit/tool:latest --help
```

### التحقق من التثبيت

```bash
# التحقق من التثبيت
kitploit-tool --version

# تشغيل الاختبارات
pytest tests/
```

### استكشاف الأخطاء وإصلاحها

إذا واجهت أي مشكلات أثناء التثبيت، تحقق من النقاط التالية:

1. **إصدار Python**: تأكد من تثبيت Python 3.8 أو أحدث
   ```bash
   python3 --version
   ```

2. **صلاحيات pip**: قد تحتاج إلى استخدام `pip install --user` أو صلاحيات المسؤول

3. **التبعيات المفقودة**: قم بتثبيت حزم النظام المطلوبة
   ```bash
   # على Ubuntu/Debian
   sudo apt-get install python3-dev build-essential
   
   # على macOS
   brew install python3
   ```

4. **تعارضات البيئة الافتراضية**: تأكد من تنشيط البيئة الافتراضية قبل التثبيت

5. **مشكلات الشبكة**: إذا كنت خلف وكيل (proxy)، قم بتكوين pip وفقًا لذلك
   ```bash
   pip install --proxy http://user:pass@proxy:port kitploit-tool
   ```

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

بعد التثبيت الناجح، راجع قسم [الاستخدام](#الاستخدام) للبدء.```bash
sbomlyze image.json --policy compliance-policy.json
```
## فرق مخطط التبعيات

يتجاوز sbomlyze مجرد فروق قوائم المكونات البسيطة لتحليل مخطط التبعيات الكامل، واكتشاف مخاطر سلسلة التوريد المُدخلة عبر التبعيات العابرة.

### الميزات

| الميزة | الوصف |
|---------|-------------|
| **فرق الحواف** | التبعيات المباشرة المُضافة/المحذوفة (A يعتمد على B) |
| **إمكانية الوصول العابر** | التبعيات غير المباشرة الجديدة التي تظهر عبر المخطط |
| **تتبع الفقدان العابر** | التبعيات العابرة التي تمت إزالتها |
| **تتبع المسار** | يُظهر بالضبط كيف يتم الوصول إلى كل تبعية عابرة جديدة |
| **تتبع العمق** | عدد القفزات التي تفصل كل تبعية جديدة عن الكود الخاص بك |
| **ملخص المخاطر** | التبعيات ذات العمق 3+ تُعلَّم كمخاطر أعلى |

### لماذا يُهم العمق

التبعيات المُدخلة في عمق أكبر من المخطط:
- يصعب تدقيقها ومراجعتها
- غالبًا ما تُسحب دون موافقة صريحة
- نواقل شائعة لهجمات سلسلة التوريد (مثل حادثة event-stream)

يساعد ملخص العمق في تحديد أولويات المراجعة:

| العمق | مستوى المخاطر | الوصف |
|-------|------------|-------------|
| **1** | منخفض | التبعيات المباشرة (أنت اخترت هذه) |
| **2** | متوسط | تبعيات تبعياتك |
| **3+** | مرتفع ⚠️ | تبعيات عابرة عميقة - راجعها بعناية |

### مثال: اكتشاف التبعيات العابرة العميقة```bash
# Before: app -> express (simple, 1 dep)
# After:  app -> express -> lodash -> underscore -> deep-lib (chain of 4)

sbomlyze before.json after.json
```
```text
Usage of ./subfinder:
  -all
    	استخدام المصادر التي تتطلب مفتاح API
  -cd
    	إظهار جميع المصادر فقط
  -config string
    	ملف تكوين Subfinder (default "/root/.config/subfinder/config.yaml")
  -d string
    	النطاق للعثور على النطاقات الفرعية له
  -dL string
    	ملف يحتوي على قائمة النطاقات للعثور على النطاقات الفرعية لها
  -exclude-sources string
    	قائمة المصادر لاستبعادها من التعداد (-es)
  -json
    	إخراج JSON
  -ls
    	إظهار جميع المصادر
  -max-time int
    	دقائق لانتظار نتائج التعداد (default 10)
  -nW
    	إظهار النطاقات الفرعية الموجودة في wildcard فقط
  -o string
    	ملف لكتابة الإخراج إليه (اختياري)
  -oI
    	كتابة الإخراج بتنسيق Host,IP
  -oJ
    	كتابة الإخراج بتنسيق JSON Lines
  -r string
    	قائمة resolvers مفصولة بفواصل
  -rL string
    	ملف نصي يحتوي على قائمة resolvers
  -recursive
    	استخدام العودية للعثور على النطاقات الفرعية
  -silent
    	إظهار النطاقات الفرعية فقط
  -sources string
    	قائمة المصادر مفصولة بفواصل (-s)
  -t int
    	عدد goroutines المتزامنة (default 10)
  -timeout int
    	ثوانٍ لانتظار انتهاء المهلة قبل التخلي عن المصدر (default 30)
  -v	إظهار الإخراج المطول
  -version
    	إظهار إصدار Subfinder
``````
🔗 New transitive dependencies (3):
  + lodash (depth 2)
    via: [app express lodash]
  + underscore (depth 3)
    via: [app express lodash underscore]
  + deep-lib (depth 4)
    via: [app express lodash underscore deep-lib]

📊 New deps by depth:
  Depth 2:              1
  Depth 3+ (risky):     2 ⚠️
```
### إخراج JSON لمخطط التبعيات```json
{
  "dependencies": {
    "added_deps": {
      "pkg:npm/express": ["pkg:npm/lodash", "pkg:npm/body-parser"]
    },
    "removed_deps": {},
    "transitive_new": [
      {
        "target": "pkg:npm/underscore",
        "via": ["pkg:npm/my-app", "pkg:npm/express", "pkg:npm/lodash", "pkg:npm/underscore"],
        "depth": 3
      }
    ],
    "transitive_lost": [],
    "depth_summary": {
      "depth_1": 0,
      "depth_2": 2,
      "depth_3_plus": 2
    }
  }
}
```
## كشف الانحراف

يصنّف sbomlyze تغييرات المكوّنات إلى ثلاثة أنواع من الانحراف، مما يساعدك على التمييز بين التحديثات العادية والتغييرات التي قد تكون مشبوهة.

### أنواع الانحراف

| النوع | المؤشر | الوصف | الخطورة |
|------|-----------|-------------|----------|
| **الإصدار** | 📦 | تغيّر رقم الإصدار | عادي |
| **السلامة** | ⚠️ | تغيّر التجزئة دون تغيّر الإصدار | عالية - حقّق في الأمر! |
| **البيانات الوصفية** | 📝 | تغيّرت البيانات الوصفية فقط (التراخيص، إلخ) | منخفضة |

### انحراف السلامة (إشارة أمنية)

يحدث انحراف السلامة عندما تتغيّر تجزئة مكوّن ما بينما يبقى إصداره كما هو. قد يشير هذا إلى:

- **هجوم على سلسلة التوريد**: استُبدلت الحزمة بنسخة خبيثة
- **إعادة بناء دون رفع الإصدار**: ممارسة مشروعة لكنها سيئة
- **بيئة بناء مختلفة**: مشكلات في قابلية إعادة الإنتاج```bash
# Example output with integrity drift
~ suspicious-pkg ⚠️  [INTEGRITY]
    hash[SHA256]: abc123 -> def456
```
**توصية**: تحقق دائماً من انحراف السلامة. قد يكون حميداً، لكنه إشارة رئيسية لأمن سلسلة التوريد.

### مخرجات JSON للانحراف

ملخص الانحراف موجود داخل كائن `diff`:```json
{
  "diff": {
    "changed": [
      {
        "id": "pkg:npm/suspicious-pkg",
        "name": "suspicious-pkg",
        "changes": ["hash[SHA-256]: abc123 -> def456"],
        "drift": {
          "type": "integrity",
          "hash_changes": {
            "changed": {
              "SHA-256": {"before": "abc123", "after": "def456"}
            }
          }
        }
      }
    ],
    "drift_summary": {
      "version_drift": 55,
      "integrity_drift": 1,
      "metadata_drift": 2
    }
  }
}
```
**استخراج ملخص الانحراف:**```bash
# Get drift summary
sbomlyze before.json after.json --json | jq '.diff.drift_summary'

---

[Read more](https://github.com/rezmoss/sbomlyze)