دوز مباشرة للمحتوى الرئيسي
دروس فالذكاء الاصطناعي

دليل النشر المحلي لـ Autonomous Pentest Agent: من التثبيت والإعداد حتى الاستكشاف الذاتي وإعادة الاختبار

كيشرح هاد المقال البنية الأساسية ديال Autonomous Pentest Agent، وطرق التثبيت، وإعدادات LLM وPostgreSQL، ومراقبة المهام، ومزامنة الأصول، وإعادة اختبار الثغرات، وطرق الترقية، مع توضيح ملاحظات مهمة على الـ reverse proxy والتطوير المحلي.

حوالي 29 دقايق ديال القراية
دليل النشر المحلي لـ Autonomous Pentest Agent: التثبيت والإعداد والاستكشاف وإعادة الاختبار

فالأول، تعرّف على المشروع وحدود الاستعمال

Autonomous Pentest Agent هو نظام مستقل لاختبارات الاختراق، كيسوقوه عدّة Agents مبنيين على LLM، وكيتستعمل فيه Go فالخلفية، وNext.js فالواجهة الأمامية، وPostgreSQL. المشروع كيقدر يسيّر المهام، الأصول، مسارات الاستكشاف، النتائج المكتاشفة، سجلات الترافيك، المصادقة على الأدوات، والمحادثات اللي فيها تدخل بشري.

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

المشروع كيوفّر نسخة تجريبية على الإنترنت باش تتعرّف على الواجهة التفاعلية، ولكن النشر والتحقق الفعلي خاصهم يبقاو محصورين بصرامة فبيئة محلية معزولة.

الوظائف الأساسية والواجهة

الواجهة الأمامية ديال النظام فيها لوحة القيادة، لائحة المهام، جلسات التنفيذ، مسارات الاستكشاف، النتائج المكتاشفة، الأصول، خريطة تغطية الأصول، تسجيل الترافيك، تدبير Agents، إعدادات LLM، الموافقة على الاعتراضات، وسجلات الخلفية.

لوحة القيادة

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

مراحل التنفيذ

مسار الاستكشاف كيسمح بمراقبة العلاقة بين الأهداف، النوايا، الحقائق، والنتائج المكتاشفة؛ وصفحة النتائج المكتاشفة كتستعمل لمراجعة الثغرات والأدلة ديالها، بينما صفحة الأصول كتستعمل لتصفح الأصول المستهدفة اللي جمعها النظام ودمجها.

لوحة القيادة

مسار الاستكشافالنتائج المكتاشفة

نظرة عامة على بنية النظام

النظام كيتكوّن من خلفية موحّدة بGo، مدموجة فيها واجهة Next.js ثابتة، ومن PostgreSQL، ومحرك Agents، وعدّة أنظمة فرعية مساندة. الخلفية كتقدّم الخدمات للواجهة عبر REST API وJWT للمصادقة وSSE، ومحرك المهام كيتكلف بجدولة planner وعدّة workers.

المشروع كيعتمد على بنية بجوج ديال الرسومات:

  • رسم الأصول: قاعدة موحّدة للحقيقة ديال الأصول ومشتركة بين المهام، وكتضم عقد بحال النطاق الجذري، النطاقات الفرعية، عناوين IP، الخدمات، التطبيقات، ونقاط النهاية.
  • رسم الاستكشاف: كيسجّل حسب كل مهمة الأهداف، النوايا، الحقائق، التلميحات، والنتائج المكتاشفة، وكيصف مسار الاستكشاف عبر علاقات الأصل والفروع.
  • علاقات الارتكاز: كترابط عقد الاستكشاف بأصول محددة، باش يمكن تشوف نسبة تغطية اختبار الأصول ونطاق الاستكشاف.

Planner كيقرا وضعية الاستكشاف وكيبعث النوايا، وWorker كياخذ النية، كيستعمل الأدوات فالتنفيذ، وكيكتب الحقائق والأصول والنتائج المكتاشفة. منين كيتبدل الرسم، كيتعاود تنبيه Planner، وكيشكّل هاد الشي حلقة مغلقة مدفوعة بالأحداث. Workers متعدّدين يقدرو حتى هما يبحثو فعمليات التنفيذ ديال Workers آخرين، بينما todolist مشتركة كتعاون التخطيط على مراحل باش يدوز الخطوات المتتابعة حسب التبعيات.

