### 2. تثبيت DockSec```bash
# Full install with AI analysis support (recommended)
pip install "docksec[ai]"

# Or the slim, scan-only core (no LLM dependencies, no API key needed)
pip install docksec

كل فحص ينتهي بملخص للنتائج: جدول درجات الخطورة، ودرجة أمان من 0 إلى 100 مع
تقييم، وكتلة إجراء "Quick take"، والتقارير المُنشأة (المحفوظة افتراضيًا في
`~/.docksec/results/`)، وأمر مقترح للتالي.

### 4. تفعيل تحليل الذكاء الاصطناعي

يشرح تحليل الذكاء الاصطناعي النتائج ويقترح إصلاحات. اختر مزوّدًا، وعيّن مفتاح API الخاص به، ثم شغّل:```bash
# OpenAI (default provider)
export OPENAI_API_KEY="sk-..."
docksec Dockerfile

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."
docksec Dockerfile --ai-only --provider anthropic --model claude-sonnet-5

# Google Gemini
export GOOGLE_API_KEY="..."
docksec Dockerfile --ai-only --provider google

# Ollama (fully local, no API key, data never leaves your machine)
docksec Dockerfile --ai-only --provider ollama --model llama3.1

قبل إرسال أي محتوى إلى مزوّد الذكاء الاصطناعي، تُقنَّع القيم التي تبدو كأسرار (كلمات المرور، الرموز،
مفاتيح API، كتل المفاتيح الخاصة) تلقائيًا. راجع
[تدفق البيانات والخصوصية](#data-flow-and-privacy).

### 5. أو شغّل صورة الحاوية (لا شيء لتثبيته)

الصورة المنشورة تتضمن إصدارات مثبّتة من Trivy وHadolint، لذا لا يوجد
شيء لتثبيته ولا شيء لتهيئته:```bash
docker run --rm -v "$PWD:/github/workspace" \
  -e INPUT_DOCKERFILE=Dockerfile \
  -e INPUT_SCAN_ONLY=true \
  ghcr.io/owasp/docksec:latest

تقرأ الصورة نفس متغيرات `INPUT_*` التي تقرأها GitHub Action، لذا يعمل أي مُدخل Action هنا: `INPUT_IMAGE`، `INPUT_COMPOSE`، `INPUT_SEVERITY`، `INPUT_FAIL_ON`، `INPUT_FORMAT`، `INPUT_SARIF`، `INPUT_OUTPUT_DIR`. اكتب التقارير في مكان ما على نقطة التحميل للاحتفاظ بها بعد خروج الحاوية:```bash
docker run --rm -v "$PWD:/github/workspace" \
  -e INPUT_COMPOSE=docker-compose.yml \
  -e INPUT_SCAN_ONLY=true \
  -e INPUT_FORMAT=json,html \
  -e INPUT_OUTPUT_DIR=/github/workspace/docksec-reports \
  ghcr.io/owasp/docksec:latest

## الأوامر الشائعة```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

# Write a Markdown report for posting directly into a pull request comment
docksec Dockerfile --scan-only --format markdown

# 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 --scan-only --compact-output         # shorter per-finding output
docksec Dockerfile --no-color                           # also honors NO_COLOR

# Apply the mechanical Dockerfile fixes (keeps a .bak, re-scans, shows the delta)
docksec Dockerfile --scan-only --fix --dry-run          # print the diff, change nothing
docksec Dockerfile --scan-only --fix

# Rank findings by severity alone, with no EPSS lookup and no network call
docksec Dockerfile --scan-only --no-epss

# Treat a scan that could not complete as a failure, not a pass
docksec Dockerfile --scan-only --fail-on high --incomplete-policy fail

