h3-cli

خادم NodeZero MCP

يتوفر الآن خادم NodeZero MCP، مما يتيح لك تشغيل وإدارة خادم MCP مستضاف محليًا يجلب إمكانيات NodeZero في البحث والإصلاح والتحقق (FFV) مباشرةً إلى سير عمل التطوير والأمان لديك.

README الخاص بـ MCP

h3-cli: أداة سطر أوامر لواجهة برمجة تطبيقات Horizon3.ai

h3-cli هي أداة CLI ملائمة (واجهة سطر أوامر) للوصول إلى واجهة برمجة تطبيقات Horizon3.ai. توفر واجهة برمجة تطبيقات Horizon3.ai وصولاً برمجيًا إلى مجموعة فرعية من الوظائف المتاحة عبر بوابة Horizon3.ai. على مستوى عالٍ، تتيح لك الواجهة:

• جدولة اختبار اختراق مستقل
• تنزيل وتشغيل NodeZero™
• مراقبة حالة اختبار الاختراق أثناء تشغيله
• استرجاع تقرير اختبار الاختراق بعد اكتماله

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

التثبيت والإعداد الأولي

الخطوات أدناه ستعمل على تشغيلك بسرعة باستخدام h3-cli. تم اختبار هذه التعليمات على أجهزة macOS وLinux، ويُفترض أن تعمل عمومًا على أي نظام متوافق مع POSIX يدعم bash.

إذا كنت تخطط لتشغيل اختبارات اختراق داخلية باستخدام h3-cli، فيجب عليك تثبيت h3-cli على نفس مضيف Docker الذي تشغّل فيه NodeZero.

من المفترض أن لديك حسابًا بالفعل لدى Horizon3.ai. إذا لم يكن لديك حساب، فسجّل في https://portal.horizon3ai.com/.

1. إنشاء مفتاح API

مطلوب مفتاح API للوصول إلى واجهة H3 API. يمكنك إنشاء واحد في البوابة ضمن قائمة User -> Account Settings.

عند إنشاء مفتاح API، يجب عليك تعيين دور يتحكم في صلاحياته. الأدوار المتاحة هي:

• User: صلاحيات أساسية للقراءة/الكتابة. يمكن لمفتاح API تشغيل اختبارات الاختراق وقراءة النتائج.
• Read-only: يمكن لمفتاح API قراءة نتائج اختبارات الاختراق، لكن لا يمكنه تشغيلها.
• NodeZero Runner: دور متخصص ومقيّد بشدة، مصمم خصيصًا لـ NodeZero Runners.

نوصي بدور User إذا كنت تختبر h3-cli وترغب في تجربة جميع ميزاته. بعد ذلك، قد ترغب في استخدام صلاحيات أكثر تقييدًا بناءً على حالة الاستخدام الخاصة بك. على سبيل المثال، إذا كنت تريد فقط استخدام h3-cli لإعداد NodeZero Runner، نوصي باستخدام دور NodeZero Runner.

يمكنك بسهولة إدارة مفاتيح API متعددة داخل نفس تثبيت h3-cli. تعلم المزيد هنا.

❗ حافظ على أمان مفتاح API الخاص بك، لأن أي شخص لديه مفتاح API الخاص بك يمكنه الوصول إلى حساب H3 الخاص بك. فكّر في مفتاح API باعتباره اسم مستخدم + كلمة مرور في واحد. يمكن لأي شخص لديه مفتاح API الوصول إلى حسابك من أي مكان. سيخزن h3-cli مفتاح API الخاص بك تحت دليل $HOME/.h3. يتم إنشاء هذا الدليل أثناء التثبيت وتكوينه بصلاحيات تتيح لك فقط القراءة أو الكتابة فيه.

2. تثبيت h3-cli

ثبّت مستودع h3-cli git على جهازك عن طريق تنفيذ أمر git التالي داخل جلسة شل/طرفية.

git clone https://github.com/horizon3ai/h3-cli

سيؤدي هذا إلى إنشاء دليل جديد باسم h3-cli وتنزيل محتويات المستودع إليه. سيتم إنشاء دليل h3-cli في الدليل الذي تشغّل فيه أمر git. يمكنك تثبيت h3-cli في أي مكان على نظام الملفات.

إذا لم يكن لديك git، يمكنك تنزيل المستودع كملف zip من القائمة أعلاه، وفك ضغطه في أي مكان على نظام الملفات.

3. تشغيل سكربت تثبيت h3-cli