التحضير قبل التثبيت

تشغيل المشروع كيتطلب على الأقل PostgreSQL. وباش تنفّذ الاستكشاف، خاصك تهيّأ LLM، وتقدر تستعمل ANTHROPIC_API_KEY أو OPENAI_API_KEY، أو تعمّرهم من بعد فصفحة «إعدادات LLM» فالواجهة.

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

المهمة

الطريقة الأولى: استعمال سكريبت التثبيت بنقرة وحدة

هاد الطريقة هي اللي كيوصي بها README. السكريبت كيفحص Docker أو كيثبتو، وكيخليك تختار بين النشر الكامل بDocker أو البناء والتشغيل محلياً.

git clone https://github.com/kutukam/autonomous-pentest-agent.git
cd autonomous-pentest-agent
./install.sh

إلى اخترتي النشر الكامل بDocker، السكريبت غادي يطلب منك كلمة سر PostgreSQL، وتقدر حتى تضغط مباشرة على Enter باش يتولّد رمز عشوائي، ومن بعد كيتكتب ف.env وكيتم تنفيذ docker compose up -d. وإلى اخترتي التشغيل المحلي، تقدر تربط بقاعدة بيانات موجودة من قبل، أو تشغّل قاعدة البيانات بDocker؛ السكريبت غادي ينشئ config.json، ويبني ثنائي Go واحد فيه الواجهة الأمامية مدموجة، ومن بعد يشغّل الخدمة.

من بعد ما يكمل التثبيت، دخل لhttp://localhost:8787. فالدخول الأول، حلّ /setup وعيّن كلمة سر المدير.

الطريقة الثانية: استعمال Docker Compose

إلى بغيتي تتحكم فالبيئة يدوياً، تقدر تستعمل Compose مباشرة:

git clone https://github.com/kutukam/autonomous-pentest-agent.git
cd autonomous-pentest-agent
cp .env.example .env
docker compose up -d

مراحل التنفيذ

حرّر .env وعمّر POSTGRES_PASSWORD، وتهيّأ ANTHROPIC_API_KEY حسب الحاجة. من بعد التشغيل، دخل لhttp://localhost:8787.

صورة Docker فيها الأدوات الشائعة، و./skills و./data كيستعملو الربط المباشر باش تتحفظ المعطيات. تقدر تختار MCP البعيد من إعدادات النظام عبر Streamable HTTP أو SSE القديم؛ وفحالة استعمال SSE القديم، غالباً كيكون العنوان /sse، وخصك تضبط رأس الطلب Authorization=Bearer <token> حسب متطلبات الخدمة.

الطريقة الثالثة: استعمال ثنائي مبني مسبقاً

تقدر حتى تنزّل الحزمة المضغوطة المناسبة للمنصة من Releases. من بعد فك الضغط، غالباً غادي تلقى apagent، وstart.sh أو start.bat فWindows، وskills/ وconfig.example.json.

cp config.example.json config.json
./start.sh

استعمل start.sh أو start.bat فالتشغيل، وما تشغّلش ./apagent مباشرة. سكريبت التشغيل كيتكلف، من بعد خروج البرنامج، يقرر واش يعاود يشغلو حسب رمز الخروج، وحتى وظيفة التحديث بنقرة وحدة فالصفحة كتحتاج هاد الآلية. للتشغيل فالخلفية، تقدر تستعمل:

nohup ./start.sh >apagent.log 2>&1 &

الطريقة الرابعة: البناء من الكود المصدري

مسار الاستكشاف

فحالة البناء من الكود المصدري، خاصك فالأول تبني الملفات الثابتة ديال الواجهة الأمامية، ومن بعد تنسخها لمجلد الواجهة المدموجة فالخلفية، وأخيراً تبني برنامج Go باستعمال الوسم embedui.

cd web && npm ci && npm run build:static && cd ..
cp -r web/out server/webui/dist
CGO_ENABLED=0 go build -tags embedui -o apagent ./cmd/apagent
./start.sh

إلى بغيتي تبني حزم إصدار متعددة المنصات، شغّل:

./build.sh --release

