Expectations/Requirements: Python 3 is already installed
This guide is to be used for building development environments for using the Resilient API and creating integrations to increase automation of the platform.
Table of Contents
- Building a Virtual Environment for App Development
- Using the API
- Developing Apps
- Publishing and Using a Private Registry
- Install virtualenv for python:
pip install virtualenv
- Make a virtual environment root folder:
mkdir ~\.python_envs
- Create virtual environment:
virtualenv --python=python3 ~\.python_envs\<name_of_environment>
- Activate the virtual environment:
~\.python_envs\<name_of_environment\Scripts\activate
- (Windows Only) Enable Long Paths
-
Open gpedit.msc
-
Navigate to the NTFS Filesystem:
[Local Computer Policy\\Computer Configuration\\Administrative Templates\\System\\Filesystem]
-
Set "Enable Win32 long paths" to Enabled
- Install the Resilient Python Modules:
pip install resilient pip install resilient-circuits pip install resilient-sdk
- (Optional) Install modules for Testing:
pip install pytest-resilient-circuits pip install resilient-lib
- Configure Resilient-Circuits to run using the Python Virtual Environment
-
Navigate to the Virtual Environment version of Resilient-Circuits:
[~\.python_envs\<name_of_environment>\Lib\site-packages\resilient_circuits]
-
Edit app.py
-
Add the code below just under the imports at the very top:
os.environ["APP_CONFIG_FILE"] = r"C:\\.python_envs\\<name_of_environment>\\app.config"
-
Create the app.config file needed for authentication:
resilient-circuits config -c
-
Edit the Config file:
[~\.python_envs\<name_of_environment>\app.config]
- Add Server Name
- Add Authentication information
- Set log file location
- Add Resilient Cert Location OR Set cert to not be verified
- If using XDR Connect, set the STOMP URL and STOMP Port
-
Install Docker from Dockers Website
-
(Windows Only) Install Linux Kernal
-
Set Docker up for Use on CommandLine
-
Open Environment Variables
Shortcut: WIN + R
Type: systempropertiesadvanced
Click On: Environment Variables
-
Edit the System variables Path
-
Add a new entry with the Docker Install Location
(Default: C:\Program Files\Docker\Docker\resources)
-
-
Run Docker (as admin)
-
Start Python in Commandline:
python
-
Authenticating to Resilient
Method 1(Preferred):
- Import the Resilient Python Module:
import resilient
- Parse the config file:
parser = resilient.ArgumentParser(config_file=resilient.get_config_file()) opts = parser.parse_args()
- Create the Client (used to connect to Resilient):
client = resilient.get_client(opts)
Method 2:
- Import the Resilient Python Module:
import resilient
- Create the client (Must know org_name and Resilient_URL):
client = resilient.SimpleClient(org_name="<org_name>",base_url="<url_of_server>", proxies=<None | dict_of_proxies>, verify=<False | path_of_PEM_file>)
- Connect using User Email and Password:
client.connect('<username>','<password>')
- Import the Resilient Python Module:
-
Using the Client, start browsing the API.
Interactive API Help: <Resilient_URL>/docs/rest-api/ui/index.html
Basic API Help: <Resilient_URL>/docs/rest-api/index.html
Documentation on Resilient Client Options: https://ibmresilient.github.io/resilient-python-api/pages/resilient/resilient.html
- Using the client, use all kinds of http options: get,put,delete,patch,post,search
client.get(<uri>) client.put(<uri>, <payload_dict>) client.post(<uri>, <payload_dict>) client.delete(<uri>) client.get_put(<uri>, <function>)
KB for finfo: https://www.ibm.com/support/pages/rest-api
KB for Gadget: https://www.ibm.com/support/pages/rest-api
-
Build the Playbook/Workflow within Resilient before moving on.
IBM KB Detailing Playbook Design: https://www.ibm.com/docs/en/sqsp/48?topic=pdg-introduction
-
Use Resilient-SDK to generate base code by defining the internal parts of the app.
resilient-sdk codegen -p <name_of_package> -m <message_destination> -f <list_of_functions> -w <list_of_workflows> -s "<list_of_scripts>" -r "<list_of_rules>" -a <list_of_artifactTypes> -fd <list_of_fields> -d <list_of_dataTables> -t <list_of_tasks>
Note: If you change any of the internal parts within the Resilient Application for the app you already exported, use the script below to reload the codegen code.
resilient-sdk codegen -p ./<package_name> --reload
Note: If you need to add any new internal parts within the Resilient Application for the app, use the script below to reload the codegen code and add any new internal additions.
resilient-sdk codegen -p ./<package_name> --reload -f <list_of_functions> -w <list_of_workflows> <...etc>
-
Build the app from the code the generator layed out.
IBM KB Detailing Code: https://www.ibm.com/docs/en/sqsp/48?topic=guide-creating-app
-
Ensure that the config/setup files have been edited, including: docker, setup, and any other file that might need changes. If you created a user for testing, be sure to add that user to the message destination.
IBM KB Detailing Package Config Files: https://www.ibm.com/docs/en/sqsp/48?topic=guide-packaging-your-app
-
Install the integration in editable mode:
pip install -e ./<package_name>/
-
Run the code in
resilient-circuits
resilient-circuits run
-
If any adjustments in code are needed stop
resilient-circuits
usingCTRL+C
and then start re-run the command above. -
Once the code is working, gather the results from your testing using the following codegen command. This will be used in the app validation later.
resilient-sdk codegen -p ./<package_name> --gather-results <path_to_app.config>
-
Build the Docker Container
docker build ./<package_name> -t resilient/<package_name>:<version_number>
-
Run the Docker Container (must have a app.config file build for linux)
docker run -v <path_to_app.config>:/etc/rescircuits/app.config resilient/<package_name>:<version_number>
-
Now go into Resilient and ensure the app is functioning properly!
Note: If you make any changes to the code of your app, you will need to redo these instructions to rebuild the container
-
Generate the documentation files for your app using the code below:
resilient-sdk docgen -p ./<package_name>
-
Open the
README.md
file that is created in the root of the package. It is likely best to use software like Visual Studio Code that can display Markdown files. -
Find all of the
::CHANGE_ME::
comments in the document and update that line, then remove the comment. -
Any screenshots that are replaced or added should go in the
doc/screenshots
folder from the package root folder. -
Finally read over the documentation and make sure that it is covers everything you want it to cover. You can use a converter to change the final MD file into a PDF for submitting as documentation if you publish your app.
- Validate that the app is ready to package by running the the following command.
resilient-sdk validate -p ./<package_name>/ --validate
- The command above will generate a report both displayed in the commandline as well as new folder called
dist
in the package root folder with a copy of the report calledvalidate-report.md
. Either use the report in commandline or open the report file. - Look through the report and resolve any of the
Critical Issues
listed in the report. - Once the errors are resolved, package the App using the command below and create the final validation report that will be packaged with the app:
resilient-sdk package -p ./<package_name>/ --validate
- The final app to be used within SOAR will now be located in the
dist
folder with the report we used earlier.
Expectations/Requirements:
1. You already have a Private Registry:
- Github, Gitlab, or another public or private container registry.
2. You already have preferably 2 AppHosts installed and configured to your Resilient server.
Note: One will be for IBM Published apps and the other will be for your custom apps.
- Log into the private registry:
docker login <registry_url> -u <username>
- Tag the container for upload:
docker tag resilient/<package_name>:<version_number> <registry_path>/ibmresilient/<package_name>:<version_number>
- Push the container to the registry:
docker push <registry_path>/ibmresilient/<packages_name>:<version_number>
-
Log into a AppHost system.
-
Configure AppHost to use the private registries base URL to YOUR registry not just the domain. (ex. ghcr.io/theirgurus)
sudo manageAppHost registry --registry <registry_url> --user <username>
-
Restart the AppHost Box (I have found it easier to reboot vs restart services)
This AppHost will no longer allow IBM Published apps, that is why it is recommended to have 2 AppHost systems.
- Install the App within IBM SOAR
- Navigate to the Apps page within the Administrator Settings.
- From here, click the "Install" button
- Provide the entire zip file of the packaged app, and click "Upload".
- After completing the installation process, move on to the configuration steps.
- Configure the App by editing the app.config file on the "Configuration" tab.
- At the bottom of the tab, choose the Private AppHost before running the "Test Configuration".
- Once the test comes back successful, Click "Save and Push Changes".
- On the "Details" tab, Deploy the app.