DockSec

ماسح أمان Docker مدعوم بالذكاء الاصطناعي يشرح الثغرات الأمنية بلغة إنجليزية بسيطة

ما هو DockSec؟

DockSec هو مشروع مختبر OWASP يسد الفجوة بين نتائج فحوصات الأمان المعقدة والإصلاحات العملية للمطورين. يدمج الماسحات الضوئية القياسية في الصناعة (Trivy, Hadolint, Docker Scout) مع الذكاء الاصطناعي لتوفير تحليل أمني مدرك للسياق.

بدلاً من إغراقك بقائمة تضم أكثر من 200 ثغرة CVE، يقوم DockSec بـ:

• ترتيب الأولويات لما يؤثر فعلياً على إعداد الحاوية الخاص بك.
• شرح الثغرات الأمنية بلغة إنجليزية بسيطة، وليس فقط بالمصطلحات الأمنية المتخصصة.
• اقتراح إصلاحات محددة لملف Dockerfile الخاص بك.
• إنشاء تقارير أمنية احترافية وتفاعلية لفريقك.

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

كيف يعمل

يتبع DockSec مساراً من أربع مراحل:

1. الفحص: يشغّل Trivy وHadolint وDocker Scout محلياً على بيئتك.
2. التحليل: يربط الذكاء الاصطناعي النتائج عبر جميع الماسحات الضوئية لإزالة الضوضاء وتقييم التأثير الواقعي.
3. التوصية: يولّد شروحات قابلة للقراءة البشرية وخطوات معالجة محددة.
4. التقرير: يصدّر النتائج القابلة للتنفيذ بصيغ HTML وPDF وJSON وCSV وSARIF وCycloneDX SBOM.

البدء

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

يقوم DockSec بتنسيق الماسحات الضوئية المحلية، لذا فهو يحتاج إلى:

أو دع DockSec يقوم بتثبيت Trivy وHadolint نيابةً عنك:```bash python -m docksec.setup_external_tools

3. تشغيل أول فحص لك

لا حاجة لمفتاح API للفحص المحلي:```bash docksec Dockerfile --scan-only

كل مزوّد لديه نموذج افتراضي معقول (OpenAI: gpt-4o، Anthropic: claude-haiku-4-5، Google: gemini-1.5-pro، Ollama: llama3.1)، لذا فإن --model هو اختياري. لتجنب تكرار العلامات، قم بتعيين متغيرات البيئة (أو ضعها في ملف .env في الدليل الذي تشغّل منه - يقوم DockSec بتحميله تلقائيًا):```bash export LLM_PROVIDER=anthropic export LLM_MODEL=claude-sonnet-5 docksec Dockerfile

الأوامر الشائعة```bash

Scan Dockerfile + Docker image (AI + scanners)

docksec Dockerfile -i myapp:latest

Scan a Docker Compose file and all its services

docksec --compose docker-compose.yml

Scan only a Docker image

docksec --image-only -i myapp:latest

Fast local scan, no AI, no API key

docksec Dockerfile --scan-only

Choose which severity levels the image scan reports (default: CRITICAL,HIGH)

docksec -i myapp:latest --image-only --severity CRITICAL,HIGH,MEDIUM

Fail the build (exit 1) if any finding is HIGH or above

docksec -i myapp:latest --image-only --fail-on high

Write only the report formats you want, to a directory of your choice

docksec Dockerfile --scan-only --format json,html --output-dir ./reports

Print results as JSON to stdout for scripts and CI pipelines

docksec -i myapp:latest --image-only --json

Write a SARIF report for GitHub Code Scanning

docksec Dockerfile --scan-only --sarif

Write a CycloneDX SBOM of an image for supply-chain tooling

docksec --image-only -i myapp:latest --sbom

Fully offline scan: local Trivy DB, no network, no AI

docksec --image-only -i myapp:latest --offline

Save today's findings as a baseline, then only gate on new findings later

docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --update-baseline docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --fail-on high

Suppress triaged findings with an auditable ignore file

docksec -i myapp:latest --image-only --ignore-file .docksec-ignore.yml

Force a fresh scan, bypassing the results cache

docksec -i myapp:latest --image-only --no-cache

Install AI-assistant skill files (Claude Code, Cursor, Copilot, and more)

docksec install-skill

Output control

docksec Dockerfile --scan-only --quiet # warnings, errors, summary only docksec Dockerfile --scan-only --verbose # INFO-level diagnostics on stderr docksec Dockerfile --scan-only --verbose --log-file logs/docksec.log docksec Dockerfile --no-color # also honors NO_COLOR