افتراضياً غادي يتولدو عدّة حزم مستهدفة لLinux وmacOS وWindows. وتقدر حتى تخصص الأهداف عبر APAGENT_TARGETS. UPX ما مفعّلاش افتراضياً، حيت الثنائي ذاتي فك الضغط من بعد التصغير يقدر ما يكونش متوافق مع بعض نوى Linux، بيئات المحاكاة الافتراضية، أو سياسات الأمان.

تهيئة قاعدة البيانات وLLM

فحالة التشغيل من البناء المحلي أو من الثنائي، تقدر تهيّأ PostgreSQL فconfig.json:

{
  "database": {
    "host": "127.0.0.1",
    "port": 5432,
    "user": "apagent",
    "password": "yourpass",
    "dbname": "apagent",
    "sslmode": "disable"
  }
}

النتائج المكتاشفة

وتقدر حتى تستعمل APAGENT_PG_DSN باش تغطي إعدادات الاتصال بقاعدة البيانات. ويمكن تهيئة LLM عبر متغيرات البيئة:

export ANTHROPIC_API_KEY=sk-...
# أو
export OPENAI_API_KEY=...

المعاملات الاختيارية كتضم APAGENT_LLM_PROVIDER وAPAGENT_LLM_MODEL وAPAGENT_LLM_BASE_URL وAPAGENT_LLM_PROXY. إلى ما بغيتيش تستعمل متغيرات البيئة، عمّر المعطيات فصفحة «إعدادات LLM» فالواجهة. عدد Workers ديال كل مهمة تقدر تعدلو من «إعدادات النظام»، والقيمة الافتراضية هي 3.

المسار الأساسي للاستعمال

  1. كمّل التهيئة: دخل للخدمة المحلية، وحلّ /setup باش تعيّن كلمة سر المدير، وتأكد من الاتصال بقاعدة البيانات.
  2. هيّأ LLM: فمتغيرات بيئة النظام أو صفحة «إعدادات LLM»، عيّن النموذج المتاح والمعاملات الضرورية.
  3. وجد الهدف المحلي: زِد غير الأصول اللي كتتحكم فيها داخل بيئة تجارب معزولة، وتأكد أنها ما غاديش توصل لأنظمة على الإنترنت أو خدمات الإنتاج.
  4. أنشئ المهمة وراقبها: استعمل صفحة المهام لتدبير المهام، وشوف حالة التشغيل من لوحة القيادة وتدفّق الأنشطة.
  5. راجع نتائج الاستكشاف: استعمل مسار الاستكشاف باش تفهم العلاقة بين النوايا والحقائق والنتائج المكتاشفة، واستعمل رسم الأصول باش تشوف الأصول المدموجة.
  6. فحص أدلة التنفيذ: راجع سجلات العملية فالجلسات، واستدعاءات الأدوات، وصفحات الترافيك؛ وإلى كانت شي عملية كتحتاج تأكيد بشري، عالجها من صفحة الموافقة على الاعتراضات.
خريطة تغطية الأصول

خريطة تغطية الأصول كتعرض الأصول الموجودة فالنطاق والعقد اللي تدار ليها الاختبار باستعمال تخطيط موجّه بالقوى، وكتدعم طيّ العقد وتوسيعها. كتصلح باش تحدد بسرعة شنو هي الأصول اللي تم استكشافها داخل نطاق التجربة المحلية.

مزامنة الأصول من ScopeSentry

المشروع كيدعم مزامنة الأصول من ScopeSentry باش ينقص الجمع المكرر. حلّ صفحة «مزامنة الأصول»، عمّر عنوان ScopeSentry وAPI Key، ومن بعد اختار حسب المشروع أو المهمة الأهداف وأنواع الأصول اللي بغيتي تزامنها.

الأصول

  • كيدعم اختيار أنواع الأصول حسب النطاق، بحال الدومينات، الدومينات الفرعية، عناوين IP، البورتات، المواقع ونقاط النهاية.
  • من بعد الاستيراد، كيتجمعو حسب نطاق أصول الشركة.
  • نتائج المزامنة كتمشي لخريطة أصول Autonomous Pentest Agent، باش تستعملها المهام التجريبية المحلية من بعد.
الأصول

تسجيل الترافيك والموافقة