شغّل الأوامر التالية لتثبيت وتهيئة h3-cli. استبدل your-api-key-here بمفتاح API الفعلي الخاص بك.

cd h3-cli
bash install.sh your-api-key-here

سيقوم سكربت التثبيت بتثبيت التبعيات (jq) وإنشاء ملف تعريف h3-cli الافتراضي لديك تحت دليل $HOME/.h3. يتم تخزين مفتاح API الخاص بك في ملف تعريف h3-cli. صلاحيات الدليل والملف التعريفي مقيدة بحيث لا يمكن لأي مستخدمين آخرين (بخلافك) القراءة أو الكتابة فيهما.

سيطلب منك سكربت التثبيت تعديل ملف تعريف الشل الخاص بك ($HOME/.bash_profile أو $HOME/.bash_login أو $HOME/.profile، اعتمادًا على نظام التشغيل لديك) لتعيين متغيرات البيئة التالية:

• H3_CLI_HOME: يستخدم h3-cli متغير البيئة هذا لتحديد موقعه وملفاته الداعمة.
• PATH: يحدد متغير البيئة هذا الدلائل التي سيتم البحث فيها للعثور على أمر شل.

بعد تحديث ملف تعريف الشل، أعد تسجيل الدخول أو أعد تشغيل جلسة الشل لالتقاط تغييرات الملف الشخصي، ثم تحقق من أنه يمكنك استدعاء h3 عن طريق تشغيله من موجه الأوامر:

h3

إذا تم تثبيت كل شيء بشكل صحيح، يجب أن ترى نص مساعدة h3-cli.

ترقية h3-cli

نصدر ميزات جديدة وإصلاحات للأخطاء وتحديثات أخرى لـ h3-cli كل شهر. قم بترقية تثبيتك باستخدام إحدى الطرق أدناه.

الخيار 1: عبر أمر h3 upgrade (موصى به)

اعتبارًا من يونيو 2023، يمكنك استخدام أمر h3 upgrade للترقية إلى أحدث إصدار من h3-cli.

إذا حصلت على ERROR: unrecognized command: "upgrade"، فأنت على إصدار سابق من h3-cli لا يدعم أمر الترقية. استخدم إحدى الطرق أدناه لترقية h3-cli.

الخيار 2: عبر easy_install.sh (موصى به إذا كان h3 upgrade غير متاح)

شغّل هذا الأمر من الدليل الأصلي لـ h3-cli (أي الدليل الذي يحتوي على دليل h3-cli/):

curl https://raw.githubusercontent.com/horizon3ai/h3-cli/public/easy_install.sh | bash 

الخيار 3: عبر git

إذا كنت قد استخدمت git clone لتثبيت المستودع، فما عليك سوى تشغيل git pull لتثبيت أحدث إصدار.

الخيار 4: عبر تنزيل zip

إذا قمت بتنزيل المستودع كملف zip، فأعد تنزيل ملف zip وفك ضغطه في نفس الموقع (أي استبدل تثبيت h3-cli الحالي بالملف zip الجديد).

التحقق من الإصدار الحالي

اعتبارًا من يونيو 2023، يمكنك عرض إصدارك الحالي من h3-cli عبر:

h3 version

يمكنك عرض السجل الكامل للإصدارات وملاحظات الإصدار عبر:

h3 version -v

البدء

1. التحقق من الاتصال بالواجهة البرمجية

شغّل الأمر التالي للتحقق من الاتصال بالواجهة البرمجية.

h3 hello-world

يجب أن ترى الرد:

{
  "data": {
    "hello": "world!"
  }
}

❗️ إذا كنت تتلقى استجابة خطأ، يرجى الاتصال بـ H3 عبر أيقونة الدردشة في بوابة Horizon3.ai.

2. الاستعلام عن قائمة اختبارات الاختراق في حسابك

سيعيد الأمر أدناه قائمة اختبارات الاختراق في حسابك، الأحدث أولاً.

h3 pentests 

لتصفية اختبارات الاختراق التي تطابق مصطلح بحث معين، مرّر مصطلح البحث كمعامل:

h3 pentests sample

3. الاستعلام عن اختبار اختراق محدد من حسابك

للاستعلام عن أحدث اختبار اختراق في حسابك:

h3 pentest

للاستعلام عن أي اختبار اختراق في حسابك، مرّر op_id الخاص باختبار الاختراق كمعامل:

h3 pentest your-op-id-here

