Package: resilient-app-config-plugins
IBM SOAR App Config PluginsRelease NotesOverviewUsageCreating a Custom PluginEdge Gateway DeploymentLicense and TermsRelease Notesv1.0.0introducedresilient-app-config-plugins. This release included the built-in plugins for HashiCorp Vault, Cyberark, and Keyring.OverviewThis package (resilient-app-config-plugins) is a Python package for the base classes for App Config plugins. This package exposes built-in plugins, as well as the interface class that outlines how to implement custom plugins. App Config plugins allow you to use external credential providers (sometimes referred to here as PAMs) manage secrets. With App Config plugins, your secrets are managed by your provider and loaded only into memory on an as-need basis for your SOAR apps. Credentials are kept out of logs and never saved to disk.UsageSee the official IBM documentation for details on how to use each supported App Config plugin:ibm.biz/soar-docs.Creating a Custom PluginYou can create your own plugin to connectresilient-circuitsto any external credential provider that may not be built-in to theresilient-circuitsframework. To create a custom plugin, you'll need to create a custom implementation of this package. If you plan to deploy the app on the Edge Gateway, you will also require a custom docker registry from which your Edge Gateway machine is setup to pull from.Clone this repo to your local machine:git clone https://github.com/ibmresilient/resilient-python-api.gitOpen the repo in your favorite code editorNavigate to theresilient-app-config-plugins/resilient_app_config_pluginsdirectory and create a new.pyfile with the name of your PAM solution which you wish to integrate with.This Python file should expose a custom class, which implements the interface defined byresilient_app_config_plugins.plugin_base.PAMPluginInterface. That interface requires that you implement a constructor, aget()method, and aselftest()method. See one of the built-in plugins for details. The most important part is to implement theget()method to make a REST request out to the solution to retrieve the data affiliated with the value that you set for that config in your app.config file. The format which you use to reference values in the app.config is up to you.This Python file should expose a custom class, which implements the interface defined byresilient_app_config_plugins.plugin_base.PAMPluginInterface. That interface requires that you implement a constructor, aget()method, and aselftest()method. See one of the built-in plugins for details. The most important part is to implement theget()method to make a REST request out to the solution to retrieve the data affiliated with the value that you set for that config in your app.config file. The format which you use to reference values in the app.config is up to you.Note that there are a few conventions that we use which are exposed from the parent classPAMPluginInterface.PAM_VERIFY_SERVER_CERT: true, false or path to a certificate file for self-signed certs. Should be parsed withresilient_app_config_plugins.plugin_base.get_verify_from_string()to properly read the valuePAM_ADDRESS: address where the PAM endpoint is hostedPAM_APP_ID: ID needed to authenticate to endpoint with pluginExample:importrequestsfromresilient_app_config_plugins.plugin_baseimportPAMPluginInterfaceclassMyPlugin(PAMPluginInterface):def__init__(self,protected_secrets_manager,key,*args,**kwargs):"""here save the protected_secrets_manager and key variables if needed"""passdefget(self,plain_text_value,default=None):"""plain_text_value is the content of a ^-prefixed string from the app.config.parse the value as needed to reach out to your endpoint"""returnplain_text_valuedefselftest(self):"""return a tuple of a boolean and a stringwhere the boolean indicates whether or not theplugin is correctly configured and the stringis a reason for why it might not be correctly configured."""returnTrue,""Add the class to the__init__.pyfile at the root of the package. Exposing your class here is the key to allowing theresilientpackage to load your plugin:#!/usr/bin/env python# -*- coding: utf-8 -*-# (c) Copyright IBM Corp. 2023. All Rights Reserved.# All valid built-in PAM plugins must be defined and imported herefrom.cyberarkimportCyberarkfrom.hashicorpimportHashiCorpVaultfrom.keyringimportKeyringfrom.my_custom_plugimportMyPluginEdge Gateway DeploymentDeploying an app with a custom App Config plugin requires a custom Docker registry to which you can push and host app container images. This guide assumes your Docker registry is configured and your Edge Gateway is configured to pull from that registry.(Edge Gateway deployment only): To add the package to your container image, build the wheel for your custom implementation of theresilient-app-config-pluginspackage:cdresilient-app-config-plugins
pipinstallbuild
python-mbuild(Edge Gateway deployment only): For each app which you wish to include this custom plugin, download the source code from App Exchange. You will have to rebuild each app with the plugins included(Edge Gateway deployment only): Edit the Dockerfile so that the .whl file created bybuildis copied to the Docker image and installed with pip (NOTE: you first have to copy the .whl file to a location knowable by the Dockerfile, usually this is a folder calleddistwithin the app's package structure):COPY./dist/tmp/packagesRUNpipinstall/tmp/packages/resilient_app_config_plugins-*.whl(Edge Gateway deployment only): Repackage the app withresilient-sdk package:resilient-sdkpackage-p.--repository-name<reponame>(Edge Gateway deployment only): Rebuild the Docker image:dockerbuild.-t<dockerregistryaddress>/<reponame>/<appname>:<version>(Edge Gateway deployment only): When installing the app through the Edge Gateway, make sure to use the app's/dist/*.zipfile rather than the.zipfile found on app exchange as the custom one will contain your repository name.License and TermsCopyright © IBM Corporation 2023Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.