| Name | ibmsecurity JSON |
| Version |
2024.10.11.0
JSON |
| download |
| home_page | None |
| Summary | Idempotent functions for IBM Security Appliance REST APIs |
| upload_time | 2024-10-14 13:04:50 |
| maintainer | None |
| docs_url | None |
| author | IBM |
| requires_python | >=3.7 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# IBM Sample Code
This repository contains Python code to manage IBM Security Appliances using their respective REST APIs.
ISAM appliance has the most mature code.
Code for ISDS appliance is under development.
Code for ISVG appliance is brand new (tested with 10.0.1.0 and higher only).
## Requirements
Python v3.7 and above is required for this package.
The following Python Packages are required:
1. requests - for making REST API calls
2. PyYAML - for the sample code to work
3. jmespath - is required for sample code
The following Python Packages are optional:
1. cryptography - to perform action on certificates (used for idempotency in management_ssl_certificate)
2. python-dateutil - date utilities (used for idempotency in management_ssl_certificate)
Appliances need to have an ip address defined for their LMI. This may mean that appliances have had their initial setup
done with license acceptance.
## TLS verification enabled (v2024.4.5)
These changes are backwards compatible. We default to not verifying but always display a notice:
````markdown
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
````
To remediate this cert validation warning, consider the instructions below:
Correct usage:
If you have the cert on disk somewhere,
instantiate the ISAMAppliance with:
ISAMAppliance(…, verify=<path to cert>)
You can retrieve this from appliance using a command like:
openssl s_client -connect ${HOSTNAME}:${PORT} </dev/null 2>/dev/null | openssl x509 -outform pem > isamAppliance.pem
If the cert is already trusted in your Python environment,
instantiate the ISAMAppliance with:
ISAMAppliance(…, verify=True)
or set the environment variable: `IBMSECLIB_VERIFY_CONNECTION=true`
If you receive errors about the hostname not matching the certificate:
This might look like:
````
<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'
````
Ensure the hostname used when instantiating your ISAMAppliance matches the Subject Alternative Name of the cert.
Check with:
openssl x509 -in <cert-pem-file> -text
Example:
$ openssl x509 -in /path/to/appliance.pem -text
Certificate:
Data:
Version: 3 (0x2)
…
X509v3 Subject Alternative Name:
DNS:appliance.ibm.com
…
The following will generate errors:
ISAMAppliance(host=”192.168.42.111”, lmi_port=443, verify=/path/to/appliance.pem)
as host does not match the Subject Alternative Name.
Instead, use:
ISAMAppliance(host=”appliance.ibm.com”, lmi_port=443, verify=/path/to/appliance.pem)
## Versioning
This package uses a date for versioning. For example: "2017.03.18.0"
It is the date when the package is released with a sequence number at the end to handle when there are
multiple releases in one day (expected to be uncommon).
## Features
This python package provides the following features:
1. Easy to use - the details of making a REST call are handled within an appliance class
2. Intuitive layout of code package and naming maps to the GUI interface of appliance
3. Idempotency - functions that make updates will query the appliance to compare given data to see if a
changes is required before making the actual change.
4. Commit and Deploy steps are provided separately to allow for flexibility in invoking them
5. Standard logging is included - with the ability to set logging levels.
6. Parameters to function will use standard default values wherever possible.
7. A force option is provided to override idempotency.
8. Compare functions are provided - takes JSON output and provide a meaningful comparison.
## Example Code
A sample `testisam.py` and `testisds.py` is provided. Provide details of your appliance and a user/password to authenticate.
Then call the functions needed. Run the code like you would any other Python script.
e.g.: `python testisam.py`
Note: the code requires PyYAML (for printing output in YAML) and importlib (dynamically load all packages) packages to work.
### Function Data Return Format
~~~~
{
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>
}
~~~~
Note: it is preferred to return warnings rather than send back a non-zero rc.
### Generic test script
For simple tests, a modified version is provided that takes the username, password, hostname, method and options as arguments, with the option to perform a commit or not.
This makes sense for simple tests but for pytest or unittests, this is not useful.
This avoids having to store credentials in a script and allows easier repeat of tests.
Example:
~~~~
python testisam_cmd.py --hostname 192.168.1.1 --method "ibmsecurity.isam.web.iag.export.features.get" --commit
~~~~
## Organization of code
### Appliance Classes
An abstract `ibmappliance` class is extended to create a class for each appliance supported here.
Currently that is ISAM and ISDS appliances.
### User Classes
An abstract `User` is extended for each type of user needed. For ISAM that is an user for appliance access
and another for authenticating to Web Runtime (Policy Server).
### Layout of ISAM packages
There are four primary ISAM packages - `base`, `web`, `aac` and `fed`. `web` contains all the components needed
for setting up the web functionality including embedded ldap, runtime and features that are activated as part of the
`wga` module. `aac` contains features activated as part of the `mga` module and `fed` that of `federation`. `base`
contains everything else - including `aac` and `fed` `runtime` and `Audit Configuration` (these are common to `aac` and `fed`
and thus in `base`).
### Package and File Names
The package and file names were created with the following intention:
1. Maintain names that match what is in the GUI interface (LMI for ISAM appliance).
2. Each file should contain just one of each function type (see list below) - i.e. just one add().
3. Group related function - one of each type - in a file.
4. The URI for the REST API calls with a file will be the same and manage a "feature" of the appliance.
### Utilities
Contains miscellaneous functions that are generic and independent of any IBM Appliance, e.g. `json_compare()`.
## Function Types
### `get_all()`
This function typically will return all objects related to that feature.
### `get()`
This function returns the details of one particular object.
### `set()`
This function will determine if the object to be manipulated exists, if not then it calls add() otherwise it will call update().
In cases where there is no update() then it will compare to see if there is a difference between existing value on the appliance
to that being set via the function - if different then it `delete()`'s the object before calling add().
### `add()`
Check and see if the object already exists - if so then skip, otherwise add it.
### `update()`
Check and see if the object already exists - if so then check if update is needed before making a change, otherwise do nothing.
### `delete()`
Check and see if the object already exists - if so then delete, otherwise do nothing.
### `import_<>()`
"import" is a reserved word, so there is a suffix to indicate what to import (e.g. file or key). This will check if the object exists
before importing it.
### `export_<>()`
Export will check if exists before exporting it - when exporting to a file, and the file already exists it will not re-export.
Export
### `compare()`
Compare takes JSON output from the get_all() functions and compares it. It will strip data from JSON that
are unique to each appliance (e.g. UUID values). The deleted_keys value returned lists the JSON keys that were deleted before comparison.
## Function Parameters
### Appliance object
Create an appliance object and pass it to the function. Appliance and the User object needed are classes to allow for
future extensions like authentication using certificate instead of username/password.
### `check_mode`
This defaults to False, pass True to return and not make a change. The "changed" flag will be set to True if changes are detected.
### `force`
This defaults to False, pass True to override the idempotency logic.
### Other Parameters
The other parameters will match the REST API documentation verbatim. The intention was to reference the REST API documentation
and not have to repeat it. Please reference REST API documentation for details.
## Adding and Making Changes
Please raise an issue in github when a bug is discovered or there are REST APIs not covered by this package.
Provide detailed notes along with trace logs when a bug is reported.
# License
The contents of this repository are open-source under the Apache 2.0 licence.
```
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.
```
Raw data
{
"_id": null,
"home_page": null,
"name": "ibmsecurity",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "IBM",
"author_email": "IBM <secorch@wwpdl.vnet.ibm.com>",
"download_url": "https://files.pythonhosted.org/packages/c4/bc/d52dff0bb7b4e61cabc821f94733187c2fe74e77a5177d5a9fadb29d2d7c/ibmsecurity-2024.10.11.0.tar.gz",
"platform": null,
"description": "# IBM Sample Code\n\nThis repository contains Python code to manage IBM Security Appliances using their respective REST APIs.\nISAM appliance has the most mature code.\n\nCode for ISDS appliance is under development.\n\nCode for ISVG appliance is brand new (tested with 10.0.1.0 and higher only).\n\n## Requirements\n\nPython v3.7 and above is required for this package.\n\nThe following Python Packages are required:\n1. requests - for making REST API calls\n2. PyYAML - for the sample code to work\n3. jmespath - is required for sample code\n\nThe following Python Packages are optional:\n1. cryptography - to perform action on certificates (used for idempotency in management_ssl_certificate)\n2. python-dateutil - date utilities (used for idempotency in management_ssl_certificate)\n\nAppliances need to have an ip address defined for their LMI. This may mean that appliances have had their initial setup\ndone with license acceptance.\n\n## TLS verification enabled (v2024.4.5)\n\nThese changes are backwards compatible. We default to not verifying but always display a notice:\n\n````markdown\nCertificate verification has been disabled. Python is NOT verifying the SSL\ncertificate of the host appliance and InsecureRequestWarning messages are\n\nbeing suppressed for the following host:\n\nhttps://{0}:{1}\n\nTo use certificate verification:\n\n1. When the certificate is trusted by your Python environment:\n Instantiate all instances of ISAMAppliance with verify=True or set\n the environment variable IBMSECLIB_VERIFY_CONNECTION=True.\n2. When the certificate is not already trusted in your Python environment:\n Instantiate all instances of ISAMAppliance with the verify parameter\n set to the fully qualified path to a CA bundle.\n\nSee the following URL for more details:\nhttps://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification\n````\nTo remediate this cert validation warning, consider the instructions below:\n\nCorrect usage:\n\nIf you have the cert on disk somewhere,\ninstantiate the ISAMAppliance with:\n\n ISAMAppliance(\u2026, verify=<path to cert>)\n\nYou can retrieve this from appliance using a command like:\n\n openssl s_client -connect ${HOSTNAME}:${PORT} </dev/null 2>/dev/null | openssl x509 -outform pem > isamAppliance.pem\n\nIf the cert is already trusted in your Python environment,\ninstantiate the ISAMAppliance with:\n\n ISAMAppliance(\u2026, verify=True)\n\nor set the environment variable: `IBMSECLIB_VERIFY_CONNECTION=true`\n\nIf you receive errors about the hostname not matching the certificate:\n\nThis might look like:\n````\n<stack trace>\n\n\u2026\n\n raise CertificateError(\"hostname %r doesn't match %r\" % (hostname, dnsnames[0]))\n\nurllib3.util.ssl_match_hostname.CertificateError: hostname '192.168.42.111' doesn't match 'appliance.ibm.com'\n\n````\n\nEnsure the hostname used when instantiating your ISAMAppliance matches the Subject Alternative Name of the cert.\n\nCheck with:\n\n openssl x509 -in <cert-pem-file> -text\n\nExample:\n\n $ openssl x509 -in /path/to/appliance.pem -text\n\nCertificate:\n\n Data:\n Version: 3 (0x2)\n \u2026\n X509v3 Subject Alternative Name:\n DNS:appliance.ibm.com\n\u2026\n\nThe following will generate errors:\n\n ISAMAppliance(host=\u201d192.168.42.111\u201d, lmi_port=443, verify=/path/to/appliance.pem)\n\nas host does not match the Subject Alternative Name.\nInstead, use:\n\n ISAMAppliance(host=\u201dappliance.ibm.com\u201d, lmi_port=443, verify=/path/to/appliance.pem)\n\n## Versioning\n\nThis package uses a date for versioning. For example: \"2017.03.18.0\"\n\nIt is the date when the package is released with a sequence number at the end to handle when there are\nmultiple releases in one day (expected to be uncommon).\n\n## Features\n\nThis python package provides the following features:\n1. Easy to use - the details of making a REST call are handled within an appliance class\n2. Intuitive layout of code package and naming maps to the GUI interface of appliance\n3. Idempotency - functions that make updates will query the appliance to compare given data to see if a\nchanges is required before making the actual change.\n4. Commit and Deploy steps are provided separately to allow for flexibility in invoking them\n5. Standard logging is included - with the ability to set logging levels.\n6. Parameters to function will use standard default values wherever possible.\n7. A force option is provided to override idempotency.\n8. Compare functions are provided - takes JSON output and provide a meaningful comparison.\n\n## Example Code\n\nA sample `testisam.py` and `testisds.py` is provided. Provide details of your appliance and a user/password to authenticate.\nThen call the functions needed. Run the code like you would any other Python script.\n\ne.g.: `python testisam.py`\n\nNote: the code requires PyYAML (for printing output in YAML) and importlib (dynamically load all packages) packages to work.\n\n### Function Data Return Format\n~~~~\n{\n rc: <0 for success, higher for errors>\n changed: <True or False>\n warnings: <List of strings with warnings - e.g. incompatible version>\n data: <JSON data returned by appliance REST API that the function called>\n}\n~~~~\n\nNote: it is preferred to return warnings rather than send back a non-zero rc.\n\n### Generic test script\n\nFor simple tests, a modified version is provided that takes the username, password, hostname, method and options as arguments, with the option to perform a commit or not.\nThis makes sense for simple tests but for pytest or unittests, this is not useful.\n\nThis avoids having to store credentials in a script and allows easier repeat of tests.\n\nExample:\n\n~~~~\npython testisam_cmd.py --hostname 192.168.1.1 --method \"ibmsecurity.isam.web.iag.export.features.get\" --commit\n~~~~\n\n## Organization of code\n\n### Appliance Classes\n\nAn abstract `ibmappliance` class is extended to create a class for each appliance supported here.\nCurrently that is ISAM and ISDS appliances.\n\n### User Classes\n\nAn abstract `User` is extended for each type of user needed. For ISAM that is an user for appliance access\n and another for authenticating to Web Runtime (Policy Server).\n\n### Layout of ISAM packages\n\nThere are four primary ISAM packages - `base`, `web`, `aac` and `fed`. `web` contains all the components needed\nfor setting up the web functionality including embedded ldap, runtime and features that are activated as part of the\n`wga` module. `aac` contains features activated as part of the `mga` module and `fed` that of `federation`. `base`\ncontains everything else - including `aac` and `fed` `runtime` and `Audit Configuration` (these are common to `aac` and `fed`\n and thus in `base`).\n\n### Package and File Names\n\nThe package and file names were created with the following intention:\n1. Maintain names that match what is in the GUI interface (LMI for ISAM appliance).\n2. Each file should contain just one of each function type (see list below) - i.e. just one add().\n3. Group related function - one of each type - in a file.\n4. The URI for the REST API calls with a file will be the same and manage a \"feature\" of the appliance.\n\n### Utilities\n\nContains miscellaneous functions that are generic and independent of any IBM Appliance, e.g. `json_compare()`.\n\n## Function Types\n\n### `get_all()`\nThis function typically will return all objects related to that feature.\n### `get()`\nThis function returns the details of one particular object.\n### `set()`\nThis function will determine if the object to be manipulated exists, if not then it calls add() otherwise it will call update().\nIn cases where there is no update() then it will compare to see if there is a difference between existing value on the appliance\nto that being set via the function - if different then it `delete()`'s the object before calling add().\n### `add()`\nCheck and see if the object already exists - if so then skip, otherwise add it.\n### `update()`\nCheck and see if the object already exists - if so then check if update is needed before making a change, otherwise do nothing.\n### `delete()`\nCheck and see if the object already exists - if so then delete, otherwise do nothing.\n### `import_<>()`\n\"import\" is a reserved word, so there is a suffix to indicate what to import (e.g. file or key). This will check if the object exists\nbefore importing it.\n### `export_<>()`\nExport will check if exists before exporting it - when exporting to a file, and the file already exists it will not re-export.\nExport\n### `compare()`\nCompare takes JSON output from the get_all() functions and compares it. It will strip data from JSON that\nare unique to each appliance (e.g. UUID values). The deleted_keys value returned lists the JSON keys that were deleted before comparison.\n\n## Function Parameters\n\n### Appliance object\nCreate an appliance object and pass it to the function. Appliance and the User object needed are classes to allow for\nfuture extensions like authentication using certificate instead of username/password.\n### `check_mode`\nThis defaults to False, pass True to return and not make a change. The \"changed\" flag will be set to True if changes are detected.\n### `force`\nThis defaults to False, pass True to override the idempotency logic.\n### Other Parameters\nThe other parameters will match the REST API documentation verbatim. The intention was to reference the REST API documentation\nand not have to repeat it. Please reference REST API documentation for details.\n\n## Adding and Making Changes\nPlease raise an issue in github when a bug is discovered or there are REST APIs not covered by this package.\nProvide detailed notes along with trace logs when a bug is reported.\n\n# License\n\nThe contents of this repository are open-source under the Apache 2.0 licence.\n\n```\nCopyright 2017 International Business Machines\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Idempotent functions for IBM Security Appliance REST APIs",
"version": "2024.10.11.0",
"project_urls": {
"Bug Tracker": "https://github.com/IBM-Security/ibmsecurity/issues",
"Homepage": "https://github.com/IBM-Security/ibmsecurity"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9608bd38b25c24fdb3c9399b9c43225da8437c53ad082e986ecadec4a157557d",
"md5": "846752edbab3f7a0576271718d279bc3",
"sha256": "4ba522d9793fd52370fe55a2da0fce51208d5c338742a84d9bf894e56f4ae95e"
},
"downloads": -1,
"filename": "ibmsecurity-2024.10.11.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "846752edbab3f7a0576271718d279bc3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 484870,
"upload_time": "2024-10-14T13:04:48",
"upload_time_iso_8601": "2024-10-14T13:04:48.610669Z",
"url": "https://files.pythonhosted.org/packages/96/08/bd38b25c24fdb3c9399b9c43225da8437c53ad082e986ecadec4a157557d/ibmsecurity-2024.10.11.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c4bcd52dff0bb7b4e61cabc821f94733187c2fe74e77a5177d5a9fadb29d2d7c",
"md5": "e8a1c7d30a7a4cee5ac91089e232376e",
"sha256": "114659fe3616230a4fa4050a9ec0a2fcb8b27440227830988e9d32d2c7c9dc7a"
},
"downloads": -1,
"filename": "ibmsecurity-2024.10.11.0.tar.gz",
"has_sig": false,
"md5_digest": "e8a1c7d30a7a4cee5ac91089e232376e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 263602,
"upload_time": "2024-10-14T13:04:50",
"upload_time_iso_8601": "2024-10-14T13:04:50.537483Z",
"url": "https://files.pythonhosted.org/packages/c4/bc/d52dff0bb7b4e61cabc821f94733187c2fe74e77a5177d5a9fadb29d2d7c/ibmsecurity-2024.10.11.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-14 13:04:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IBM-Security",
"github_project": "ibmsecurity",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ibmsecurity"
}
