Enabling Custom Scripts

Overview

In TOS Aurora, SecureChange runs custom-written scripts using the following mechanism. This applies both to scripts that were originally written for TOS Classic and new scripts written for TOS Aurora:

Set up:

The Tufin mediator script is installed on the SecureChange pod.
The web service is installed on a server outside the cluster.
The scripts and their dependencies are placed in the same location as the web service.

Run:

SecureChange calls the mediator script, which sends a request to the web service.
The web service runs the script and returns the result to the mediator, which returns it to SecureChange.

Tufin provides a template that you can use to write the mediator script. The mediator script gets custom script identifiers from SecureChange as well as ticket information attributes. The mediator passes this information to a web service that runs required customized scripts, and then passes the results back to the mediator, which then passes the results to SecureChange.

The example in this procedure provides step-by-step instructions to use the sample mediator and web service to run a script outside the TOS cluster. This example assumes that the web service and the scripts are installed and run on the same host as the TOS cluster.

Example files are available at https://gitlab.com/tufinps/tos2/trigger-example

If you have any questions about the migration process from TOS Classic to TOS Aurora, you can send a question in the Tufin Developer community in the Aurora Migration category.

Trigger Types

There are several types of scripts triggers in SecureChange. This list includes some of the trigger types that are supported by the mediator.

Workflow event triggers, as configured in Settings > SecureChange API
Scripted conditions for skip steps
Scripted condition for dynamic assignment
Pre-assignment scripts
Dynamic assignments by scripted tasks
External risk analysis

Enabling Custom Scripts

Get root privileges.

Either use your own password,
```
[[<ADMIN> ~]$]$ sudo su -
```
sudo su -
or use the root password (RHEL/Rocky Linux only),
```
[[<ADMIN> ~]$]$ su -
```
su -
On a node in the cluster in your desired directory, clone the sample mediator script and related files:
```
[<ADMIN> ~]# mkdir -p trigger-service && curl "https://gitlab.com/api/v4/projects/tufinps%2Ftos2%2Ftrigger-example/repository/archive.tar.gz" | tar -zx -C trigger-service --strip-components 1
```
mkdir -p trigger-service && curl "https://gitlab.com/api/v4/projects/tufinps%2Ftos2%2Ftrigger-example/repository/archive.tar.gz" | tar -zx -C trigger-service --strip-components 1
Run the following to set up Python and Poetry in the required directory.
```
[<ADMIN> ~]# cd trigger-service && \
python3 -m venv venv && \
source venv/bin/activate && \
pip3 install --upgrade pip &&\
pip3 install poetry && \
poetry install
```
cd trigger-service && \ python3 -m venv venv && \ source venv/bin/activate && \ pip3 install --upgrade pip &&\ pip3 install poetry && \ poetry install
Start the web service in a Screen session.
```
[<ADMIN> ~]# screen -S customscript
```
screen -S customscript
```
[<ADMIN> ~]# poetry run uvicorn trigger_proxy:app --reload --host 0.0.0.0
```
poetry run uvicorn trigger_proxy:app --reload --host 0.0.0.0
Modify the Mediator script (mediator.sh). In the following line, replace SCRIPT_HOST=10.20.51.230:8000 with the IP address of the web service:
```
SCRIPT_HOST=10.20.51.230:8000
```
- For a deployment without high availability (HA), use the IP address of assigned to a node in the cluster, which is the IP address you would use to SSH to the server. It is not the VIP used in the TOS interface.
- For an HA deployment, use the IP address of the cni0 interface from the server running the trigger proxy.
  
  To get the IP address:
```
[<ADMIN> ~]# ip -4 addr show cni0 | grep -oP "(?<=inet )[\d\.]+(?=/)"
```
  ip -4 addr show cni0 | grep -oP "(?<=inet )[\d\.]+(?=/)"
  Set the SCRIPT_HOST to the returned IP address:
```
[<ADMIN> ~]# set SCRIPT_HOST=<IP>
```
  set SCRIPT_HOST=<IP>
  where <IP> is the IP address.
Place your custom SecureChange scripts, together with all dependencies and resources, on a node in the cluster in the directory or subdirectory that contains the web service. Make sure that the web service has permissions to run the scripts.
Copy the script to the SecureChange pod:
```
[<ADMIN> ~]# tos scripts sc push mediator.sh
```
tos scripts sc push mediator.sh
This command places the script in the following directory on the internal SecureChange pod.
```
[<ADMIN> ~]# /opt/tufin/data/securechange/scripts/
```
/opt/tufin/data/securechange/scripts/

Configuring the SecureChange Engine to Run Custom Scripts