ستستخدم العديد من أوامر h3-cli أحدث اختبار اختراق كافتراضي، ما لم يتم تمرير op_id كمعامل.

غالبًا ما يتم استخدام المصطلحين "op" و"pentest" بالتبادل.

4. تشغيل اختبار اختراق

يتطلب تشغيل اختبار اختراق تحديد قالب op. يحدد قالب op تكوين اختبار اختراق كامل، يتضمن النطاق ومعلمات الهجوم والتكوينات الأخرى (الاختيارية).

توفر Horizon3.ai للمستخدمين الجدد قالب op افتراضيًا باسم Default 1 - Recommended. هذا القالب دائمًا محدث بأحدث معلمات الهجوم والتكوين الموصى به. لا يحدد القالب الافتراضي نطاقًا، وفي هذه الحالة سيستخدم NodeZero النطاق الذكي - ستوفر الشبكة الفرعية المضيفة لـ NodeZero النطاق الأولي، وسيتوسع عضويًا أثناء اختبار الاختراق مع اكتشاف المزيد من المضيفات والشبكات الفرعية. لمزيد من المعلومات حول النطاق الذكي وخيارات النشر الأخرى، قم بزيارة وثائق المنتج.

للمستخدمين المتمرسين، يمكن إنشاء قالب/قوالب op مخصصة عبر بوابة Horizon3.ai. لإنشاء قالب op مخصص، انتقل عبر نموذج Run a Pentest حتى ترى خيار تخصيص تكوين اختبار الاختراق. يمكن إنشاء قالب op دون تشغيل اختبار الاختراق فعليًا.

لتوفير اختبار اختراق باستخدام قالب op الافتراضي والنطاق الذكي:

h3 run-pentest

تحتوي استجابة JSON على تفاصيل اختبار الاختراق المنشأ حديثًا. يمكنك التحقق من أن اختبار الاختراق قيد التجهيز عن طريق فحص بوابة Horizon3.ai، أو عن طريق تشغيل h3 pentest.

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

❗ انتظر! لم تنتهِ بعد!

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

إذا كنت تشغل اختبار اختراق خارجي، يتم إطلاق NodeZero لك تلقائيًا في سحابة H3 كجزء من h3 run-pentest، وفي هذه الحالة لا توجد خطوات إضافية من جانبك لبدء اختبار الاختراق.

5. تشغيل NodeZero

❗ ️تنطبق الخطوة التالية على اختبارات الاختراق الداخلية فقط؛ أما بالنسبة لاختبارات الاختراق الخارجية، فسيتم إطلاق NodeZero لك تلقائيًا في سحابة H3.

بعد إنشاء اختبار اختراق داخلي، يجب عليك بعد ذلك تشغيل حاوية NodeZero على مضيف Docker داخل شبكتك. يتم ذلك عن طريق تشغيل سكربت إطلاق NodeZero على مضيف Docker لديك.

لتشغيل سكربت إطلاق NodeZero لأحدث اختبار اختراق قمت بإنشائه:

h3 run-nodezero

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

NodeZero هي حاوية Docker. يمكنك عرضها باستخدام docker ps. سيكون اسم الحاوية بالشكل n0-xxxx.

6. تنزيل تقارير اختبار الاختراق

بعد انتهاء اختبار الاختراق، استخدم الأمر التالي لتنزيل ملف zip يحتوي على جميع تقارير PDF وCSV لأحدث اختبار اختراق تم إنشاؤه:

h3 pentest-reports

سيقوم الأمر أعلاه بتنزيل ملف zip إلى pentest-reports-{op_id}.zip في الدليل الحالي.

حالات الاستخدام

• النشر الآلي لـ NodeZero باستخدام NodeZero Runner. تعرّف على كيفية استخدام NodeZero Runner لنشر NodeZero على مضيف Docker تلقائيًا، دون الحاجة إلى نسخ ولصق سكربت إطلاق NodeZero يدويًا.
• الجدولة الآلية. تعرّف على كيفية تشغيل اختبارات الاختراق تلقائيًا وفق جدول منتظم، على سبيل المثال مرة أسبوعيًا أو مرة شهريًا.
• الاعتمادات المُحقنة تلقائيًا. تعرّف على كيفية حقن الاعتمادات تلقائيًا في اختبار اختراق مجدول بانتظام باستخدام NodeZero Runner.
• مراقبة اختبارات الاختراق. تعرّف على كيفية مراقبة اختبارات الاختراق باستخدام h3-cli.
• ترقيم صفحات النتائج. تعرّف على كيفية التنقل بين الصفحات عبر مجموعات النتائج الكبيرة باستخدام h3-cli.
• تحليل JSON باستخدام jq. تعرّف على كيفية الاستفادة من قوة jq لتحليل استجابات JSON من h3-cli. يمكن لـ jq تحليل حقول محددة، وطباعة بنية الاستجابة، وحتى تحويل استجابة JSON إلى CSV.

