.. _corelight-client:

.. Version number is filled in automatically. .. |version| replace:: 1.5.22

==================================== Corelight Sensor Command Line Client

.. contents::

نظرة عامة

توفر هذه الأداة عميلاً لسطر الأوامر لـ Corelight Sensor <https://www.corelight.com>، وهو جهاز Bro <https://www.bro.org> صُمم من الأساس بواسطة مبتكري Bro لتحويل حركة مرور الشبكة إلى بيانات عالية الدقة لخط تحليلاتك. باستخدام عميل سطر الأوامر، يمكنك تكوين والتحكم في Corelight Sensor عن بُعد من خلال واجهة RESTful API الشاملة الخاصة به. راجع وثائق Corelight Sensor للحصول على نسخة موسعة من نظرة عامة العميل هذه.

:Version: |version| :Home: http://www.corelight.com :GitHub: https://github.com/corelight/corelight-client :Author: Corelight, Inc. <https://www.corelight.com>_ [email protected]

الترخيص

هذا العميل مفتوح المصدر بموجب ترخيص BSD. راجع COPYING للتفاصيل.

التثبيت

يحتاج عميل سطر الأوامر إلى Python >= 3.4 مع تثبيت وحدة requests كاعتماده الرئيسي.

أسهل طريقة لتثبيت العميل هي من خلال Python Package Index::

# pip3 install corelight-client

بدلاً من ذلك، يمكنك تثبيت أحدث إصدار من GitHub::

# git clone https://github.com/corelight/corelight-client
# cd corelight-client
# pip3 install setuptools
# python3 setup.py install

إذا تم تثبيت كل شيء بشكل صحيح، فإن --help سيعطيك رسالة الاستخدام::

# corelight-client --help
Usage: corelight-client [<global options>] <command> <subcommand> [<options>]
          [--ssl-ca-cert SSL_CA_CERT] [--ssl-no-verify-certificate]
          [--ssl-no-verify-hostname] [--cache CACHE]
[...]

لاحظ أنه في البداية، لن يعرض لك --help أي أوامر أخرى لاستخدامها. انتقل إلى القسم التالي للسماح للعميل بالاتصال بجهازك.

الوصول والمصادقة

تحتاج إلى تمكين الوصول إلى Corelight API من خلال واجهة تكوين الجهاز. تحتاج أيضًا إلى تعيين كلمات مرور لمستخدمي API admin (للوصول غير المحدود) و monitor (للوصول للقراءة فقط). راجع وثائق Corelight Sensor لمزيد من المعلومات.

بعد ذلك، تحتاج إلى إخبار corelight-client بعنوان الشبكة لـ Corelight Sensor الخاص بك. لديك ثلاثة خيارات للقيام بذلك:

• أضف -b <address> إلى سطر الأوامر.

• أنشئ ملف تكوين ~/.corelight-client.rc بالمحتوى device=<address>.

• عيّن متغير البيئة CORELIGHT_DEVICE=<address>.

إذا تم إعداد كل ذلك، فإن corelight-client --help سيطلب منك الآن اسم مستخدم وكلمة مرور، ثم سيعرض لك القائمة الكاملة للأوامر التي تتيح واجهة API الخاصة بالجهاز للعميل تقديمها. إذا أكدت حفظ بيانات الاعتماد، سيقوم العميل بتخزينها في ~/.corelight-client/credentials لإعادة استخدامها مستقبلاً. يمكنك أيضًا تحديد معلومات المصادقة من خلال Configuration File_ أو كـ Global Options_.

الاستخدام

يوفر العميل وظائف API من خلال مجموعة من الأوامر بالتنسيق <command> <subcommand> [options]. بإضافة --help إلى أي أمر، تحصل على وصف لجميع وظائفه وخياراته.

إذا أدرج مخرجات --help خيار أمر ما من النوع file، فإن العميل يتطلب منك تحديد مسار ملف لإرساله. بالإضافة إلى ذلك، يمكنك إضافة البادئة file:// إلى قيمة أي خيار لقراءة محتواه من ملف بدلاً من إعطائه على سطر الأوامر نفسه.

(ملاحظة: ستحتوي مخرجات --help على قائمة الأوامر فقط إذا تمكن العميل من الاتصال والمصادقة على الجهاز.)

.. _corelight-client-options:

الخيارات العامة

يدعم corelight-client خيارات سطر الأوامر العامة التالية. يجب استخدام خياري --device و --fleet بشكل حصري متبادل من بعضهما البعض. تنطبق جميع الخيارات الأخرى على جميع الطلبات:

--async لا ينتظر اكتمال الأوامر غير المتزامنة قبل الخروج.

--device يحدد عنوان الشبكة لجهاز Corelight Sensor.

--fleet يحدد عنوان الشبكة لـ Corelight Fleet Manager.

--uid يحدد UID لـ Corelight Sensor المُدار من خلال Corelight Fleet Manager المحدد.

--cache=<file> يعيّن ملفًا مخصصًا لتخزين بيانات Corelight Sensor الوصفية مؤقتًا.

--debug يمكّن مخرجات التصحيح التي تعرض طلبات HTTP وردودها.

--password يحدد كلمة المرور للمصادقة.

--mfa يحدد رمز التحقق بخطوتين (2FA) للمصادقة مع Corelight Fleet Manager المحدد. استخدم '-' لسؤال المستخدم.