النظام كيوفر بروكسي لتسجيل الترافيك، ويمكن تحديد عنوان الواجهة وواجهة API وعنوان بروكسي الترافيك بطريقة بحال ./start.sh -addr :8787 -proxy :8788. عملية تنفيذ الأدوات من طرف Worker كتخلي سجلات ديال الأنشطة، وآلية الموافقة على الاعتراض كتخلي الإنسان يأكد عمليات الأدوات ملي كيكون هاد الشي ضروري.

الترافيك

سجلات الموافقة كتدعم عرض التفاصيل داخل السجل العام للموافقات، والموافقات المعترَض عليها داخل المهمة، وبطاقات الموافقة فالمحادثة. خاصك ديما تراجع مزيان الهدف والمعاملات ديال العملية، وتحصر الهدف فبيئة تجريبية معزولة.

إعادة اختبار الثغرات

من تبويب «إعادة الاختبار» فتفاصيل المهمة، تقدر تختار الثغرات على صفحات، وتشوف الاستنتاجات والأدلة السابقة، وتطلق جلسة مستقلة مع Agent لإعادة الاختبار. لائحة الثغرات، تفاصيل الثغرة ومنظر الأصول كاملين كيوفرو مدخل لإعادة الاختبار.

استنتاجات إعادة الاختبار كتشمل «ما زالت قابلة لإعادة الإنتاج»، «تصلحات» و«ما قدرناش نأكدو». استنتاج كل إعادة اختبار، والأدلة ورابط الجلسة كيتحفظو فتفاصيل الثغرة. إلا نجحات إعادة الاختبار وكان الاستنتاج «تصلحات»، النظام كيحدّث حالة معالجة الثغرة أوتوماتيكيا؛ أما التنفيذ الجاري، الفاشل، المتوقف أو أي استنتاج آخر، ما كيبدلش الحالة الأصلية أوتوماتيكيا.

أول مرة كيبدا فيها الـ backend، كيكون محضّر Agent قابل للتعديل سميتو «إعادة اختبار الثغرات»، يعني retester. تقدر تضبط فيه البرومبت، وLLM، وميزانية التشغيل والأدوات من إدارة Agents. إلا كانت نفس الثغرة كتعاود تختبر، النظام كيعاود يستعمل الجلسة الموجودة؛ ومن بعد التوقيف، الفشل أو إعادة تشغيل الخدمة، تقدر تطلق الاختبار من جديد. README كيوضح حتى أن سجلات إعادة الاختبار القديمة ما داخلاش حاليا فتصدير تقارير الثغرات ولا فحزمة أرشيف المهمة، وما مرتبطةش أوتوماتيكيا بحزمة الترافيك.

خريطة تغطية الأصول

النشر عبر بروكسي عكسي

الواجهة، API وSSE كيتقدمو افتراضيا من نفس بورت الـ backend، وبهذا غالبا ما كايناش حاجة لضبط NEXT_PUBLIC_SSE_BASE. إلا تعرّض HTTPS عبر Nginx، خاصك تسدّ التخزين المؤقت ديال SSE وتضبط مهلة قراءة طويلة:

