Custom AI Agent

الجسر بين Burp Suite والذكاء الاصطناعي الحديث.

ملاحظة حول الاسم: يُنشر هذا الامتداد باسم Custom AI Agent (سابقًا Burp AI Agent). أُعيدت تسميته للامتثال لمتطلبات تسمية متجر BApp Store من PortSwigger ولتجنب الالتباس مع مزود Burp AI المدمج في Burp Suite. يحتفظ مستودع GitHub (github.com/six2dez/burp-ai-agent)، وموقع التوثيق (burp-ai-agent.six2dez.com)، ودليل الإعدادات (~/.burp-ai-agent/) بمعرّف burp-ai-agent للاستمرارية.

Custom AI Agent هو امتداد لـ Burp Suite يدمج الذكاء الاصطناعي في سير عملك الأمني. استخدم النماذج المحلية أو مزودي السحابة، واربط وكلاء الذكاء الاصطناعي الخارجيين عبر MCP، ودع الماسحات السلبية/النشطة تكتشف الثغرات بينما تركز أنت على الاختبار اليدوي.

ما الجديد في الإصدار v0.9.0

• دعم أصلي لـ Anthropic كخلفية (CAP-01) — اتصال مباشر بواجهة Anthropic Messages API عبر نقل HTTP الخاص بـ Burp؛ تظهر جميع الحركة في سجل الوكيل (Proxy history).
• تشفير الأسرار في وضع السكون AES-256-GCM (SEC-01) — تُشفَّر جميع مفاتيح API والرموز المخزنة بمفتاح خاص بكل تثبيت باستخدام javax.crypto. المفتاح الرئيسي موجود في Burp Preferences بجوار النص المشفر، لذا يوفر هذا حماية من الفحص العرضي لملف التفضيلات، وليس من مهاجم محلي — انظر ملاحظات الخصوصية والأمان.
• إخفاء هوية المضيف الحقيقي عبر HKDF (PRIV-01) — يستخدم وضع STRICT الآن استخراج/توسيع HMAC-SHA256 حقيقيًا (وليس SHA-256 مع إضافة ملح) لإخفاء هوية المضيف.
• تنقيح نص الطلب/الاستجابة + أنماط مخصصة (PRIV-02) — تشمل خطوط معالجة التنقيح حقول النص وأنماط regex القابلة لتهيئة المستخدم والتي تم التحقق منها ضد هجمات ReDoS.
• خط تحذير قبل إرسال الأسرار (PRIV-03) — يصدر تحذيرًا قبل مغادرة القيم عالية الاعتلاج (high-entropy) لـ Burp؛ ويتم تسجيل إجراءات القائمة المسموحة في سجل التدقيق.
• خوادم MCP الخارجية (CAP-02) — الاتصال بخوادم MCP خارجية/مخصصة (SSE أو stdio) بحيث يمكن لوكلاء الذكاء الاصطناعي استدعاء أدواتهم إلى جانب أدوات Burp المدمجة.
• قيود ميزانية الرموز لكل جلسة (CAP-04) — يحدّ BudgetGuard إنفاق الماسح السلبي بحالات WARN/CAP/OFF؛ ويتوقف الماسح السلبي تلقائيًا عند الحد الأقصى الصلب.

أبرز المزايا