كل إعداد اختياري؛ أي شيء تتركه فارغًا يعود إلى متغير البيئة ثم إلى القيمة الافتراضية المدمجة. يوجد مثال كامل مشروح في examples/.docksec.yml.

الأولوية

الأعلى أولوية أولاً:``` CLI flag > environment variable > .docksec.yml > built-in default

مع --json وحده، لا تتم كتابة أي ملفات تقارير؛ ادمجه مع --format لكتابة الملفات وطباعة JSON في نفس التشغيل. تنتقل جميع الرسائل القابلة للقراءة البشرية إلى stderr في وضع --json، بحيث لا يحتوي stdout أبدًا إلا على حمولة JSON.

مخرجات SARIF لفحص كود GitHub

يكتب --sarif تقرير SARIF 2.1.0 إلى جانب تنسيقات التقارير الأخرى. ارفعه باستخدام إجراء github/codeql-action/upload-sarif القياسي لرؤية النتائج مُعلَّقة مباشرة على طلبات السحب وفي تبويب الأمان:```yaml

• name: Run DockSec uses: OWASP/[email protected] with: dockerfile: 'Dockerfile' sarif: 'true'

• name: Upload SARIF to GitHub Code Scanning uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: ~/.docksec/results

يتم مطابقة النتائج حسب معرّف الثغرة والهدف واسم الحزمة، لذا تبقى خط الأساس صالحة مع ظهور واختفاء نتائج غير ذات صلة. أعد التشغيل باستخدام --update-baseline متى أردت قبول الحالة الحالية كخط أساس جديد.

تجاهل النتائج (الإعفاءات)

--ignore-file FILE يقوم بكتم النتائج الفردية التي قام الفريق بمراجعتها وقبولها. على عكس خط الأساس (لقطة زمنية لحظة معينة)، فإن ملف الإهمال هو قائمة صريحة وقابلة للمراجعة حيث يحمل كل إدخال سببًا وتاريخ انتهاء اختياريًا. إذا كان ملف .docksec-ignore.yml موجودًا في الدليل الحالي، فسيتم التقاطه تلقائيًا.```yaml

.docksec-ignore.yml

ignores:

• id: CVE-2023-45853 # Trivy vulnerability ID or DockSec rule ID reason: "zlib CVE; code path not reachable, vendor fix pending" expires: 2026-12-31 # optional; entry stops applying after this date
• id: compose-missing-healthcheck reason: "healthchecks are handled by the orchestrator"

--sbom يتطلب صورة واحدة (-i)، لذلك يتم تخطيه في عمليات التشغيل عبر compose. مثل --sarif، فهو مستقل عن --format.

تدفق البيانات والخصوصية

تم تصميم DockSec بحيث تعرف دائمًا ما يغادر جهازك:

• الفحص محلي بالكامل. تعمل Trivy وHadolint ودرجة الأمان على جهازك. لا يتم رفع محتويات الصور إلى أي مكان بواسطة DockSec.
• تحليل الذكاء الاصطناعي يرسل الملف المفحوص فقط. عند تشغيل مرحلة الذكاء الاصطناعي، يتم إرسال محتوى Dockerfile أو ملف compose (بالإضافة إلى ملخص قصير لعدد الثغرات للتقييم) إلى مزود LLM الذي قمت بتكوينه. لا يتم نقل أي شيء آخر.
• يتم تنقيح الأسرار قبل مغادرتها. يتم إخفاء القيم التي تشبه الأسرار (كلمات المرور، الرموز، مفاتيح API، كتل المفاتيح الخاصة) في الملف قبل إرسال المحتوى إلى مزود الذكاء الاصطناعي. تبقى أسماء المفاتيح مرئية بحيث لا تزال البيانات المكشوفة يتم الإبلاغ عنها. استخدم --no-redact لإلغاء الاشتراك.
• يدعم الذكاء الاصطناعي المحلي بالكامل. استخدم --provider ollama لإبقاء تحليل الذكاء الاصطناعي على أجهزتك الخاصة، أو --scan-only / --offline لتخطي الذكاء الاصطناعي تمامًا.
• لا يوجد تتبع. لا يجمع DockSec أي بيانات استخدام ولا يتصل بأي خادم.

وضع عدم الاتصال

--offline يقوم بتشغيل فحص بدون وصول إلى الشبكة. يستخدم قاعدة بيانات ثغرات Trivy الموجودة بالفعل على القرص (بدون تحديث قاعدة البيانات) ويتخطى تحليل الذكاء الاصطناعي وفحص Docker Scout المتقدم، وكلاهما يتطلب شبكة. هذه هي أبسط طريقة للفحص في بيئة معزولة أو مقيدة:```bash docksec --image-only -i myapp:latest --offline