To run custom scripts in SecureChange with the Mediator Script, you need to define the path to the Mediator Script and create a list of scripts that should be run with the Mediator Script. When SecureChange runs a script, it checks the following:

Is the Mediator Script defined
Is the customized script to be run listed in the white list

If both of these criteria are met, SecureChange runs the mediator script path and passes the script-to-be-run identifier as an argument. The Mediator Script, in turn, issues a web call to a server which implements the logic of the script.

If either of these criteria are not met, SecureChange runs the script on its path in the same way that the script would have run in TOS Classic.

To define where the mediator is installed on the pod:
```
[<ADMIN> ~]# curl -k -X PUT -u <user name>:<password> "https://<IP Address>/securechangeworkflow/api/securechange/internal/configuration/set?insert=true&key=webHookMediatorScriptFullPath&value=/opt/tufin/data/securechange/scripts/mediator.sh"
```
curl -k -X PUT -u <user name>:<password> "https://<IP Address>/securechangeworkflow/api/securechange/internal/configuration/set?insert=true&key=webHookMediatorScriptFullPath&value=/opt/tufin/data/securechange/scripts/mediator.sh"
where:
- <user name> and <password> – SecureChange credentials for a user with Admin privileges
- <IP Address> – TOS VIP Address
Configure the script in SecureChange. For example, if the script is for a Workflow event, configure as follows:
1. In SecureChange, select Settings > SecureChange API.
2. In the Full Path field enter the full path where the script resides on the host outside the TOS cluster.
  
  The full path for the script is the full path where the script is located. The web service should be installed in the same common path.
Register the scripts:
```
[<ADMIN> ~]# curl -k -X PUT -u <user name>:<password> "https://<IP Address>/securechangeworkflow/api/securechange/internal/configuration/set?insert=true&key=webHookMediatorScriptWhitelist&value=/home/tufin-admin/trigger-service/MyScript1.sh;/home/tufin-admin/trigger-service/MyScript2.sh"
```
curl -k -X PUT -u <user name>:<password> "https://<IP Address>/securechangeworkflow/api/securechange/internal/configuration/set?insert=true&key=webHookMediatorScriptWhitelist&value=/home/tufin-admin/trigger-service/MyScript1.sh;/home/tufin-admin/trigger-service/MyScript2.sh"
where:
- <user name> and <password> - SecureChange credentials for a user with Admin Privileges
- <IP Address> – TOS VIP Address
- /home/tufin-admin/trigger-service/MyScript1.sh;/home/tufin-admin/trigger-service/MyScript2.sh - Script identifiers, multiple values are separated by a semicolon (;). The value must correspond with the value in the Full Path field of the script in SecureChange.
If the parameter is missing or has no value, SecureChange will use the Path field for the triggered script, and will not use the mediator script. SecureChange can work in hybrid mode, some scripts can be run locally, while some scripts are run externally by the mediator script.

If you want to retrieve the current settings and modify them, use this command:
```
[<ADMIN> ~]# curl -k -X GET -u <user name>:<password> "https://<IP Address>/securechangeworkflow/api/securechange/internal/configuration/load?insert=true&key=webHookMediatorScriptWhitelist"
```
curl -k -X GET -u <user name>:<password> "https://<IP Address>/securechangeworkflow/api/securechange/internal/configuration/load?insert=true&key=webHookMediatorScriptWhitelist"
In SecureChange, click Test to confirm that SecureChange is able to run the script.

Important Notes

The mediator and web service scripts are working examples are provided by Tufin as a courtesy. By downloading and using these scripts you agree to take responsibility for implementation and maintenance.
You are responsible to make sure that the web service is up and running at all times.
The host where the web service is installed must have an Internet connection when the web service is installed and the first time that the process is run.
The sample web service is designed to run on a node in the cluster, and will only respond to requests from the SecureChange pod using the Kubernetes library. These examples assume that the scripts are installed on the same host where TOS cluster runs.

If you prefer that the web service and customized scripts reside on different hosts, you should implement security measures such as encryption and authentication according to your organization's regulations.
Customized scripts will not be able to access the TOS database directly.
These scripts are intended to allow TOS-specific addons only. Scripts should be designed to utilize the TOS APIs or web service to interact with the software.
Customized scripts should not impede the performance or functionality of TOS. If Tufin Support provides assistance with troubleshooting or performance issues, you may be asked to disable custom scripts as part of the troubleshooting process.
On high availability (HA) deployments, the web service should be installed on a data node.
You can install this solution on a node in the cluster or a separate external server; however, the examples in this topic are for a node in the cluster.