• 12 خلفية للذكاء الاصطناعي — Burp AI (مدمج)، Anthropic، Ollama، LM Studio، NVIDIA NIM، Perplexity، Generic OpenAI-compatible، Gemini CLI، Claude CLI، Codex CLI، OpenCode CLI، Copilot CLI.
• 59 أداة MCP — اسمح لـ Claude Desktop (أو أي عميل MCP) بقيادة Burp بشكل مستقل (8 أدوات ذكاء اصطناعي أصلية للامتداد في إصدار المتجر، وكل 59 أداة في الإصدار الكامل).
• وصول MCP محدد النطاق — يمكنك اختياريًا حصر كل أداة MCP بمضيفيك داخل النطاق (in-scope)، بحيث لا يمكن للعملاء الخارجيين الوصول إلى أهداف خارج النطاق عبر Burp.
• 62 فئة ثغرات — ماسحات ذكاء اصطناعي سلبية ونشطة تغطي الحقن والمصادقة والتشفير والمزيد. يعمل الماسح السلبي كـ PassiveScanCheck في Burp (Burp Pro).
• التثبيت من Releases — حمّل ملف JAR من Releases. غير متوفر في BApp Store: الطلب مفتوح منذ يناير 2026.
• واجهة متوافقة مع المظهر — ينسّق نظام تصميم داخلي لوحة الإعدادات ويعيد تطبيق المظهر تلقائيًا مع مفتاح Burp الفاتح/الداكن.
• مهارة Burp Scan — استخدم مساعد ترميز الذكاء الاصطناعي المفضل لديك (Claude Code، Gemini CLI، Codex، إلخ) كماسح عبر MCP.
• 3 أوضاع خصوصية — STRICT / BALANCED / OFF. احذف البيانات الحساسة قبل مغادرتها Burp.
• مكتبة أوامر مخصصة — احفظ أوامر حرة الصياغة لكل سياق (طلب HTTP أو مشكلة ماسح)؛ وشغّلها من قائمة النقر بزر الماوس الأيمن أو اكتب أوامر ارتجالية عبر Custom….
• تسجيل التدقيق — ملفات JSONL مع تجزئة نزاهة SHA-256 للامتثال؛ كل إطلاق يُوسم بـ promptSource / contextKind لإعادة الإنتاجية.

البدء السريع

1. التثبيت

حمّل أحدث ملف JAR من Releases، أو ابنِ من المصدر (Java 21):

git clone https://github.com/six2dez/burp-ai-agent.git
cd burp-ai-agent

# Full build (default, GitHub releases) — all 59 MCP tools
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar
# Output: build/libs/Custom-AI-Agent-full-<version>.jar

# Store build (BApp Store submission) — 8 extension-native AI MCP tools only
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar -PstoreBuild=true
# Output: build/libs/Custom-AI-Agent-<version>.jar

2. التحميل إلى Burp

1. افتح Burp Suite (Community أو Professional).
2. انتقل إلى Extensions > Installed > Add.
3. اختر Java كنوع الامتداد وحدد ملف .jar.

يسجّل الامتداد في Burp باسم Custom AI Agent (الاسم في قائمة الامتدادات وتبويب Suite) لتمييزه عن مزود Burp AI المدمج في Burp.

3. ملفات تعريف الوكلاء

يُثبّت الامتداد تلقائيًا ملفات التعريف المرفقة في ~/.burp-ai-agent/AGENTS/ عند أول تشغيل. أضف ملفات *.md إضافية في ذلك الدليل لإضافة ملفات تعريف مخصصة.

4. تهيئة خلفية

افتح تبويب AI Agent وانتقل إلى Settings. اختر خلفية:

بالنسبة إلى NVIDIA NIM، تتوقع الخلفية نفس تدفق chat-completions الذي تستخدمه نقطة النهاية المستضافة من NVIDIA. الإعداد العامل هو:

Backend: NVIDIA NIM
Base URL: https://integrate.api.nvidia.com
Model: moonshotai/kimi-k2.5
API Key: <your nvapi token>

اترك العناوين الإضافية فارغة ما لم تتطلبها بوابتك. يرسل الامتداد الطلبات إلى /v1/chat/completions ويستخدم رمز الحامل المُهيأ تلقائيًا.

5. تشغيل أول تحليل

1. تصفح هدفًا عبر Burp Proxy.
2. انقر بزر الماوس الأيمن على أي طلب في Proxy > HTTP History.
3. اختر Extensions > Custom AI Agent > Analyze this request.
4. تُفتح جلسة محادثة مع تحليل الذكاء الاصطناعي.

6. الاتصال بـ Claude Desktop عبر MCP (اختياري)

فعّل خادم MCP في Settings > MCP Server وأضف هذا إلى إعداد Claude Desktop لديك:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "burp-ai-agent": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "http://127.0.0.1:9876/sse"
      ]
    }
  }
}

يتطلب Node.js 18+. إذا فعّلت External Access، يجب على عميل MCP إرسال Authorization: Bearer <token> في كل طلب.