هذا يُنشئ أو يُحدّث:

• .claude/commands/docksec.md (أمر Claude Code /docksec)
• .cursor/rules/docksec.mdc (Cursor)
• AGENTS.md (Codex CLI)، GEMINI.md (Gemini CLI)
• .github/copilot-instructions.md (GitHub Copilot)

الملفات هي نص عادي يمكنك مراجعته وتثبيته؛ لا يتم تنفيذ أي شيء. إعادة تشغيل الأمر تُحدّث قسم DockSec في مكانه بدلاً من تكراره.

الميزات

• تحليل ذكي: يشرح الذكاء الاصطناعي معنى الثغرات لإعدادك الخاص.
• دعم نماذج LLM متعددة: OpenAI، Anthropic Claude، Google Gemini، أو نماذج محلية عبر Ollama.
• الخصوصية أولاً: يتم إخفاء القيم السرية قبل وصول أي محتوى إلى مزوّد الذكاء الاصطناعي، والفحص محلي بالكامل، ولا يوجد أي تتبع عن بُعد.
• فحص Docker Compose: اكتشاف أخطاء الإعداد على مستوى التنسيق وفحص جميع الخدمات في ملف compose.
• تكامل عميق: يجمع بين Trivy (الثغرات)، Hadolint (فحص الأكواد)، وDocker Scout.
• تقييم أمني: درجة من 0-100 مع تصنيف لتتبع وضعك الأمني بمرور الوقت.
• تنسيقات غنية: HTML (تفاعلي)، PDF، JSON، CSV، SARIF، وCycloneDX SBOM.
• جاهز للـ CI/CD: أكواد خروج --fail-on، وضع خط الأساس/الترس، إعفاءات قابلة للتدقيق، JSON إلى stdout، وإجراء GitHub Action في السوق.
• وضع عدم الاتصال: فحص معزول تماماً (--offline) باستخدام قاعدة بيانات Trivy المحلية.
• مهارات المساعد الذكي: docksec install-skill يعلّم Claude Code، Cursor، Copilot، وغيرهم كيفية تشغيل DockSec في مستودعك.

مقارنة DockSec

DockSec هو الوحيد بين هذه الأدوات الذي يجمع بين الإصلاح السياقي لـ Dockerfile وتصميم مفتوح المصدر بالكامل، تحت حوكمة OWASP، وقابل للتشغيل محلياً. تقدم Snyk وAikido إصلاحاً بالذكاء الاصطناعي قادراً، لكن فقط كمنصات سحابية تجارية ترسل بياناتك إلى خدمتها. Trivy مفتوح المصدر ومحلي لكنه يتوقف عند الاكتشاف ولا يساعدك في إصلاح أي شيء. يسد DockSec الفجوة للمطورين وللفرق الخاضعة للتنظيم أو المعزولة التي تحتاج إلى كل من إرشادات الإصلاح والتحكم الكامل في بياناتها، دون أي تكلفة.

خارطة الطريق

راجع ROADMAP.md لمعرفة اتجاه DockSec: فحص السجلات بدون داemon Docker محلي، ملف تكوين سياسة على مستوى المستودع، قوالب Jenkins/GitLab/Azure DevOps، صورة حاوية رسمية، فحص Kubernetes وHelm، والمزيد. الملاحظات والأصوات على الأولويات مرحب بها في القضايا وعلى OWASP Slack.

المساهمة

يزدهر DockSec بفضل مساهمات المجتمع. سواء كنت مطوراً أو مصمماً أو متحمساً للأمن، هناك طرق عديدة للمشاركة:

• المساهمات البرمجية: إصلاح الأخطاء أو إضافة ميزات جديدة.
• التوثيق: تحسين الأدلة أو إنشاء دروس تعليمية.
• الإبلاغ عن القضايا: تحديد الأخطاء والإبلاغ عنها.
• الملاحظات: مشاركة تجربتك واقتراحاتك.

للبدء، راجع إرشادات المساهمة، مدونة قواعد السلوك، ودليل الرعاية.

القادة والمجتمع

يقود DockSec فريق مخصص ملتزم بجعل أمن الحاويات في متناول الجميع:

• Advait Patel - قائد المشروع
• Arkadii Yakovets - قائد مشارك للمشروع

تجدنا هنا:

• صفحة مشروع OWASP: owasp.org/DockSec/
• OWASP Slack: #project-docksec
• PyPI: pypi.org/project/docksec/
• القضايا: الإبلاغ عن خطأ
• سجل التغييرات: CHANGELOG.md