IBM सैंपल कोड

इस रिपॉजिटरी में IBM सिक्योरिटी ऐप्लायंस को उनके संबंधित REST APIs का उपयोग करके प्रबंधित करने के लिए Python कोड शामिल है। ISAM ऐप्लायंस के लिए कोड सबसे परिपक्व है।

ISDS ऐप्लायंस के लिए कोड विकास के अधीन है।

ISVG ऐप्लायंस के लिए कोड बिल्कुल नया है (केवल 10.0.1.0 और उससे ऊपर के साथ परीक्षण किया गया)।

आवश्यकताएँ

इस पैकेज के लिए Python v3.9 और उससे ऊपर का संस्करण आवश्यक है।

निम्नलिखित Python पैकेज आवश्यक हैं:

1. requests - REST API कॉल करने के लिए
2. PyYAML - सैंपल कोड के काम करने के लिए
3. jmespath - सैंपल कोड के लिए आवश्यक है

निम्नलिखित Python पैकेज वैकल्पिक हैं:

1. cryptography - प्रमाणपत्रों पर कार्रवाई करने के लिए (management_ssl_certificate में idempotency के लिए उपयोग किया जाता है)
2. python-dateutil - दिनांक उपयोगिताएँ (management_ssl_certificate में idempotency के लिए उपयोग किया जाता है)

ऐप्लायंस के LMI के लिए एक IP पता परिभाषित होना आवश्यक है। इसका मतलब यह हो सकता है कि ऐप्लायंस की प्रारंभिक सेटअप लाइसेंस स्वीकृति के साथ की गई हो।

TLS सत्यापन सक्षम (v2024.4.5)

ये परिवर्तन पिछड़े-संगत (backwards compatible) हैं। हम डिफ़ॉल्ट रूप से सत्यापन नहीं करते हैं लेकिन हमेशा एक सूचना प्रदर्शित करते हैं:

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)

संस्करण (Versioning)

यह पैकेज संस्करण निर्धारण के लिए एक दिनांक का उपयोग करता है। उदाहरण के लिए: "2017.03.18.0"

यह वह दिनांक है जब पैकेज जारी किया जाता है, जिसके अंत में एक अनुक्रम संख्या होती है जो उस स्थिति को संभालने के लिए होती है जब एक ही दिन में कई रिलीज़ होती हैं (जिसके सामान्य होने की उम्मीद नहीं है)।

विशेषताएँ

यह Python पैकेज निम्नलिखित विशेषताएँ प्रदान करता है:

1. उपयोग में आसान - REST कॉल करने का विवरण एक ऐप्लायंस क्लास के भीतर संभाला जाता है
2. कोड पैकेज की सहज लेआउट और नामकरण ऐप्लायंस के GUI इंटरफ़ेस से मेल खाता है
3. Idempotency - अद्यतन करने वाले फ़ंक्शन वास्तविक परिवर्तन करने से पहले यह देखने के लिए ऐप्लायंस से क्वेरी करेंगे कि दिए गए डेटा में बदलाव आवश्यक है या नहीं।
4. Commit और Deploy चरण अलग-अलग प्रदान किए जाते हैं ताकि उन्हें बुलाने में लचीलापन रहे
5. मानक logging शामिल है - logging स्तर निर्धारित करने की क्षमता के साथ।
6. फ़ंक्शन के पैरामीटर जहाँ संभव हो मानक डिफ़ॉल्ट मानों का उपयोग करेंगे।
7. idempotency को ओवरराइड करने के लिए एक force विकल्प प्रदान किया गया है।
8. Compare फ़ंक्शन प्रदान किए गए हैं - 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 शामिल हैं (ये aac और fed दोनों के लिए सामान्य हैं और इसलिए base में हैं)।

पैकेज और फ़ाइल नाम

पैकेज और फ़ाइल नाम निम्नलिखित इरादे से बनाए गए थे:

1. ऐसे नाम बनाए रखें जो GUI इंटरफ़ेस (ISAM ऐप्लायंस के लिए LMI) में जो है उससे मेल खाते हों।
2. प्रत्येक फ़ाइल में प्रत्येक फ़ंक्शन प्रकार का केवल एक ही होना चाहिए (नीचे दी गई सूची देखें) - यानी केवल एक add()।
3. संबंधित फ़ंक्शन - प्रत्येक प्रकार का एक - एक फ़ाइल में समूहित करें।
4. किसी फ़ाइल में REST API कॉल के लिए URI समान होगा और ऐप्लायंस की एक "feature" का प्रबंधन करेगा।

उपयोगिताएँ

ऐसे विविध फ़ंक्शन शामिल हैं जो सामान्य हैं और किसी भी IBM ऐप्लायंस से स्वतंत्र हैं, जैसे json_compare()।

फ़ंक्शन प्रकार