--ssl-ca-cert يحدد ملفًا يحتوي على شهادة SSL CA مخصصة للتحقق من صحة الجهاز.

--ssl-no-verify-certificate يوجه العميل لقبول أي شهادة SSL لـ Corelight Sensor.

--ssl-no-verify-hostname يوجه العميل لقبول شهادة SSL الخاصة بـ Corelight Sensor حتى لو لم تتطابق مع اسم المضيف الخاص به.

--socket يوجه العميل لاستخدام unix domain socket لإرسال الطلبات.

--user يحدد اسم المستخدم للمصادقة.

--version يعرض إصدار corelight-client ويخرج.

--ignore-meta لا ترسل معلومات البيانات الوصفية إلى استدعاء API الخاص بالجهاز، إلا إذا تم تحديدها على CLI.

--automation يمكّن مجموعة من السلوكيات الملائمة للأتمتة: مهل الطلبات، إعادة المحاولة عند الفشل العابر، أخطاء JSON المنظمة، تصنيف رموز الخروج المنسق، والتأكيد الصارم غير التفاعلي. راجع Automation_ أدناه للتفاصيل. يمكن أيضًا تمكينه عن طريق تعيين متغير البيئة CORELIGHT_AUTOMATION=1.

--timeout يعيّن مهلة الطلب بالثواني، إما كرقم واحد N (يُطبق على كل من الاتصال والقراءة) أو كـ connect,read. القيمة الافتراضية هي 10,3600 عند تمكين --automation.

--retries يعيّن عدد مرات إعادة المحاولة للفشل العابر (أخطاء الاتصال، و HTTP 429/502/503/504 للطلبات المتكررة بأمان). القيمة الافتراضية هي 3 عند تمكين --automation، و 0 بخلاف ذلك.

--retry-max-time يعيّن الحد الأقصى لإجمالي عدد الثواني التي تُقضى في إعادة المحاولة. القيمة الافتراضية هي 120 عند تمكين --automation.

--error-format يعيّن تنسيق المخرجات/الأخطاء إلى text أو json. القيمة الافتراضية هي json عند تمكين --automation، و text بخلاف ذلك.

--assume-yes يمضي قدمًا في العمليات المحمية بالتأكيد دون مطالبة (اسم مستعار: --confirm). مطلوب لتنفيذ العمليات المدمّرة أثناء تمكين --automation؛ وإلا فإن تلك العمليات تفشل بخطأ يتطلب التأكيد.

الأتمتة

تمرير --automation (أو تعيين CORELIGHT_AUTOMATION=1) يمكّن مجموعة من السلوكيات الملائمة للأتمتة ويشغّل تصنيف رموز الخروج أدناه. وهو يتضمن --noblock ويستخدم افتراضيًا مهلة اتصال 10 ثوانٍ / قراءة 3600 ثانية، و3 مرات إعادة محاولة (بحد أقصى 120 ثانية إجمالاً)، ومخرجات JSON لكل من النجاح والخطأ. يمكن تجاوز كل جزء بعلمه الخاص.

بدون --automation لا توجد مهلة طلب على الإطلاق (يحجب العميل إلى أجل غير مسمى)، لذا فإن تمكينه لا يقصّر أبدًا مهلة كانت موجودة من قبل. مهلة القراءة الافتراضية طويلة عمدًا: فهي تهدف فقط إلى تحديد اتصال متعطل، وليس لتقييد العمل الطبيعي. بعض العمليات، مثل عمليات الرفع الكبيرة، يمكن أن تستغرق بشكل مشروع عدة دقائق، وتنطبق مهلة القراءة على كل عملية قراءة شبكة بدلاً من النقل بأكمله، لذا فإن الرفع المستمر يعيد تعيينها باستمرار. خفّض --timeout إذا كنت تريد أن تتخلى الأتمتة بشكل أسرع، أو ارفعه لعملية نقل كبيرة بشكل غير عادي عبر رابط بطيء.

إعادة المحاولة تراعي الطلبات المتكررة بأمان: طلبات GET/HEAD/OPTIONS تعيد المحاولة عند فشل الاتصال وعند HTTP 429/502/503/504. الطرق غير الآمنة (POST/PUT/DELETE) تعيد المحاولة فقط عندما تنتهي مهلة الاتصال قبل أن يصل إلى الخادم أبدًا، لذا لا يتم إرسال تعديل مرتين. لأي فشل عابر آخر على طريقة غير آمنة، لا يعيد العميل المحاولة؛ بل يخرج بالرمز المطابق (ويضبط retriable في غلاف خطأ JSON) حتى يتمكن المستدعي، الذي يعرف وحده ما إذا كانت عمليته آمنة للتكرار، من اتخاذ القرار.

--retry-max-time هو ميزانية زمنية إجمالية لحلقة إعادة المحاولة، تُقاس من المحاولة الأولى وتشمل الوقت المستغرق في الطلبات نفسها. يتم التحقق منه قبل كل محاولة جديدة: بمجرد أن يتجاوز الوقت المنقضي بالإضافة إلى التراجع التالي هذه الميزانية، لا تبدأ أي محاولة أخرى. لا يقطع أبدًا طلبًا قيد التنفيذ بالفعل -- مدة الطلب الواحد محدودة بمهلة القراءة أعلاه، وليس بهذه القيمة.

رموز الخروج (فقط عند تمكين الأتمتة):