owasp-dep-scan/dep-scanماسح ضوئي للثغرات الأمنية في التبعيات من الجيل التالي مع تحليل الوصول، توليد SBOM، تدقيق التراخيص، ومسح صور الحاويات لتكامل CI/CD.
OWASP dep-scan هي أداة تدقيق أمني ومخاطر من الجيل التالي تستند إلى الثغرات المعروفة والإرشادات وقيود التراخيص لتبعيات المشروع. يتم دعم كل من المستودعات المحلية وصور الحاويات كمدخلات، والأداة مثالية للتكامل مع منصات ASPM/VM وفي بيئات CI.
تدفقات بيانات مفصلة لتحديد كل من المسارات القابلة للوصول وغير القابلة للوصول في تطبيقك بناءً على السياق الكامل.
يقوم dep-scan بحساب إمكانية الوصول لسبعة أنظمة بيئية للغات من خلال أربع قطاعات. يتم وضع علامة قابل للوصول على حزمة ثغرات كودها موجود فعليًا على مسار منفذ، بينما الحزمة التي تم إعلانها فقط في BOM ولكن لم يتم استدعاؤها مطلقًا لا يتم وضع علامة عليها. كل قطاع يغذي نفس محرك الوصول المشترك والمفهرس بمفاتيح purl، لذا فإن السلوك موحد عبر اللغات. إمكانية الوصول مفعلة افتراضيًا (--reachability-analyzer FrameworkReachability); SemanticReachability يضيف بالإضافة إلى ذلك الخدمات التي تم الوصول إليها ونقاط النهاية وإمكانية الوصول بعد البناء (ثنائي/حاوية).
للاطلاع على المفاهيم الكامنة وراء إمكانية الوصول وتحديد الأولويات، اقرأ فصول نموذج الوصول و تحديد الأولويات. للحصول على أمثلة عملية لكل لغة، راجع أدلة اللغات. بالنسبة لقصة الامتثال (VDR و CSAF VEX)، راجع دليل VDR و دليل CSAF VEX.
إمكانية الوصول مفعلة افتراضيًا تحت --profile research، وهو ما يستخدمه dep-scan عند تفعيل إمكانية الوصول. الأوامر أدناه كافية للبدء؛ تغطي أدلة كل لغة دقة الثنائيات، وأمان الواجهة الخلفية والشبكة، ومتطلبات الاستعادة، والأمثلة العملية على الملفات الثابتة في المستودع.
Rust (rusi). يقوم cdxgen بتشغيل rusi ويحتفظ بتقريره، والذي يقوم dep-scan بتحويله إلى المسار المشترك، لذا فإن crate تم استدعاؤه فعليًا (على سبيل المثال time::now() لـ RUSTSEC-2020-0071) يكون قابلًا للوصول بينما crate موجود فقط لا يكون كذلك. راجع دليل إمكانية الوصول في Rust.```bash
depscan -i ./my-rust-app -o ./reports --profile research
**Go (golem).** يستدعي dep-scan [golem](https://github.com/cdxgen/cdxgen-plugins-bin) مباشرة لمشاريع Go (يحتاج إلى `go` في `PATH`)، ويضع علامة "قابل للوصول" (Reachable) على الوحدة عندما تكون دوالها على مسار متتبع. استخدم `--go-analyzer-network offline` للمستودعات غير الموثوقة مع وجود ذاكرة تخزين مؤقتة دافئة للوحدة. راجع [دليل الوصولية لـ Go](https://depscan.readthedocs.io/languages/go-reachability).```bash
depscan -i ./my-go-app -o ./reports -t go
.NET (dosai). يقوم cdxgen بتشغيل dosai، الذي يُصدر حكمًا صريحًا حول قابلية الوصول لكل حزمة (PackageReachability مع ReachabilityKind و Confidence) يعامله dep-scan على أنه موثوق، لذا فإن حزمة NuGet تسمى فعليًا (على سبيل المثال JsonConvert.DeserializeObject على مدخلات مُتحكم بها) تكون قابلة للوصول. امسح شجرة مستعادة (restored tree) بحثًا عن purls ذات إصدارات. انظر .NET دليل قابلية الوصول.```bash
depscan -i ./my-dotnet-app -o ./reports -t dotnet
**JVM, JavaScript/TypeScript, Python, and PHP (atom).** تشارك هذه النظم الأربعة المُقطِّع [atom](https://github.com/AppThreat/atom) الذي يبني تمثيلاً وسيطًا غير مرتبط بلغة ويقوم بالتقطيع الثابت. راجع [JVM, JS, Python, and PHP reachability guide](https://depscan.readthedocs.io/languages/jvm-js-python-php-reachability).```bash
depscan --profile research -t java -i ./my-java-app -o ./reports --explain
للتجاوز عن إمكانية الوصول الموجهة نحو الإطار إلى طبقات نقطة النهاية والخدمة وما بعد البناء، مرر --reachability-analyzer SemanticReachability مع --bom-dir من BOMs دورة الحياة. راجع دليل إمكانية الوصول الدلالي.
افهم CVEs بوضوح دون الحاجة لقراءة الوصف.
ركز فقط على CVEs التي تحتاج انتباهك.
ابق دائمًا متقدمًا بخطوة مع التنبؤ المتقدم بالثغرات والاستغلال.
dep-scan مثالي للاستخدام أثناء التكامل المستمر (CI) وكتطوير محلي.
sudo npm install -g @cyclonedx/cdxgen
pip install owasp-depscan
pip install owasp-depscan[all]
سيؤدي هذا إلى تثبيت أمرين هما `cdxgen` و`depscan`.
يمكنك استدعاء الأمر scan مباشرة مع الخيارات المختلفة.```bash
cd <project to scan>
depscan --src $PWD --reports-dir $PWD/reports
فيما يلي القائمة الكاملة للخيارات:```text usage: depscan [-h] [--config CONFIG] [--no-banner] [-i SRC_DIR_IMAGE] [-o REPORTS_DIR] [--csaf] [--profile {appsec,research,operational,threat-modeling,license-compliance,generic,machine-learning,ml,deep-learning,ml-deep,ml-tiny}] [--lifecycle {pre-build,build,post-build} [{pre-build,build,post-build} ...]] [--technique {auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} [{auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} ...]] [--bom-engine {auto,CdxgenGenerator,CdxgenServerGenerator,CdxgenImageBasedGenerator,BlintGenerator} | --vulnerability-analyzer {auto,VDRAnalyzer,LifecycleAnalyzer}] [--reachability-analyzer {off,FrameworkReachability,SemanticReachability}] [--no-suggest] [--risk-audit] [--cdxgen-args CDXGEN_ARGS] [--private-ns PRIVATE_NS] [-t PROJECT_TYPE [PROJECT_TYPE ...]] [--bom BOM | --bom-dir BOM_DIR | --purl SEARCH_PURL] [--report-template REPORT_TEMPLATE] [--report-name REPORT_NAME] [--deep] [--fuzzy-search] [--search-order {purl,pcu,cpe,cpu,url}] [--no-universal] [--no-vuln-table] [--server] [--server-host SERVER_HOST] [--server-port SERVER_PORT] [--cdxgen-server CDXGEN_SERVER] [--debug] [-q | --explain] [-v]
Fully open-source security and license audit for application dependencies and container images based on known vulnerabilities and advisories.
options: -h, --help show this help message and exit --config CONFIG Path to the configuration file. Default: $PWD/.config/depscan.toml --no-banner Do not display the logo and donation banner. Please make a donation to OWASP before using this argument. -i, --src SRC_DIR_IMAGE Source directory or container image or binary file -o, --reports-dir REPORTS_DIR Reports directory --csaf Generate a OASIS CSAF VEX document --profile {appsec,research,operational,threat-modeling,license-compliance,generic,machine-learning,ml,deep-learning,ml-deep,ml-tiny} Profile to use while generating the BOM. For granular control, use the arguments --bom-engine, --vulnerability-analyzer, or --reachability-analyzer. --lifecycle {pre-build,build,post-build} [{pre-build,build,post-build} ...] Product lifecycle for the generated BOM. Multiple values allowed. --technique {auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} [{auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} ...] Analysis technique to use for BOM generation. Multiple values allowed. --bom-engine {auto,CdxgenGenerator,CdxgenServerGenerator,CdxgenImageBasedGenerator,BlintGenerator} BOM generation engine to use. Defaults to automatic selection based on project type and lifecycle. --vulnerability-analyzer {auto,VDRAnalyzer,LifecycleAnalyzer} Vulnerability analyzer to use. Defaults to automatic selection based on bom_dir argument. --reachability-analyzer {off,FrameworkReachability,SemanticReachability} Reachability analyzer to use. Default FrameworkReachability. --no-suggest Disable suggest mode --risk-audit Perform package risk audit (slow operation). Npm only. --cdxgen-args CDXGEN_ARGS Additional arguments to pass to cdxgen --private-ns PRIVATE_NS Private namespace to use while performing oss risk audit. Private packages should not be available in public registries by default. Comma separated values accepted. -t, --type PROJECT_TYPE [PROJECT_TYPE ...] Override project types if auto-detection is incorrect. Multiple values supported. --bom BOM Examine using the given Software Bill-of-Materials (SBOM) file in CycloneDX format. Use cdxgen command to produce one. --bom-dir BOM_DIR Examine all the Bill-of-Materials (BOM) files in the given directory. --purl SEARCH_PURL Scan a single package url. --custom-data CUSTOM_DATA Path to directory containing custom vulnerability data (JSON/YAML/TOML) to override/augment results. --report-template REPORT_TEMPLATE Jinja template file used for rendering a custom report --report-name REPORT_NAME Filename of the custom report written to the --reports-dir --deep Perform deep scan by passing this --deep argument to cdxgen. Useful while scanning docker images and OS packages. --fuzzy-search Perform fuzzy search by creating variations of package names. Use this when the input SBOM lacks a PURL. --search-order {purl,pcu,cpe,cpu,url} Attributes to use while searching for vulnerabilities. Default: PURL, CPE, URL (pcu). --no-universal Depscan would attempt to perform a single universal scan instead of individual scans per language type. --no-vuln-table Do not print the table with the full list of vulnerabilities. This can help reduce console output. --server Run depscan as a server --server-host SERVER_HOST depscan server host --server-port SERVER_PORT depscan server port --server-allowed-hosts [SERVER_ALLOWED_HOSTS ...] List of allowed hostnames or IPs that can access the server (e.g., 'localhost 192.168.1.10'). If unspecified, no host allowlist is enforced. --server-allowed-paths [SERVER_ALLOWED_PATHS ...] List of allowed filesystem paths that can be scanned by the server. Restricts parameter in /scan requests. --cdxgen-server CDXGEN_SERVER cdxgen server url. Eg: --debug Run depscan in debug mode. -q, --quiet Makes depscan quiet. --explain Makes depscan to explain the various analysis. Useful for creating detailed reports. --explanation-mode {Endpoints,EndpointsAndReachables,NonReachables,LLMPrompts} Style of explanation needed. Defaults to Endpoints and Reachables. --annotate Include the generated text VDR report as an annotation. Defaults to true when explain is enabled; false otherwise. -v, --version Display the version
### الملفات الثنائية المستقلة (لا تتطلب Python أو Node.js)
الملفات التنفيذية أحادية الملف والمجمّعة مسبقًا مرفقة مع كل [إصدار على GitHub](https://github.com/owasp-dep-scan/dep-scan/releases). تحتوي هذه الملفات على نسخة متطابقة من [cdxgen](https://github.com/cdxgen/cdxgen) الثنائي SEA، مما يجعل إنشاء قائمة المواد (BOM) يعمل فورًا دون الحاجة إلى تثبيت Python أو Node.js أو cdxgen.
| Platform | Architecture | Asset |
| --------------------- | ------------- | --------------------------- |
| Linux (glibc) | x86_64 | `depscan-linux-amd64` |
| Linux (glibc) | arm64 | `depscan-linux-arm64` |
| Linux (musl / Alpine) | x86_64 | `depscan-linux-amd64-musl` |
| Linux (musl / Alpine) | arm64 | `depscan-linux-arm64-musl` |
| macOS | Apple silicon | `depscan-darwin-arm64` |
| macOS | Intel | `depscan-darwin-amd64` |
| Windows | x86_64 | `depscan-windows-amd64.exe` |
كل ملف مصحوب بملف `.sha256` مطابق للتحقق.```bash
# Example: Linux x86_64
curl -LO https://github.com/owasp-dep-scan/dep-scan/releases/latest/download/depscan-linux-amd64
curl -LO https://github.com/owasp-dep-scan/dep-scan/releases/latest/download/depscan-linux-amd64.sha256
sha256sum -c depscan-linux-amd64.sha256
chmod +x depscan-linux-amd64
./depscan-linux-amd64 --src $PWD --reports-dir $PWD/reports
[!NOTE] ثنائيات macOS غير موقعة حاليًا. في التشغيل الأول، قد يقوم Gatekeeper بحظرها؛ قم بإزالة سمة العزل باستخدام
xattr -d com.apple.quarantine ./depscan-darwin-arm64(أو اسمح بالثنائي تحت إعدادات النظام، الخصوصية والأمان).
[!NOTE] يتم تنزيل قاعدة بيانات الثغرات الأمنية في التشغيل الأول. يتم تضمين cdxgen فقط، وليس قاعدة بيانات الثغرات. استخدم الأمر
depscan-vdbلتحديد نسخة قاعدة بيانات معينة، على سبيل المثالdepscan-vdb download --scope appلقاعدة بيانات أصغر للتطبيقات فقط. راجع دليل قاعدة بيانات الثغرات الأمنية لمصفوفة الصور الكاملة.
جميع الثنائيات المستقلة تتضمن blint، ولكن ليس الخلفية الاختيارية nyxstone للتفكيك (التي لا تحتوي على wheels ولا تدعم Windows). لذلك، تحليل الثنائيات القائم على التفكيك العميق غير متوفر في الثنائيات المستقلة؛ استخدم حزمة Python (pip install owasp-depscan[all]) إذا كنت بحاجة إليه.
افحص مشروع Java.```bash depscan --src -o containertests -t java
امسح علامة `latest` للحاوية `shiftleft/scan-slim````bash
depscan --src shiftleft/scan-slim -o containertests -t docker
أضف license إلى النوع لإجراء تدقيق الترخيص.```bash
depscan --src shiftleft/scan-slim -o containertests -t docker license
يمكنك أيضًا تحديد الصورة باستخدام ملخص sha256```bash
depscan --src redmine@sha256:a5c5f8a64a0d9a436a0a6941bc3fb156be0c89996add834fe33b66ebeed2439e -o containertests -t docker
يمكنك أيضًا حفظ صور الحاويات باستخدام أمر docker أو podman save وتمرير الأرشيف إلى depscan للمسح.```bash docker save -o /tmp/scanslim.tar shiftleft/scan-slim:latest
depscan --src /tmp/scanslim.tar -o reports -t docker
راجع اختبارات docker ضمن سير عمل GitHub action لهذا المستودع لمزيد من الأمثلة.
### مسح المشاريع محليًا (حاوية Docker)
يمكن استخدام صورة الحاوية `ghcr.io/owasp-dep-scan/dep-scan` لإجراء الفحص.
للمسح بالإعدادات الافتراضية```bash
docker run --rm -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports
للمسح باستخدام تكوين قائم على متغيرات البيئة المخصصة```bash
docker run --rm
-e VDB_HOME=/db
-e GITHUB_TOKEN=
-v /tmp:/db
-v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports
في المثال أعلاه، يتم تثبيت `/tmp` كـ `/db` داخل الحاوية. يتم بعد ذلك تحديد هذا الدليل كـ `VDB_HOME` لتخزين معلومات الثغرات الأمنية مؤقتًا. بهذه الطريقة يمكن تخزين قاعدة البيانات مؤقتًا وإعادة استخدامها لتحسين الأداء.
### وضع الخادم
يمكن تشغيل dep-scan و cdxgen في وضع الخادم. استخدم ملف docker-compose المرفق للبدء.```bash
git clone https://github.com/owasp-dep-scan/dep-scan
docker compose up
ملف compose المرفق يضبط DEPSCAN_SERVER_API_KEY على قيمة مؤقتة للتطوير افتراضياً بحيث يمكن لخدمة dep-scan الارتباط بـ 0.0.0.0. قم بتجاوز هذه القيمة قبل كشف الخدمة خارج مختبر محلي.```bash
depscan --server --server-host 127.0.0.1 --server-port 7070
إذا كنت بحاجة إلى ربط dep-scan بعنوان غير محلي، قم بتعيين مفتاح API أولاً:```bash
export DEPSCAN_SERVER_API_KEY="change-this-before-production"
depscan --server --server-host 0.0.0.0 --server-port 7070
[!IMPORTANT] يرفض dep-scan الارتباط بعنوان غير محلي بدون إما
DEPSCAN_SERVER_API_KEYأو اشتراك صريح عبرDEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND=true.
استخدم نقطة النهاية /scan لإجراء عمليات المسح.
[!NOTE] المعلمة
typeإلزامية في وضع الخادم. عند تمكين مصادقة مفتاح API، أرسل المفتاح باستخدامX-API-KeyأوAuthorization: Bearer <key>.
- مسح مستودع GitHub.```bash
curl \
-H 'Authorization: Bearer dev-only-change-me' \
--json '{"url": "https://github.com/HooliCorp/vulnerable-aws-koa-app", "type": "js"}' \
http://127.0.0.1:7070/scan \
-o app.vdr.json
## التطوير المحلي
قم بإعداد uv باتباع [الوثائق الرسمية](https://docs.astral.sh/uv/).```shell
uv sync --all-extras --all-packages
uv run depscan --help
uv run pytest
vdb --clean vdb --download-image
### مسح محلي لـ depscan```shell
uv run depscan --config .config/depscan-dev.toml
سيستخدم هذا تلقائياً الإعدادات المحددة في ملف الإعدادات المحلي file.
الوثائق الكاملة موجودة في depscan.readthedocs.io. الصفحات الرئيسية:
رخصة MIT
تم التبرع بهذا المشروع لمؤسسة OWASP في أغسطس 2023 من قبل شركة AppThreat Ltd.
يتم تمويل هذا المشروع من خلال NGI Zero Core، وهو صندوق أنشأته NLnet بدعم مالي من برنامج الإنترنت من الجيل التالي التابع للمفوضية الأوروبية. تعرف على المزيد على صفحة مشروع NLnet.
| اللغة / النظام البيئي | محرك الوصول | المحلل الافتراضي |
|---|
| Java / JVM (Groovy, Kotlin, Scala) | atom | FrameworkReachability |
| JavaScript / TypeScript | atom | FrameworkReachability |
| Python | atom | FrameworkReachability |
| PHP | atom | FrameworkReachability |
| Rust | rusi | FrameworkReachability |
| Go | golem | FrameworkReachability |
| .NET (C#, VB, F#, R) | dosai | FrameworkReachability |
path