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 शामिल हैं (ये और दोनों के लिए सामान्य हैं और इसलिए में हैं)।

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

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

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

उपयोगिताएँ

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

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

get_all()

यह फ़ंक्शन सामान्यतः उस सुविधा से संबंधित सभी ऑब्जेक्ट लौटाता है।

get()

यह फ़ंक्शन एक विशेष ऑब्जेक्ट का विवरण लौटाता है।

set()

यह फ़ंक्शन निर्धारित करेगा कि जिस ऑब्जेक्ट को संशोधित किया जाना है वह मौजूद है या नहीं, यदि नहीं तो यह add() को कॉल करता है अन्यथा यह update() को कॉल करेगा। ऐसे मामलों में जहां कोई update() नहीं है तो यह तुलना करेगा कि ऐप्लायंस पर मौजूदा मान और फ़ंक्शन के माध्यम से सेट किए जा रहे मान के बीच कोई अंतर है या नहीं - यदि अलग है तो यह add() को कॉल करने से पहले ऑब्जेक्ट को delete() करता है।

add()

जाँच करें कि ऑब्जेक्ट पहले से मौजूद है या नहीं - यदि हाँ तो छोड़ दें, अन्यथा इसे जोड़ें।

update()

जाँच करें कि ऑब्जेक्ट पहले से मौजूद है या नहीं - यदि हाँ तो परिवर्तन करने से पहले जाँचें कि अद्यतन आवश्यक है या नहीं, अन्यथा कुछ न करें।

delete()

जाँच करें कि ऑब्जेक्ट पहले से मौजूद है या नहीं - यदि हाँ तो हटाएँ, अन्यथा कुछ न करें।

import_<>()

"import" एक आरक्षित शब्द है, इसलिए यह इंगित करने के लिए एक प्रत्यय है कि क्या आयात करना है (जैसे फ़ाइल या कुंजी)। यह आयात करने से पहले जाँच करेगा कि ऑब्जेक्ट मौजूद है या नहीं।

export_<>()

Export निर्यात करने से पहले जाँच करेगा कि अस्तित्व है या नहीं - किसी फ़ाइल में निर्यात करते समय, यदि फ़ाइल पहले से मौजूद है तो यह पुनः निर्यात नहीं करेगा। Export

compare()

Compare get_all() फ़ंक्शन से JSON आउटपुट लेता है और उसकी तुलना करता है। यह JSON से उन डेटा को हटा देगा जो प्रत्येक ऐप्लायंस के लिए अद्वितीय हैं (जैसे UUID मान)। लौटाया गया deleted_keys मान उन JSON कुंजियों को सूचीबद्ध करता है जो तुलना से पहले हटाई गई थीं।

फ़ंक्शन पैरामीटर

ऐप्लायंस ऑब्जेक्ट

एक ऐप्लायंस ऑब्जेक्ट बनाएं और इसे फ़ंक्शन में पास करें। ऐप्लायंस और आवश्यक User ऑब्जेक्ट ऐसी क्लासेस हैं जो भविष्य के विस्तार की अनुमति देती हैं जैसे उपयोगकर्ता नाम/पासवर्ड के बजाय प्रमाणपत्र का उपयोग करके प्रमाणीकरण।

check_mode

यह डिफ़ॉल्ट रूप से False है, True पास करें ताकि लौटे और कोई परिवर्तन न करे। यदि परिवर्तन पाए जाते हैं तो "changed" फ़्लैग True पर सेट हो जाएगा।

force

यह डिफ़ॉल्ट रूप से False है, idempotency तर्क को ओवरराइड करने के लिए True पास करें।

अन्य पैरामीटर

अन्य पैरामीटर REST API दस्तावेज़ीकरण के अनुरूप होंगे। इरादा REST API दस्तावेज़ीकरण को संदर्भित करना था और इसे दोहराना नहीं था। विवरण के लिए कृपया REST API दस्तावेज़ीकरण देखें।

जोड़ना और परिवर्तन करना

कृपया github में एक issue दर्ज करें जब कोई बग खोजा जाए या ऐसे 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.