server {
    listen 443 ssl;
    server_name your.domain.com;

    location / {
        proxy_pass http://127.0.0.1:8787;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

إلا كان SSE كيستعمل مصدر مختلف على الصفحة، غير فهاد الحالة خاصك تضبط NEXT_PUBLIC_SSE_BASE فمرحلة البناء. هاد المتغير كيتثبت فالحزمة الثابتة وقت next build، وضبطو وقت تشغيل الحاوية ما غاديش يخدم.

الترقية وحماية البيانات

وقت ترقية المشروع، كيتبدل البرنامج غير هو، وما كيتحيدوش عمدا مجلدات بيانات PostgreSQL ولا ./data ولا ./skills. ملي كيبدا التطبيق، كينفذ بشكل idempotent تهيئة بنية قاعدة البيانات والترحيلات، وبالتالي غالبا ما كايناش حاجة لتنفيذ سكريبتات الترحيل يدويا. ومع ذلك، خاصك دير نسخة احتياطية من ./data وقاعدة البيانات قبل الترقية.

من الأفضل تنفذ التحديث من بطاقة «الإصدار والتحديثات» فصفحة إعدادات النظام. البرنامج كينزل حزمة الإصدار الخاصة بالمنصة الحالية، كيتحقق من SHA256، كيدير اختبارا سريعا، ومن بعد سكريبت التشغيل كيكمل الاستبدال. إلا فشل التحقق، كيتحيد الملف المؤقت؛ وإلا فشل الإصدار الجديد فالإقلاع بشكل متتابع، كيرجع النظام تلقائيا للإصدار السابق. التحديث كيعيد تشغيل الخدمة وكيقطع المهام اللي خدامة، لذلك خاصو يتدار فوقت ما كايناش فيه مهام.

فالنشر باستعمال Docker، تحديث الصفحة كيبدل البرنامج غير هو، وما كيحدّثش أدوات بحال Playwright وnmap الموجودة فالصورة. باش تحدّث الصورة، شغّل:

الترافيك

docker compose pull apagent
docker compose up -d apagent

وتقدر حتى تستعمل سكريبت التحديث الموجود فالمستودع:

./update.sh

التطوير والاختبار المحلي

فمود التطوير، تقدر تشغل فآن واحد الـ backend، بروكسي الترافيك وسيرفر التطوير ديال Next.js:

./dev.sh

العنوان الافتراضي للدخول هو http://localhost:5173. وتقدر حتى تشغلهم بشكل منفصل:

go run ./cmd/apagent
cd web && npm run dev
go test ./...

إلا ما استعملتيش -tags embedui، الـ backend ما كيضمنش الواجهة الأمامية داخلو. إلا بغيتي غير تشوف الواجهة بلا ما تشغل الـ backend، استعمل:

cd web && NEXT_PUBLIC_MOCK=1 npm run dev

ملاحظات مهمة

  • تأكد بلي PostgreSQL خدام، وراجع اسم المستخدم، كلمة السر، اسم قاعدة البيانات والبورت.
  • إلا نجح اتصال تدفق الأنشطة ولكن ما بان حتى حدث، راجع واش البروكسي العكسي سدّ التخزين المؤقت، وتأكد بلي مهلة الاتصال الطويل كافية.
  • ملي كتستعمل نسخة مترجمة مسبقا، ما تتجاوزش start.sh ولا start.bat، حيث آلية التبديل وإعادة التشغيل الأوتوماتيكية من بعد تحديث الصفحة تقدر ما تخدمش مزيان.
  • من بعد تعديل الموارد الثابتة ديال الواجهة، خاصك تعاود تنفذ npm run build:static، ومن بعد تنسخها لـ server/webui/dist وتعاود تترجم البرنامج.
  • دير نسخة احتياطية من قاعدة البيانات، ./data و./skills قبل الترقية؛ بنية قاعدة البيانات تقدر تترحل أوتوماتيكيا، ولكن ما كايناش عودة تلقائية.
  • ما تدخلش أصول حقيقية من الإنترنت، بيانات اعتماد الإنتاج أو بيانات حساسة للنظام التجريبي المحلي.

الخلاصة

Autonomous Pentest Agent كيجمع بين خدمة Go، واجهة Next.js، نموذج بيانات مزدوج بالرسوم البيانية فـ PostgreSQL، وتنسيق متعدد الوكلاء باستعمال LLM، وكيقدم تدبير المهام، مسار الاستكشاف، تغطية الأصول، تتبع الترافيك، الموافقات وإعادة اختبار الثغرات. تقدر تبدا باستعمال Docker أو سكريبت التثبيت فبيئة محلية معزولة، ومن بعد تضبط قاعدة البيانات وLLM، وفالأخير تفهم سلوك النظام تدريجيا عبر المهام، خريطة الأصول وجلسات التنفيذ. أثناء الاستعمال، خاصك تلتزم باستعمال المشروع للتعلم المحلي وبجميع المتطلبات القانونية والتنظيمية.

المشروع مرخّص برخصة AGPL-3.0؛ إلا عدلتيه وقدمت الخدمة للمستخدمين عبر الشبكة، خاصك تنشر المصدر الكامل المعني حسب متطلبات الرخصة. لمزيد من تفاصيل التنفيذ، راجع المصدر الموجود فالمستودع، وnorma SDK وملف LICENSE ديال المشروع.