المصادقة وملفات تعريف h3-cli

تتم المصادقة بسلاسة وتلقائيًا عند استدعاء أمر h3. لا يوجد شيء صريح عليك القيام به للمصادقة. يوثق هذا القسم الآليات الأساسية.

يقرأ h3-cli مفتاح H3_API_KEY من ملف تعريف h3-cli الخاص بك (تحت $HOME/.h3) للمصادقة على واجهة Horizon3.ai API وإنشاء جلسة (مؤقتة). يتم تخزين رمز الجلسة (JWT) مؤقتًا تحت $HOME/.h3. تنتهي صلاحية رمز الجلسة بعد ساعة واحدة، وعندها سيقوم h3-cli تلقائيًا بإعادة المصادقة وإعادة إنشاء جلسة.

يمكنك المصادقة صراحة باستخدام الأمر التالي:

h3 auth

سيقوم الأمر أعلاه بإخراج رمز الجلسة (ويخزنه أيضًا مؤقتًا تحت $HOME/.h3). إذا كان لديك بالفعل رمز جلسة (غير منتهي الصلاحية)، فسيستمر h3 auth في استخدام رمز الجلسة هذا بدلاً من إعادة المصادقة.

إذا كنت تريد إجبار h3-cli على إعادة المصادقة، استخدم خيار force:

h3 auth force

ملفات تعريف h3-cli

يمكنك إدارة ملفات تعريف مصادقة متعددة لـ h3-cli تحت نفس دليل $HOME/.h3. كل ملف تعريف h3-cli له مفتاح API خاص به.

عند تثبيت h3-cli لأول مرة، سيقوم تلقائيًا بإنشاء ملف تعريف أولي باسم default بمفتاح API الذي قدمته إلى install.sh.

إذا كنت ترغب في إنشاء ملف تعريف آخر بمفتاح API مختلف، استخدم الأمر التالي:

h3 save-profile my-profile {api-key}

سيؤدي هذا إلى إنشاء ملف تعريف باسم my-profile تحت $HOME/.h3 لمفتاح {api_key} المحدد. لتفعيل الملف الشخصي في جلسة الشل الحالية، استخدم الأمر التالي (لاحظ النقطة البادئة .):

. h3 profile my-profile

يمكنك التحقق من الملف الشخصي النشط حاليًا باستخدام h3 profile، وعرض تفاصيل حول مفتاح API الخاص به باستخدام h3 whoami:

h3 profile
h3 whoami

يمكنك حفظ مفاتيح API متعددة تحت ملفات تعريف h3-cli مختلفة والتبديل بينها حسب الحاجة باستخدام الأمر أعلاه. على سبيل المثال، للرجوع إلى ملف التعريف default:

. h3 profile default

لعرض قائمة ملفات تعريف h3-cli تحت دليل $HOME/.h3:

h3 profiles

يمكنك حذف ملف تعريف من دليل $HOME/.h3 باستخدام:

h3 delete-profile {name}

سيقوم هذا بإزالة ملف التعريف المسمى {name} ومفتاح API الخاص به من دليل $HOME/.h3 على الجهاز المحلي. لاحظ أنه لن يقوم بإبطال مفتاح API؛ فهو يحذفه فقط من الجهاز المحلي. يمكنك إبطال مفتاح API من البوابة.

تشغيل اختبارات الاختراق باستخدام h3-cli

يحتوي هذا القسم على أمثلة إضافية لتشغيل اختبارات الاختراق باستخدام h3-cli.

أبسط طريقة لتوفير اختبار اختراق هي استخدام قالب op الافتراضي و_النطاق الذكي_:

h3 run-pentest

لتوفير اختبار اختراق وإطلاق NodeZero على الجهاز المحلي (لاختبارات الاختراق الداخلية فقط):

h3 run-pentest-and-nodezero

لاحظ أن هذا ينطبق فقط على اختبارات الاختراق الداخلية. بالنسبة لاختبارات الاختراق الخارجية، يتم إطلاق NodeZero لك تلقائيًا في سحابة H3 كجزء من h3 run-pentest.

