Enabling Custom Scripts

Overview

Custom scripts let you customize the way SecureChange reacts to the progress of tickets in a workflow. You can use various triggers that start external tasks based on the workflow progress or send information to external systems about ticket progress. For example, your custom script can collect ticket information and send it in an email message or save it to a file (see Using Scripts).

In TOS Aurora, the SecureChange service runs in a Kubernetes pod. Since Kubernetes pods do not retain changes upon restart, the ways that you interact with the TOS Aurora SecureChange pod are more limited than the flexibility required for custom scripts. Tufin has created the mediator script to use HTTP/HTTPS communication from the SecureChange pod to another location - either the TOS Aurora host or an external server. This removes the limitations of running custom scripts within a pod while maintaining the ability to use standalone executable scripts. The script will be executed by an external process at the operating system level, passing data to STDIN. This solution allows running the scripts on TOS Aurora similar to how they ran on TOS Classic.

To use this solution, you must:

  • Install the Tufin mediator script on the SecureChange pod.

  • Install the web service and the custom scripts (and their dependencies) in the same location, which could be on the TOS Aurora server or on an external server.

Who Should Use This Topic?

It is recommended that the Tufin system administrator, or a user with a similar skill-set, use this topic. The ideal user is someone who is comfortable with command-line Linux and scripting, and knows how services are created.

How Does It Work?

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 script passes this information to a web service that runs required customized scripts, and then passes the results back to the mediator script, which then passes the results to SecureChange.

For your reference, this link, https://gitlab.com/tufinps/tos2/trigger-example, contains example files including the mediator script and sample custom scripts.

If you have any questions about custom scripts and 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 the mediator script supports:

Important Notes

  • The mediator and web service scripts are working examples that are provided by Tufin as a courtesy. By downloading and using these scripts, you agree to take responsibility for implementation and maintenance

  • 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; this topic includes both options.

Enable Custom Scripts

Run this procedure on the server on which you will run the custom scripts (TOS Aurora or external).

  1. 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 -
  2. Navigate to your main working directory. The examples in this topic use /opt as the main working directory. You can select any directory, which you should use instead of /opt when following these procedures. 
    [<ADMIN> ~]# cd /opt
    cd /opt

  3. 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

  4. 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 && \
    deactivate
    cd trigger-service && \ python3 -m venv venv && \ source venv/bin/activate && \ pip3 install --upgrade pip &&\ pip3 install poetry && \ poetry install && \ deactivate

  5. At this point, you can continue custom script configuration on either a TOS Aurora server or on an external server.

    1. Create a file in the /etc/systemd/system directory called trigger.service. (In this example, we use the vi editor, but you can create it any way you like.)

      [<ADMIN> ~]# vi /etc/systemd/system/trigger.service
      vi /etc/systemd/system/trigger.service

      For example:

      [Unit]
Description=Tufin Trigger Service
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/trigger-service/
Environment=PATH=/opt/trigger-service/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
Environment=PYTHONPATH=/opt/trigger-service/venv/lib/python3.6/site-packages:/opt/trigger-service/venv/bin
Environment=KUBECONFIG=/etc/rancher/k3s/k3s.yaml
ExecStart=/opt/trigger-service/venv/bin/uvicorn trigger_proxy:app --host 0.0.0.0
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure

[Install]
WantedBy=multi-user.target
    2. Modify the following locations where you have the mediator script installed: (Note that in the example, the location is /opt/trigger-service.)
      • WorkingDirectory
      • Environment
      • ExecStart
    3. Save the trigger.service file.
    4. Change the file permissions. 
      [<ADMIN> ~]# chmod 644 /etc/systemd/system/trigger.service
      chmod 644 /etc/systemd/system/trigger.service

    5. Start the service.

      [<ADMIN> ~]# systemctl start trigger
      systemctl start trigger

    6. Enable service on boot.

      [<ADMIN> ~]# systemctl enable trigger 
      systemctl enable trigger

    7. Check the status.

      [<ADMIN> ~]# systemctl status trigger
      systemctl status trigger

    8. Modify the Mediator script (mediator.sh). In the following line, replace SCRIPT_HOST=192.168.40.73:8000 with the IP address of the web service:

      SCRIPT_HOST=192.168.40.73: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.

    9. 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.

    10. 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/

    1. Modify the mediator.sh file.
      • On line 4 in the mediator.sh file, replace the IP address with the IP address of the external server that will present the custom script. You must prepend https:// before the IP address:

        SCRIPT_HOST=https://<EXTERNAL_SERVER_IP>:8000

      • Replace line 6 with the following: 
        resp=$(curl --cacert /opt/tufin/data/securechange/scripts/rootCA.pem -sS --fail -X POST -u "user:pass"  -H "Content-Type: application/json" "$SCRIPT_HOST/trigger_file" -d \
        resp=$(curl --cacert /opt/tufin/data/securechange/scripts/rootCA.pem -sS --fail -X POST -u "user:pass" -H "Content-Type: application/json" "$SCRIPT_HOST/trigger_file" -d \

        • This code establishes trust between the SecureChange pod on the Aurora node and the external server that will present the certificate. When you push the cert to the SecureChange pod, the full path is sent to the pod.

        Alternatively, you can replace --cacert /opt/tufin/data/securechange/scripts/rootCA.pem with -k, which accepts any certificate but is not secure.

        Replace user:pass with the username/password that is required for basic authentication to the external server.

    2. Create a file in the /etc/systemd/system directory called trigger.service. (In this example, we use the vi editor, but you can create it any way you like.)

      [<ADMIN> ~]# vi /etc/systemd/system/trigger.service
      vi /etc/systemd/system/trigger.service

    3. Copy the following into the trigger.service file and replace ssl-keyfile and ssl-certfile with your key/cert pair.

      [Unit]
Description=Tufin Trigger Service
After=network.target

[Service]
Type=simple
WorkingDirectory=<WORKING_DIRECTORY>
Environment=PATH=/opt/trigger-service/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
ExecStart=<EXEC_START_DIRECTORY> trigger_proxy:app --host 0.0.0.0 --ssl-keyfile=<SSL_KEYFILE> --ssl-certfile=<SSL_CERTFILE>
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure

[Install]
WantedBy=multi-user.target

      where

      • <WORKING_DIRECTORY> and <EXEC_START_DIRECTORY> are the location where you installed the mediator script.

      • Environment: Change the path as required for your environment.

      • <SSL_KEYFILE> and <SSL_CERTFILE> are the SSL files that are saved in the directory under the <WORKING_DIRECTORY> and <EXEC_START_DIRECTORY> directories. For example:

        • ssl-keyfile=<WORKING_DIRECTORY>/ssl_cert/10.20.50.56-key.pem

        • ssl-certfile=<WORKING_DIRECTORY>/ssl_cert/10.20.50.56.pem

    4. Save the trigger.service file.
    5. Change the file permissions. 
      [<ADMIN> ~]# chmod 644 /etc/systemd/system/trigger.service
      chmod 644 /etc/systemd/system/trigger.service

    6. Start the service.

      [<ADMIN> ~]# systemctl start trigger
      systemctl start trigger

    7. Enable service on boot.

      [<ADMIN> ~]# systemctl enable trigger 
      systemctl enable trigger

    8. Check the status.

      [<ADMIN> ~]# systemctl status trigger
      systemctl status trigger

    9. 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.

    10. Copy the mediator.sh script and the rootCA.pem file to the Aurora data node. 

      [<ADMIN> ~]# scp mediator.sh rootCA.pem tufin-admin@<AURORA DATA NODE IP>:~
      scp mediator.sh rootCA.pem tufin-admin@<AURORA DATA NODE IP>:~

      The scp command copies the files from your external server to the /home/tufin-admin/ directory on the Aurora data node.

    11. Push the files to the SecureChange pod:

      [<ADMIN> ~]# tos scripts sc push mediator.sh
      tos scripts sc push mediator.sh
      [<ADMIN> ~]# tos scripts sc push rootCA.pem
      tos scripts sc push rootCA.pem

      The tos scripts sc commands place the files in the /opt/tufin/data/securechange/scripts/ directory on the SecureChange pod.

    12. On the external server, modify the trigger-service/trigger_proxy/_init_.py file as follows:

      1. On lines 68 and 69, change the username and password to match those in the mediator.sh file.

        • correct_username = secrets.compare_digest(credentials.username, "username")

        • correct_password = secrets.compare_digest(credentials.password, "password")

      2. On line 80, add a # to comment out the line:

        #@app.post("/trigger_file", dependencies=[Depends(ip_security)])

      3. On line 81, remove the # to uncomment the line:

        @app.post("/trigger_file", dependencies=[Depends(basic_auth)])

Configure 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 it. When SecureChange runs a script, it checks the following:

  • Is the Mediator Script defined?

  • Is the customized script to be run listed in the Mediator Script Allow list (whitelist in the API)?

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 that 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.

  1. 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

    Here is an example of the expected output:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <configuration_change>
        <key>webHookMediatorScriptFullPath</key>
        <new_value>/opt/tufin/data/securechange/scripts/mediator.sh</new_value>
    </configuration_change>

  2. 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=/opt/trigger-service/MyScript1.sh;/opt/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=/opt/trigger-service/MyScript1.sh;/opt/trigger-service/MyScript2.sh"

    where:

    • <user name> and <password> - SecureChange credentials for a user with Admin Privileges

    • <IP Address> – TOS VIP Address

    • /opt/trigger-service/MyScript1.sh;/opt/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 or in the external server.

    Here is an example of the expected output:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <configuration_change>
        <key>webHookMediatorScriptWhitelist</key>
        <new_value>/opt/trigger-service/MyScript1.sh;/opt/trigger-service/MyScript2.sh</new_value>
    </configuration_change>

    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?key=webHookMediatorScriptWhitelist"
    curl -k -X GET -u <user name>:<password> "https://<IP Address>/securechangeworkflow/api/securechange/internal/configuration/load?key=webHookMediatorScriptWhitelist"

  3. 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.

  4. In SecureChange, click Test to confirm that SecureChange is able to run the script.

Specify Script in SecureChange and Test

Now that the service is running, you can modify SecureChange to point to the full-path location of your custom script. In the following example, the full path is /opt/trigger-service/SecureChangeTestScript.sh.

After testing, you should also see a hit in the systemctl status trigger command: