Shannon يسحب صورة worker من Docker Hub، ويشغّل البنية التحتية المحلية المطلوبة، ويُثبّت المستودع الهدف للقراءة فقط داخل حاوية worker مؤقتة، ويكتب النتائج إلى مساحة عمل محلية.

لبنى المصدر، والفحوصات المُوثّقة، والإعداد الخاص بكل مزوّد، وملاحظات المنصات، راجع [Documentation](#documentation).

> [!TIP]
> **هل تفضّل استخدام اشتراك بدلاً من أرصدة API؟**
>
> - **OpenAI Codex:** يدعم أحدث إصدار من Shannon اشتراكات ChatGPT Plus وPro. اتبع [دليل إعداد اشتراك OpenAI Codex](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#openai-codex-chatgpt-pluspro-subscription) للبدء.
> - **xAI (Grok):** يدعم أحدث إصدار من Shannon اشتراكات xAI. اتبع [دليل إعداد اشتراك xAI](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#xai-grok-subscription) للبدء.
> - **Claude Code:** لا يدعم أحدث إصدار من Shannon اشتراكات Claude Code. اتبع [دليل إعداد اشتراك Claude Code](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#claude-code-subscription) لاستخدام الإصدار `1.9.0`، وهو الإصدار النهائي المبني على Claude Agent SDK.



## Key Capabilities

- **No exploit, no report**: Reports only vulnerabilities confirmed with a reproducible proof of concept, reducing speculative scanner noise.
- **Advanced code analysis**: Maps architecture, trust boundaries, interfaces, data flows, and critical assets before sending credible attack paths to live pentesting agents.
- **Autonomous execution**: Runs reconnaissance, analysis, exploitation, and reporting from a single command.
- **Live terminal experience**: Simplifies scan setup and shows agent progress and results without exposing orchestration logs.
- **Authenticated testing**: Supports credentials, login flows, TOTP, email authentication, focus areas, and rules of engagement through configuration.
- **OWASP-focused coverage**: Tests for exploitable injection, XSS, SSRF, broken authentication, and broken authorization.
- **Resumable workspaces**: Resumes interrupted scans without repeating completed work.
- **Native CI/CD integrations**: Runs through the official GitHub Action or GitLab CI/CD component, preserves artifacts, publishes findings, and gates releases on proven vulnerabilities.
- **Multi-format reports**: Produces evidence-rich PDF and Markdown reports plus JSON and SARIF 2.1.0. SARIF is enabled by default for exploit-mode scans.
- **Provider agnostic and BYOK**: Supports Anthropic, OpenAI, xAI, AWS Bedrock, compatible APIs and LLM gateways, and local models served through Ollama, vLLM, or LM Studio.
- **Private by design**: Runs in your infrastructure, stores results locally, and sends model requests directly to your chosen endpoint. A local endpoint keeps data inside your environment.



## CI/CD Integrations

Shannon can run continuously against deployed staging and development environments through official integrations for [GitHub Actions](https://github.com/KeygraphHQ/shannon-action) and [GitLab CI/CD](https://gitlab.com/KeygraphHQ/shannon-ci).

Both integrations:

- analyze the checked-out source repository while attacking a running target;
- preserve PDF, Markdown, and SARIF reports as pipeline artifacts;
- preserve scan and agent logs for debugging, including incomplete runs;
- support pull-request, release, and scheduled pentests;
- distinguish an incomplete assessment from a completed scan with no findings; and
- optionally fail the pipeline when Shannon exploits a vulnerability at or above a configured severity threshold.

A code-analysis hypothesis does not fail the pipeline. Severity gates count only findings with `status: exploited`.

### GitHub Actions```yaml
name: Shannon Pentest

on:
  workflow_dispatch:

permissions:
  security-events: write

jobs:
  pentest:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Shannon
        uses: KeygraphHQ/shannon-action@v1
        with:
          url: https://staging.example.com
          api-key: ${{ secrets.SHANNON_AI_API_KEY }}
          fail-on-severity: high
          upload-sarif: true

EXISTING -- "Pentest candidates" --> REC["Finding reconciliation<br/>(merge + deduplicate)"]
SAST -- "SAST candidates" --> REC

REC -- "Reconciled exploitation queue" --> EXP["Exploitation agents"]
APP["Running application"] --> EXP

EXP -- "Exploit demonstrated" --> REPORT["Reporting<br/>PDF · Markdown · SARIF"]
EXP -- "No exploit demonstrated" --> DROP["Discard"]

REPORT --> CICD["CI/CD gate"]

مرحلة بمرحلة:

1. **الاستطلاع وتحليل الثغرات** يستكشف التطبيق قيد التشغيل، ويربط سلوك وقت التشغيل بالمصدر، ويشغّل وكلاء متخصصين عبر Injection وXSS وSSRF والمصادقة والتفويض.
2. **تحليل الكود الأمني الوكيلي** يرسم معمارية التطبيق وحدود الثقة والواجهات المكشوفة والاعتماديات وتدفقات البيانات والأصول عالية المخاطر، ثم يفتح تحقيقات موجّهة ضدها.
3. **مطابقة النتائج** تدمج كلا مساري المرشحين، وتزيل التكرار المتداخل، وتجمّع ما تبقى في قائمة انتظار الاستغلال.
4. **وكلاء الاستغلال** يحاولون تنفيذ هجمات إثبات مفهوم حقيقية ضد التطبيق قيد التشغيل.
5. **التحقق** يستبعد كل مرشح لا يستطيع Shannon إثباته.
6. **إعداد التقارير** ينتج تقارير PDF وMarkdown مع الأدلة المرفقة، بالإضافة إلى JSON منظّم وSARIF للأنظمة اللاحقة.

فقط الثغرات المُتحقق منها حيًّا تصبح نتائج اختبار اختراق Shannon أو تُحتسب ضمن بوابات الخطورة في CI/CD.

تعمل كل عملية فحص في حاوية Docker مؤقتة مع مساحة عمل معزولة وتنسيق لكل استدعاء.

## التوثيق

استخدم هذه الأدلة للتفاصيل التشغيلية:


| الدليل                                                     | استخدمه من أجل                                                                                                                                                                |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [بناء المصدر وأوامر CLI](https://github.com/keygraphhq/shannon/blob/main/docs/development.md)      | الاستنساخ، والبناء، والأوامر الشائعة، ومسارات الإخراج، والتطوير المحلي.                                                                                                  |
| [الإعداد](https://github.com/keygraphhq/shannon/blob/main/docs/configuration.md)                    | الاختبار المُصادَق عليه، وتدفقات تسجيل الدخول، وقواعد الاشتباك، ومرشحات التقارير.                                                                                              |
| [مزوّدو الذكاء الاصطناعي](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md)                      | اختيار النموذج، والمزوّدون المدعومون (Anthropic وOpenAI وxAI وAWS Bedrock وأي مزوّد آخر يدعمه Pi)، وبوابات LLM المخصصة.                             |
| [المنصات والشبكات](https://github.com/keygraphhq/shannon/blob/main/docs/platforms.md)             | Windows/WSL2 وLinux وmacOS وشبكات Docker والتطبيقات المحلية وأسماء المضيفين المخصصة.                                                                                          |
| [مساحات العمل والاستئناف](https://github.com/keygraphhq/shannon/blob/main/docs/workspaces.md)             | تسمية مساحات العمل، واستئناف عمليات الفحص المتقطعة، وتخزين مساحات العمل.                                                                                                     |
| [السلامة والقيود](https://github.com/keygraphhq/shannon/blob/main/docs/safety.md)                  | متطلبات الاستخدام المصرّح به، وإرشادات البيئات غير الإنتاجية، والتأثيرات التغييرية، والتكلفة، وتحذيرات النماذج.                                                                          |
| [التغطية وخارطة الطريق](https://github.com/keygraphhq/shannon/blob/main/docs/coverage-roadmap.md)          | تغطية الثغرات الحالية والعمل المخطط له.                                                                                                                          |
| [منصة Keygraph Enterprise](https://github.com/keygraphhq/shannon/blob/main/docs/keygraph-platform.md) | تحليل SAST الوكيلي الشامل، واختبار الاختراق المستمر، وإدارة النتائج على مدار دورة الحياة الكاملة، والمعالجة، والتحقق الموجّه، والحوكمة المؤسسية، والنشر داخل المنشأة. |




## السلامة والنطاق والقيود

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

أنت مسؤول عن استخدام Shannon بشكل قانوني وأخلاقي. لا توجّه Shannon نحو أنظمة أو مستودعات أو تطبيقات لا تملكها أو لا تملك تفويضًا صريحًا لاختبارها.

قيود مهمة:

- تم ضبط Shannon Open Source لاختبار اختراق سريع ومستنير بالكود في التطوير اليومي وCI/CD. أما تحليل SAST الوكيلي الشامل، وتغطية الماسحات الأوسع، والحوكمة المركزية، وإدارة الثغرات على مدار دورة الحياة الكاملة، فتُقدَّم عبر منصة Keygraph Enterprise.
- لا تزال النتائج تتطلب مراجعة بشرية. قد تحتوي التقارير المولّدة بواسطة LLM على تفاصيل ضعيفة الدعم أو غير صحيحة.
- يُعدّ Anthropic وOpenAI وxAI وAWS Bedrock مزوّدين مدمجين، وأي مزوّد آخر في كتالوج الأداة يعمل أيضًا — وكل منها يمكن الوصول إليه عبر عنوان URL أساسي مخصص يوجّهه إلى وكيل أو بوابة LLM. تتفاوت قدرات النماذج، والنموذج الذي لا يتبع تعليمات Shannon أو قيود استخدام الأدوات بشكل موثوق سينتج نتائج أضعف.
- قد تستغرق العملية الكاملة نحو 1 إلى 1.5 ساعة وقد تترتب عليها تكاليف واجهة LLM API حسب تسعير النموذج وتعقيد التطبيق.
- لا تفحص قواعد أكواد غير موثوقة أو عدائية. يمكن تعريض الأدوات المدعومة بالذكاء الاصطناعي التي تقرأ الكود المصدري لهجمات حقن الأوامر (prompt injection).

اقرأ دليل [السلامة والقيود](https://github.com/keygraphhq/shannon/blob/main/docs/safety.md) الكامل قبل تشغيل Shannon في بيئة جديدة.

## الترخيص

Shannon Open Source مرخّص بموجب [GNU Affero General Public License v3.0](https://github.com/keygraphhq/shannon/blob/main/LICENSE).

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

للترخيص التجاري، تواصل عبر [[email protected]](mailto:[email protected]).

## شكر وتقدير

شكرًا لـ [Pi](https://github.com/earendil-works/pi)،
و[Playwright CLI](https://github.com/microsoft/playwright-cli)،
و[Mantis](https://github.com/google/mantis).

راجع [THIRD_PARTY_NOTICES.md](https://github.com/keygraphhq/shannon/blob/main/THIRD_PARTY_NOTICES.md) لتفاصيل الترخيص والإسناد.

## عن Keygraph

**Keygraph** هي الشركة التي تقف خلف Shannon. وهي تبني أيضًا **منصة Keygraph**، المنتج التجاري لاختبار الاختراق الوكيلي الذي يغلق دورة حياة AppSec الكاملة ويشغّل نسخة معزّزة من Shannon كمحرك اختبار الاختراق الخاص به.

## المجتمع والدعم

تتوفر **ساعات العمل المجتمعية** للحصول على مساعدة عملية بشأن الأخطاء وعمليات النشر وأسئلة الإعداد.

- الولايات المتحدة/أوروبا: الخميس، 10:00 صباحًا بتوقيت المحيط الهادئ
- آسيا: الخميس، 2:00 مساءً بتوقيت الهند
- [احجز موعدًا](https://cal.com/george-flores-keygraph/shannon-community-office-hours)

[انضم إلى Discord](https://discord.gg/cmctpMBXwE) لطرح الأسئلة ومشاركة الملاحظات والتواصل مع مستخدمي Shannon الآخرين.

في الوقت الحالي، لا تقبل Keygraph مساهمات الكود الخارجية. نرحّب بالمشكلات للإبلاغ عن الأخطاء وطلبات الميزات:

- [الإبلاغ عن الأخطاء](https://github.com/KeygraphHQ/shannon/issues)
- [اقتراح ميزات](https://github.com/KeygraphHQ/shannon/discussions)

ابقَ على تواصل:

- [موقع Keygraph](https://keygraph.io)
- [Twitter/X: @KeygraphHQ](https://twitter.com/KeygraphHQ)
- [LinkedIn: Keygraph](https://linkedin.com/company/keygraph)



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



### هل يمكنني استضافة Shannon ذاتيًّا؟

نعم. يعمل Shannon Open Source داخل بنيتك التحتية في حاوية عامل مؤقتة. يثبّت المستودع للقراءة فقط ويكتب النتائج إلى مساحة عمل محلية.

لا تتلقى Keygraph كودك المصدري أبدًا ولا تتوسط في حركة نماذجك. تذهب طلبات نموذجك مباشرة إلى المزوّد أو نقطة النهاية التي تهيّئها، وتحمل معها سياق الكود المصدري والتطبيق. وجّه Shannon إلى نقطة نهاية مستضافة محليًّا وستبقى تلك الحركة داخل بيئتك أيضًا.

### هل يدعم Shannon إحضار مفتاحك الخاص (BYOK)؟

نعم، دائمًا. أنت توفّر بيانات اعتماد LLM التي يستخدمها Shannon لتشغيل اختبار اختراق، في كل عملية نشر، مفتوحة المصدر وتجارية. لا تتوسط Keygraph في حركة نماذجك أبدًا.

### هل يُخرج Shannon صيغة SARIF؟

نعم. يُصدر Shannon صيغة SARIF 2.1.0، وهي الصيغة القياسية من OASIS لنتائج التحليل الساكن، إلى جانب JSON منظّم. يقرأها أي مستهلك لـ SARIF: خدمات فحص الكود، ومنصات إدارة الثغرات، ولوحات المعلومات الأمنية، وخطوط CI/CD. تُكتب افتراضيًّا في عمليات الفحص بوضع الاستغلال؛ اضبط `report.sarif` على `"false"` في ملف الإعداد لديك لإلغاء ذلك.

### ما مزوّدو الذكاء الاصطناعي الذين يدعمهم Shannon؟

يُعدّ Anthropic وOpenAI وxAI وAWS Bedrock مدمجين ويُهيّؤون مباشرةً بمعرّف المزوّد. وإلى جانب هؤلاء، يعمل Shannon على أي مزوّد في كتالوج أداة Pi، ويُسمّى بالطريقة نفسها `<provider>:<model-id>`. يمكن توجيه أي مزوّد إلى وكيل أو بوابة LLM عبر عنوان URL أساسي مخصص، وهو يتجاوز نقطة النهاية فقط ويحافظ على لهجة API الخاصة بذلك المزوّد. يستخدم Shannon إعداد نموذج موحّد واحد طوال اختبار الاختراق.

### هل يمكنني تشغيل Shannon على نموذج محلي أو مستضاف ذاتيًّا؟

يعمل Shannon مع النماذج المحلية المُقدَّمة عبر Ollama أو vLLM أو LM Studio، والتي تكشف نقطة نهاية متوافقة مع OpenAI، وكذلك الموجّهات مثل OpenRouter وبوابات LLM مثل LiteLLM. وجّه Shannon إلى نقطة النهاية بعنوان URL أساسي مخصص. تتفاوت القدرات، والنموذج الذي لا يتبع تعليمات Shannon أو قيود استخدام الأدوات بشكل موثوق سينتج اختبارات اختراق أضعف من نموذج متقدم، لذا اسلك هذا المسار فقط إذا كنت تعرف كيف يتصرف النموذج الذي اخترته. راجع [مزوّدو الذكاء الاصطناعي](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#custom-base-url).

### هل يستغل Shannon الثغرات فعليًّا أم يكتفي بالفحص؟

ينفّذ Shannon استغلالات حقيقية. لا يبلّغ عن نتيجة إلا عندما ينتج إثبات مفهوم فعّال، ويتجاهل الفرضيات التي لا يستطيع إثباتها. إنه مختبر اختراق، وليس ماسحًا سلبيًّا.

**بُني بواسطة [Keygraph](https://keygraph.io)**