يمكنك أيضًا تسجيل خوادم MCP خارجية أو مخصصة في Settings > MCP > External Servers (نقل SSE أو stdio). تُخزَّن رموز مصادقة الخادم الخارجي مشفرة في وضع السكون، مع الملاحظة التحذيرية الموضحة في ملاحظات الخصوصية والأمان. انظر docs/external-mcp-servers.md لتفاصيل الإعداد وملاحظات الأمان.

مهارة Burp Scan (الفحص بالذكاء الاصطناعي من الطرفية)

تتيح لك مهارة burp-scan استخدام أي مساعد ترميز بالذكاء الاصطناعي (Claude Code، Gemini CLI، Codex، إلخ) كماسح Burp من الطرفية. بدلًا من الذكاء الاصطناعي المدمج في الإضافة، يصبح ذكاء طرفيتك هو محرك الاستدلال بينما يوفر Burp الأدوات عبر MCP.

ماذا تحتوي

• مرجع أدوات MCP (حتى 59 أداة في الإصدار الكامل) منظمًا حسب إجراء الفحص
• بروتوكول التحليل السلبي (تحليل الحركة دون إرسال طلبات)
• مكتبة حمولات الاختبار النشط (أكثر من 200 حمولة لـ 62 فئة ثغرات مع أنماط اكتشاف)
• سير عمل فحص شامل (النطاق -> السلبي -> النشط -> OOB -> التقرير)
• بروتوكول إنشاء المشكلات مع تعيين الخطورة/الثقة

التثبيت لـ Claude Code

انسخ المهارة إلى دليل مهارات Claude Code لديك:

# Global (available in all projects)
cp -r skills/burp-scan ~/.claude/skills/burp-scan

# Or project-specific
cp -r skills/burp-scan .claude/skills/burp-scan

ثم استخدم /burp-scan في Claude Code أو اتركه يُفعَّل تلقائيًا عندما تذكر فحص Burp.

التثبيت لمساعدي الذكاء الاصطناعي الآخرين

المهارة ملف Markdown مستقل في skills/burp-scan/SKILL.md. يمكنك استخدامه مع أي مساعد ذكاء اصطناعي يدعم أوامر النظام prompt أو ملفات السياق:

• Gemini CLI / Codex / OpenCode: أضفه كملف سياق أو الصقه في أمر النظام لديك
• عملاء MCP مخصصون: ضمّن محتوى المهارة كسياق نظام إلى جانب اتصال MCP
• أي نموذج لغوي LLM: الملف مكتفٍ ذاتيًا — غذّه كسياق مع تعريفات أدوات MCP الخاصة بك

مثال استخدام

You: Connect to Burp MCP at localhost:9876 and scan the proxy history for IDOR vulnerabilities

AI: [Uses proxy_http_history to pull traffic]
    [Identifies endpoints with numeric IDs]
    [Sends http1_request with ID+1, ID-1 payloads]
    [Compares responses for different user data]
    [Creates issue_create for confirmed IDOR]

المهارة والماسح المدمج في الإضافة متكاملان: تعمل الإضافة على الفحص الآلي في الخلفية، بينما تتيح المهارة فحصًا تفاعليًا موجَّهًا من المحلل من طرفيتك.

التوثيق

التوثيق الكامل متاح في burp-ai-agent.six2dez.com.

• التثبيت
• البدء السريع
• جولة في الواجهة
• ملفات تعريف الوكلاء
• الماسح السلبي
• الماسح النشط
• نظرة عامة على MCP
• أوضاع الخصوصية
• مرجع الإعدادات
• استكشاف الأخطاء وإصلاحها
• مهارة Burp Scan

أدلة التشغيل

• تحصين MCP
• دليل أمان الواجهة
• استكشاف أخطاء الخلفية
• إعداد خلفية Anthropic
• خوادم MCP الخارجية

ملاحظات الخصوصية والأمان

