IBM Sample Code

يحتوي هذا المستودع على كود Python لإدارة أجهزة IBM الأمنية باستخدام واجهات REST API الخاصة بها. يتمتع جهاز ISAM بأكثر كود نضجًا.

الكود الخاص بجهاز ISDS قيد التطوير.

الكود الخاص بجهاز ISVG جديد تمامًا (تم اختباره مع الإصدار 10.0.1.0 وما فوق فقط).

المتطلبات

يتطلب هذا الحزمة Python الإصدار 3.9 وما فوق.

حزم Python التالية مطلوبة:

1. requests - لإجراء استدعاءات REST API
2. PyYAML - لكي يعمل الكود النموذجي
3. jmespath - مطلوب للكود النموذجي

حزم Python التالية اختيارية:

1. cryptography - لتنفيذ إجراءات على الشهادات (تُستخدم لضمان التماثل في management_ssl_certificate)
2. python-dateutil - أدوات التاريخ (تُستخدم لضمان التماثل في management_ssl_certificate)

يجب أن يكون للأجهزة عنوان IP محدد لواجهة LMI الخاصة بها. قد يعني هذا أن الأجهزة قد أكملت الإعداد الأولي لقبول الترخيص.

التحقق من TLS مفعّل (v2024.4.5)

هذه التغييرات متوافقة مع الإصدارات السابقة. الإعداد الافتراضي هو عدم التحقق، لكننا نعرض دائمًا إشعارًا:

Certificate verification has been disabled. Python is NOT verifying the SSL
certificate of the host appliance and InsecureRequestWarning messages are

being suppressed for the following host:

https://{0}:{1}

To use certificate verification:

1. When the certificate is trusted by your Python environment:
   Instantiate all instances of ISAMAppliance with verify=True or set
   the environment variable IBMSECLIB_VERIFY_CONNECTION=True.
2. When the certificate is not already trusted in your Python environment:
   Instantiate all instances of ISAMAppliance with the verify parameter
   set to the fully qualified path to a CA bundle.

See the following URL for more details:
https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification

لمعالجة تحذير التحقق من الشهادة هذا، يُرجى مراعاة الإرشادات أدناه:

الاستخدام الصحيح:

إذا كان لديك الشهادة على القرص في مكان ما، قم بإنشاء نسخة من ISAMAppliance مع:

ISAMAppliance(…, verify=<path to cert>)

يمكنك استرجاعها من الجهاز باستخدام أمر مثل:

openssl s_client -connect ${HOSTNAME}:${PORT} </dev/null 2>/dev/null | openssl x509 -outform pem >  isamAppliance.pem

إذا كانت الشهادة موثوقة بالفعل في بيئة Python الخاصة بك، قم بإنشاء نسخة من ISAMAppliance مع:

ISAMAppliance(…, verify=True)

أو قم بتعيين متغير البيئة: IBMSECLIB_VERIFY_CONNECTION=true

إذا تلقيت أخطاء حول عدم تطابق اسم المضيف مع الشهادة:

قد يبدو هذا كما يلي:

<stack trace>

…

    raise CertificateError("hostname %r doesn't match %r" % (hostname, dnsnames[0]))

urllib3.util.ssl_match_hostname.CertificateError: hostname '192.168.42.111' doesn't match 'appliance.ibm.com'

تأكد من أن اسم المضيف المستخدم عند إنشاء ISAMAppliance يطابق Subject Alternative Name الخاص بالشهادة.

تحقق باستخدام:

openssl x509 -in <cert-pem-file> -text

مثال:

$ openssl x509 -in /path/to/appliance.pem -text

Certificate:

Data:
    Version: 3 (0x2)
    …
        X509v3 Subject Alternative Name:
            DNS:appliance.ibm.com

…

سوف يؤدي ما يلي إلى توليد أخطاء:

ISAMAppliance(host=”192.168.42.111”, lmi_port=443, verify=/path/to/appliance.pem)

لأن المضيف لا يطابق Subject Alternative Name. بدلاً من ذلك، استخدم:

ISAMAppliance(host=”appliance.ibm.com”, lmi_port=443, verify=/path/to/appliance.pem)

الإصدارات

تستخدم هذه الحزمة تاريخًا للإصدارات. على سبيل المثال: "2017.03.18.0"

وهو تاريخ إصدار الحزمة مع رقم تسلسلي في النهاية للتعامل مع الحالات التي توجد فيها إصدارات متعددة في يوم واحد (من المتوقع أن يكون هذا غير شائع).

الميزات

توفر حزمة Python هذه الميزات التالية:

1. سهلة الاستخدام - يتم التعامل مع تفاصيل إجراء استدعاء REST داخل فئة الجهاز
2. تخطيط بديهي لحزمة الكود وتسمية تتوافق مع واجهة GUI للجهاز
3. التماثل (Idempotency) - الدوال التي تقوم بالتحديثات ستستعلم من الجهاز لمقارنة البيانات المعطاة لمعرفة ما إذا كانت هناك حاجة للتغيير قبل إجراء التغيير الفعلي.
4. يتم توفير خطوات Commit و Deploy بشكل منفصل لإتاحة المرونة في استدعائها
5. يتم تضمين تسجيل قياسي (logging) - مع إمكانية تعيين مستويات التسجيل.
6. ستستخدم معاملات الدوال قيمًا افتراضية قياسية حيثما أمكن.
7. يتم توفير خيار force لتجاوز التماثل.
8. يتم توفير دوال المقارنة - تأخذ مخرجات JSON وتقدم مقارنة ذات معنى.