كل إعداد اختياري؛ أي شيء تتركه يعود إلى متغير البيئة ثم إلى الإعداد الافتراضي المدمج. يوجد مثال كامل مشروح في
[`examples/.docksec.yml`](https://github.com/owasp/docksec/blob/main/examples/.docksec.yml).

### الأولوية

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

### الأولوية: ما يجب إصلاحه أولاً

يتم تقييم كل اكتشاف CVE مقابل [EPSS](https://www.first.org/epss/)، الذي
يقدّر احتمال استغلاله خلال الثلاثين يومًا القادمة. ودمج ذلك
مع الخطورة يعطي أربع فئات:

| الفئة | المعنى |
|---|---|
| **أصلح الآن** | خطورة حرجة أو عالية، وضمن أعلى 10% من CVEs من حيث احتمالية الاستغلال |
| **أصلح قريبًا** | خطورة حرجة أو عالية، لكن الاستغلال أقل شيوعًا |
| **راقب** | خطورة أقل، لكنه يُستغل فعليًا |
| **أولوية منخفضة** | خطورة أقل، والاستغلال غير شائع |

هذا هو نداء الشبكة الوحيد الذي يجريه DockSec خارج مرحلة الذكاء الاصطناعي، وهو
ضيق النطاق عمدًا: **يتم إرسال معرّفات CVE فقط** - لا أسماء صور، ولا محتويات ملفات،
ولا مسارات. يتم تخزين النتائج مؤقتًا لمدة 24 ساعة. ويعطّل `--offline` و`--no-epss` ذلك،
وأي فشل يتراجع إلى الترتيب حسب الخطورة فقط بدلاً من إفشال الفحص.

### سلاسل الاستغلال

يعرض العرض لكل خدمة على حدة الاكتشافات واحدًا تلو الآخر. كما يبلّغ DockSec عن المواضع
التي تتحد فيها اكتشافات منفصلة لتشكّل مسار هجوم واحد:```text
Exploit chains
  [HIGH] 'web' is internet-facing and can reach 'db' with a committed credential
      services: web, db
      combines: compose-plaintext-secret-env, compose-no-network-segmentation
      'web' accepts connections from outside the host and shares the default
      network with 'db'. 'db' is not exposed directly, but its credential is in
      the compose file, so compromising 'web' yields authenticated access to it.
      Neither service looks critical on its own.
      break it: Put 'db' on its own network that 'web' does not join, or move
      POSTGRES_PASSWORD to a Docker secret.

### مخرجات قابلة للقراءة آليًا

يطبع `--json` كائن JSON واحدًا إلى stdout (معلومات الفحص، والثغرات، وعدد مرات الخطورة، وأي نتائج ذكاء اصطناعي) بدلًا من الملخص القابل للقراءة البشرية، بحيث يمكن تمريره مباشرة إلى أدوات أخرى:```bash
docksec -i myapp:latest --image-only --json | jq '.severity_counts'

> `if: always()` مهم: بدونه، يتم تخطي خطوة الرفع كلما تسبب
> `--fail-on` في خروج DockSec بقيمة غير صفرية، مما يفقد النتائج في اللحظة التي
> تكون فيها أكثر أهمية.

### وضع خط الأساس / السقاطة

يتيح لك `--baseline FILE` تبنّي `--fail-on` في مشروع موجود دون جدار من
النتائج الموجودة مسبقًا يعيق كل عملية بناء. شغّل مرة واحدة مع `--update-baseline` لأخذ لقطة
لنتائج اليوم، ثم التزم بملف خط الأساس؛ من ذلك الحين فصاعدًا، يتحكم `--fail-on` فقط في
النتائج غير الموجودة بالفعل في خط الأساس:```bash
# Snapshot current findings (does not gate)
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --update-baseline

# Later runs only fail on NEW findings above the threshold
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --fail-on high

تُزال النتائج المُثبَّطة (suppressed) قبل التقييم والتقارير ومخرجات `--json` وبوابة `--fail-on`. تتوقف الإدخالات المنتهية الصلاحية عن التطبيق تلقائيًا (مع تحذير)، وتُعلَّم الإدخالات التي تفتقر إلى سبب لتبقى حالات الإعفاء قابلة للتدقيق. أضف الملف إلى نظام التحكم في الإصدارات حتى تخضع حالات التثبيط للمراجعة مثل أي تغيير آخر.

---

## التقارير

### صيغ التقارير

بشكل افتراضي، يكتب كل فحص أربعة ملفات تقارير؛ استخدم `--format` لاختيار مجموعة فرعية:

- **html**: تقرير ويب تفاعلي ومرتب بصريًا: بطاقات الخطورة، وتقييم الدرجة، وجدول كامل للثغرات مع الإصدارات المُصلَّحة، ونتائج الذكاء الاصطناعي الكاملة.
- **pdf**: مستند محمول جاهز للعرض.
- **json**: بيانات فحص كاملة قابلة للقراءة آليًا (بنفس شكل مخرجات `--json` على stdout).
- **csv**: جدول جاهز للجداول الحسابية للثغرات الفردية.
- **markdown**: تقرير خفيف وقابل للقراءة (ملخص الخطورة + جدول الثغرات مع الإصدارات المُصلَّحة) يُعرض أصليًا في تعليقات طلبات السحب وملخصات مهام CI. اختياري: أضف `markdown` إلى `--format`؛ فهو لا يُكتب افتراضيًا.

> ملاحظة حول سلوك CSV: عند عدم وجود ثغرات، لا يزال DockSec يكتب ملف CSV
> يحتوي على الترويسة فقط (أسماء الأعمدة، بدون صفوف) حتى لا تتعطل الأتمتة اللاحقة أبدًا
> بسبب ملف مفقود أو فارغ. هذا مقصود.

### CycloneDX SBOM

يكتب `--sbom` قائمة مكونات برمجية بصيغة CycloneDX (`<image>.cdx.json`) للصورة
المفحوصة، مع سرد كل مكوّن حزمة بالإضافة إلى الثغرات المعروفة. تُنتَج قائمة المكونات
بواسطة مُصدِّر Trivy الأصلي (لذا فهي متوافقة مع المواصفات) ويطبع DockSec نفسه
في بيانات تعريف الأداة. أدخلها في Dependency-Track، أو رسم بياني للتبعيات من GitHub، أو أي
مستهلك آخر لـ SBOM:```bash
docksec --image-only -i myapp:latest --sbom

تأكد من تنزيل قاعدة بيانات Trivy مرة واحدة على الأقل (أي فحص عبر الإنترنت سابق
يقوم بذلك) قبل الاعتماد على `--offline`.

### ذاكرة التخزين المؤقت لنتائج الفحص

يتم تخزين نتائج فحص الصور مؤقتًا (الافتراضي: 24 ساعة، يمكن تجاوزه باستخدام
`DOCKSEC_CACHE_TTL_HOURS`) وتُربط ببصمة محتوى الصورة (content digest)، لذا فإن وسمًا
أُعيد بناؤه مثل `:latest` المُعاد استخدامه يحصل دائمًا على فحص جديد. استخدم `--no-cache` (أو
`DOCKSEC_USE_CACHE=false`) لتجاوز ذاكرة التخزين المؤقت لتشغيل واحد.

### سحب الصور غير الموجودة محليًا

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

اضبط `DOCKSEC_PULL_MISSING_IMAGES=false` لإيقاف هذا والفشل بدلًا من ذلك، وهو أمر
يستحق القيام به على اتصال محدود البيانات أو على runner مشترك. لا يقوم `--offline` أبدًا
بالسحب، بغض النظر عن هذا الإعداد.

---

## مهارات مساعد الذكاء الاصطناعي (`install-skill`)

يكتب `docksec install-skill` تعليمات استخدام DockSec في ملفات السياق
المعروفة لمساعدي البرمجة بالذكاء الاصطناعي الشائعين، حتى يعرف المساعد العامل في مستودعك كيفية
استدعاء DockSec:```bash
docksec install-skill

## ما الجديد

- إضافة دعم لـ `--proxy` في `nuclei`
- إصلاح مشكلة في `httpx` عند استخدام `-json` مع `-silent`
- تحسين أداء `subfinder` عند استخدام مصادر متعددة
- تحديث قوالب `nuclei` إلى الإصدار الأخير

## التثبيت

```bash
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

nuclei -u https://example.com -t cves/

إنه متحفظ عن قصد. لن يختار إصدار صورة أساسية، أو ينقل سرًا، أو يحوّل `ADD` الذي يجلب عنوان URL أو يفك ضغط أرشيف، أو يعدّل ملف compose - يتم الإبلاغ عن تلك بدلاً من ذلك ضمن "Needs review". كما يرفض تعديل ملف يحتوي على تغييرات غير مُثبَّتة إلا إذا تم تمرير `--force`، بحيث يكون git دائمًا في وضع يسمح بالتراجع عن التغيير.

## Documentation

| Guide | What it covers |
| --- | --- |
| [Evaluation guide](https://github.com/owasp/docksec/blob/main/docs/evaluation-guide.md) | 15-minute assessment, including what DockSec does *not* do |
| [Exploit chains](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md) | Cross-service attack paths, and their limits |
| [Compose rule reference](https://github.com/owasp/docksec/blob/main/docs/rules/README.md) | All 17 rules: what each catches, and when keeping it is reasonable |
| [CI integration](https://github.com/owasp/docksec/blob/main/docs/ci/README.md) | Jenkins, GitLab, Azure Pipelines, pre-commit |
| [Examples](https://github.com/owasp/docksec/blob/main/examples/README.md) | Ten Dockerfiles and compose stacks with their expected findings |
| [Case studies](https://github.com/owasp/docksec/blob/main/docs/case-studies/README.md) | Real scans of official images, with the numbers |

## Roadmap

راجع [ROADMAP.md](https://github.com/owasp/docksec/blob/main/ROADMAP.md) لمعرفة إلى أين يتجه DockSec: فحص السجلات (registry) دون خادم Docker محلي، وملف تكوين سياسات على مستوى المستودع، وقوالب Jenkins/GitLab/Azure DevOps، وصورة حاوية رسمية، وفحص Kubernetes وHelm، والمزيد. نرحب بالملاحظات والتصويت على الأولويات في
[issues](https://github.com/OWASP/DockSec/issues) وعلى
[OWASP Slack](https://owasp.slack.com/archives/C0APXGCUW7M).

---

## Contributing

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

- **Code Contributions**: إصلاح الأخطاء أو إضافة ميزات جديدة.
- **Documentation**: تحسين الأدلة أو إنشاء دروس تعليمية.
- **Issue Reporting**: تحديد الأخطاء والإبلاغ عنها.
- **Feedback**: شارك تجربتك واقتراحاتك.

للبدء، اطّلع على [Contributing Guidelines](https://github.com/owasp/docksec/blob/main/CONTRIBUTING.md) و[Code of Conduct](https://github.com/owasp/docksec/blob/main/CODE_OF_CONDUCT.md) و[Sponsorship Guide](https://github.com/owasp/docksec/blob/main/SPONSORSHIP.md).

---

## Leaders and Community

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

- [Advait Patel](https://github.com/advaitpatel) - Project Lead
- [Arkadii Yakovets](https://github.com/arkid15r) - Project Co-lead

تجدنا هنا:

- **OWASP Project Page**: [owasp.org/DockSec/](https://owasp.org/DockSec/)
- **OWASP Slack**: [#project-docksec](https://owasp.slack.com/archives/C0APXGCUW7M)
- **PyPI**: [pypi.org/project/docksec/](https://pypi.org/project/docksec/)
- **Issues**: [Report a bug](https://github.com/OWASP/DockSec/issues)
- **Changelog**: [CHANGELOG.md](https://github.com/owasp/docksec/blob/main/CHANGELOG.md)

---

<div align="center">
  <strong>If DockSec helps you, star the repo to help others discover it.</strong><br>
  Built by <a href="https://github.com/advaitpatel">Advait Patel</a> and the OWASP community.
</div>