• الأسرار في وضع السكون — ما يفعله التشفير وما لا يفعله. تُشفَّر جميع مفاتيح API والرموز المخزنة (Anthropic، رمز حامل MCP، كلمة مرور مخزن مفاتيح TLS، إلخ) باستخدام AES-256-GCM ومفتاح رئيسي عشوائي خاص بكل تثبيت (SecretCipher). يُخزَّن ذلك المفتاح الرئيسي نفسه في Burp Preferences بترميز Base64، بجوار النص المشفر الذي يحميه (التفضيل secret.master.key.v1). أي شخص يمكنه قراءة Burp Preferences يمكنه بالتالي أيضًا قراءة المفتاح وفك تشفير الأسرار. وهو لا يحمي من مهاجم محلي أو عملية خبيثة تعمل باسم مستخدمك؛ تعامل معه كإخفاء ضد الفحص العرضي لملف تفضيلات أو مشروع مُصدَّر. إذا كان يجب أن ينجو أي اعتماد من نموذج التهديد هذا، فاحتفظ به في مخزن أسرار مخصص والصقه في كل جلسة.
• استدعاءات الأدوات الصادرة من النموذج تتطلب موافقتك. استدعاء الأداة الذي يستخرجه الامتداد من مخرجات النموذج لا يُنفَّذ ضد Burp حتى تقرر أنت. تحمل كل أداة مستوى أمانًا إلزاميًا: التشغيل التلقائي (قراءة فقط مع مخرجات محدودة)، أو التأكيد بخيار Approve for session، أو التأكيد في كل استدعاء. اسم أداة لا يتعرف عليه الكتالوج يُعامل كتأكيد في كل مرة، وليس تلقائيًا أبدًا، والأدوات الخارجية ذات مساحة الاسم ext: تؤكد دائمًا في كل استدعاء. يظهر القرار كبطاقة داخل نص المحادثة وليس كنافذة حوار مشروطة، ويُسجَّل كل قرار — حدث تدقيق بالإضافة إلى سطر في تبويب Output في Burp، نظرًا لأن تسجيل التدقيق معطَّل افتراضيًا. الرفض يعيد للنموذج نتيجة محايدة "غير مصرح به، لا تُعد المحاولة" بدلًا من خطأ. هذا المستوى مستقل عن مفتاح Unsafe Mode: يحدد Unsafe Mode ما إذا كانت الأداة قد تُنفَّذ إطلاقًا، بينما يحدد المستوى ما إذا كان النموذج قد يشغّلها دون سؤال. الأساس المنطقي للتصميم: DECISIONS.md ADR-15. دليل المشغل: docs/ui-safety-guide.md.
• وضع الخصوصية STRICT يخفي هوية المضيفين باستخدام HKDF حقيقي (استخراج/توسيع HMAC-SHA256). وضع BALANCED ينقّح ملفات تعريف الارتباط والرموز وعناوين المصادقة. وضع OFF يرسل الحركة كما هي.
• تُغلَّف مخرجات خادم MCP الخارجي بعلامة حد الثقة قبل دخولها إلى أمر الذكاء الاصطناعي، ما يمنع حقن الأوامر prompt من استجابات الخادم غير الموثوقة.

الإعدادات ذات نسق إصدارات داخليًا (settings.schema.version) وتُرحَّل إضافيًا عند التحميل لضمان ترقيات آمنة.

المتطلبات

• Burp Suite Community أو Professional (2023.12+)
• Java 21 (مضمّن مع Burp الحديث للتشغيل؛ مطلوب بشكل منفصل للبناء من المصدر)
• خلفية ذكاء اصطناعي واحدة مهيأة على الأقل (انظر الجدول أعلاه)

الرخصة

هذا المشروع مرخّص بموجب MIT License.

إخلاء المسؤولية

استخدام Custom AI Agent لمهاجمة أهداف دون موافقة مسبقة غير قانوني. تقع على عاتق المستخدم مسؤولية الالتزام بجميع القوانين المعمول بها. لا يتحمل المطوّرون أي مسؤولية عن إساءة الاستخدام أو الأضرار الناجمة عن هذه الأداة. استخدمها بمسؤولية.

المساهمة

نرحب بالمشكلات (Issues) وطلبات السحب (pull requests). انظر CONTRIBUTING.md لإعداد التطوير والإرشادات، أو وثائق المطوّرين لتفاصيل البنية.