تنسيق إرجاع بيانات الدالة

{
    rc:       <0 for success, higher for errors>
    changed:  <True or False>
    warnings: <List of strings with warnings - e.g. incompatible version>
    data:     <JSON data returned by appliance REST API that the function called>
}

ملاحظة: يُفضّل إرجاع تحذيرات بدلاً من إرسال rc غير صفري.

تنظيم الكود

فئات الأجهزة

يتم توسيع فئة مجردة ibmappliance لإنشاء فئة لكل جهاز مدعوم هنا. حاليًا هذه هي أجهزة ISAM و ISDS.

فئات المستخدمين

يتم توسيع مستخدم مجرد User لكل نوع مستخدم مطلوب. بالنسبة إلى ISAM، يوجد مستخدم للوصول إلى الجهاز وآخر للمصادقة على Web Runtime (Policy Server).

تخطيط حزم ISAM

توجد أربع حزم ISAM رئيسية - base و web و aac و fed. تحتوي web على جميع المكونات اللازمة لإعداد وظائف الويب بما في ذلك ldap المدمج ووقت التشغيل (runtime) والميزات التي يتم تفعيلها كجزء من وحدة wga. تحتوي aac على الميزات التي يتم تفعيلها كجزء من وحدة mga و fed على ميزات federation. تحتوي base على كل شيء آخر - بما في ذلك aac و fed runtime و Audit Configuration (وهذه مشتركة بين و وبالتالي فهي في ).

أسماء الحزم والملفات

تم إنشاء أسماء الحزم والملفات بالنية التالية:

1. الحفاظ على الأسماء التي تطابق ما هو موجود في واجهة GUI (LMI لجهاز ISAM).
2. يجب أن يحتوي كل ملف على نوع واحد فقط من كل نوع دالة (انظر القائمة أدناه) - أي دالة add() واحدة فقط.
3. تجميع الدوال ذات الصلة - واحدة من كل نوع - في ملف.
4. سيكون URI لاستدعاءات REST API داخل الملف هو نفسه ويدير "ميزة" من ميزات الجهاز.

الأدوات المساعدة

تحتوي على دوال متنوعة عامة ومستقلة عن أي جهاز IBM، على سبيل المثال json_compare().

أنواع الدوال

get_all()

تقوم هذه الدالة عادةً بإرجاع جميع الكائنات المتعلقة بتلك الميزة.

get()

تقوم هذه الدالة بإرجاع تفاصيل كائن معين واحد.

set()

ستحدد هذه الدالة ما إذا كان الكائن المطلوب التعامل معه موجودًا، إذا لم يكن كذلك فستستدعي add() وإلا ستستدعي update(). في الحالات التي لا توجد فيها update()، ستقارن لمعرفة ما إذا كان هناك فرق بين القيمة الموجودة على الجهاز وتلك التي يتم تعيينها عبر الدالة - إذا كانت مختلفة فستستدعي delete() للكائن قبل استدعاء add().

add()

تحقق مما إذا كان الكائن موجودًا بالفعل - إذا كان كذلك فتخطَّه، وإلا أضفه.

update()

تحقق مما إذا كان الكائن موجودًا بالفعل - إذا كان كذلك فتحقق مما إذا كان التحديث مطلوبًا قبل إجراء تغيير، وإلا لا تفعل شيئًا.

delete()

تحقق مما إذا كان الكائن موجودًا بالفعل - إذا كان كذلك فاحذفه، وإلا لا تفعل شيئًا.

import_<>()

"import" كلمة محجوزة، لذلك هناك لاحقة للإشارة إلى ما يجب استيراده (مثل ملف أو مفتاح). ستتحقق هذه الدالة مما إذا كان الكائن موجودًا قبل استيراده.

export_<>()

ستتحقق عملية التصدير من وجود الكائن قبل تصديره - وعند التصدير إلى ملف، إذا كان الملف موجودًا بالفعل فلن يتم إعادة تصديره. Export

compare()

تأخذ Compare مخرجات JSON من دوال get_all() وتقارنها. ستزيل البيانات من JSON الفريدة لكل جهاز (مثل قيم UUID). تشير قيمة deleted_keys التي يتم إرجاعها إلى مفاتيح JSON التي تم حذفها قبل المقارنة.

معاملات الدوال

كائن الجهاز

قم بإنشاء كائن جهاز ومرره إلى الدالة. كائنات الجهاز والمستخدم المطلوبة هي فئات تسمح بإضافات مستقبلية مثل المصادقة باستخدام شهادة بدلاً من اسم المستخدم/كلمة المرور.

check_mode

القيمة الافتراضية هي False، مرر True للإرجاع وعدم إجراء تغيير. سيتم تعيين علامة "changed" على True إذا تم اكتشاف تغييرات.

force

القيمة الافتراضية هي False، مرر True لتجاوز منطق التماثل.

معاملات أخرى

ستطابق المعاملات الأخرى توثيق REST API حرفيًا. كان الهدف هو الرجوع إلى توثيق REST API وعدم الحاجة إلى تكراره. يُرجى الرجوع إلى توثيق REST API للحصول على التفاصيل.

الإضافة وإجراء التغييرات

يُرجى فتح issue في github عند اكتشاف خطأ أو وجود REST APIs لا تغطيها هذه الحزمة. قدّم ملاحظات مفصلة مع سجلات التتبع عند الإبلاغ عن خطأ.

الترخيص

محتويات هذا المستودع مفتوحة المصدر بموجب ترخيص Apache 2.0.

Copyright 2017 International Business Machines

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.