إذا صادف أن قمت بتشغيل h3 run-pentest-and-nodezero لاختبار اختراق خارجي، فسيتخطى ببساطة الجزء الذي يقوم فيه بتنزيل وتشغيل NodeZero، حيث يتم التعامل مع ذلك تلقائيًا في سحابة H3.

لتشغيل اختبار اختراق باستخدام قالب op مخصص، حدده كمعامل لـ schedule_op_template.graphql:

h3 run-pentest '{"op_template_name":"your-op-template-here"}' 

لتشغيل اختبار اختراق باستخدام قالب op الافتراضي ولكن مع تعيين اسم من اختيارك، استخدم معامل op_name الاختياري:

h3 run-pentest '{"op_name":"your-op-name-here"}' 

لتشغيل اختبار اختراق باستخدام قالب op الافتراضي ولكن مع تحديد اسمه ونطاقه، استخدم معامل schedule_op_form الاختياري:

h3 run-pentest '{"schedule_op_form":{"op_name":"your-op-name-here", "op_param_max_scope": "192.168.0.0/24"}}' 

لاحظ أن h3 run-pentest وh3 run-pentest-and-nodezero يقبلان جميع المعاملات الاختيارية نفسها.

لتشغيل اختبار اختراق وتعيينه إلى NodeZero Runner باسم my-nodezero-runner:

h3 run-pentest '{"schedule_op_form":{"op_name":"Pentest created via h3-cli and launched via runner", "runner_name":"my-nodezero-runner"}}' 

تشغيل اختبارات الاختراق الخارجية

إذا كان لديك قالب op مهيأ لاختبار الاختراق الخارجي الخاص بك:

h3 run-pentest '{"op_template_name":"your-op-template-here"}' 

إذا لم يكن لديك قالب op، يمكنك تشغيل اختبار اختراق خارجي عن طريق البحث أولاً عن uuid مجموعة الأصول الخاصة بك عبر h3 asset-groups:

h3 asset-groups

ثم استخدم الأمر أدناه لتشغيل اختبار اختراق خارجي ضد مجموعة الأصول هذه. استبدل uuid مجموعة الأصول الخاصة بك بـ {your-asset-group-uuid}:

h3 run-pentest '{"schedule_op_form": {"op_type": "ExternalAttack", "asset_group_uuid": "{your-asset-group-uuid}"}}' 

مدعوم بواسطة GraphQL

واجهة برمجة تطبيقات Horizon3.ai مدعومة بواسطة GraphQL. بالإضافة إلى وثائق CLI هذه، تشمل الوثائق ذات الصلة:

• Horizon3.ai Docs
• GraphQL.org

متقدم: كتابة استعلامات GraphQL الخاصة بك

يوفر h3-cli آلية بسيطة لتشغيل استعلامات GraphQL الخاصة بك. أولاً، عرّف استعلام GraphQL في ملف (عادةً بامتداد .graphql، على الرغم من أن ذلك غير مطلوب). ثم مرّر الملف إلى h3 gql:

h3 gql {your-query-file}

على سبيل المثال، عرّف ما يلي في ملف باسم my_session.graphql:

query {
    session_user_account {
        email
        name
        company_name
    }
}

ثم شغّل:

h3 gql ./my_session.graphql

يجب أن ترى استجابة JSON الأولية من خادم GraphQL. يمكنك تنسيق استجابة JSON بشكل جميل باستخدام jq:

h3 gql ./my_session.graphql | jq .

مهم! يجب عليك تحديد المسار إلى ملف graphql (كامل أو نسبي، على سبيل المثال ./my_session.graphql بدلاً من my_session.graphql فقط)، وإلا فإنك تخاطر بالتصادم مع ملفات graphql التي يستخدمها h3-cli داخليًا.

متقدم: استعلامات GraphQL ذات المعاملات

يمكن لاستعلامات GraphQL أيضًا تحديد معاملات، تمرر إلى h3 gql ككائن JSON.

على سبيل المثال، عرّف ما يلي في ملف باسم my_pentest.graphql:

query q($op_id: String!) {
    pentest(op_id:$op_id) {
        op_id
        name
        state
    }
}

في هذا المثال، $op_id معامل يجب توفيره لتشغيل الاستعلام. يتم تمرير المعامل إلى الاستعلام داخل كائن JSON:

h3 gql ./my_pentest.graphql '{"op_id":"your-op-id-here"}' | jq .

استبدل your-op-id-here بـ op_id فعلي.