SecureChange Custom Scripts

Overview

Custom scripts are files of code containing business logic that can run at various stages of the SecureChange ticket lifecycle. The scripts can be written by any programmer with the required skills; alternatively, they can be provided by Tufin Professional Services. For a quotation, contact your account manager. The scripts receive the ticket details from SecureChange, which they can use to run TOS APIs and/or pass information to external systems; they have no format requirements. Any number of custom scripts can be integrated into workflows.

Custom scripts can be written in any programming language, and must be installed on the TOS Aurora host outside the cluster or on an external host.

Custom scripts can be invoked following a specific workflow event such as closing a ticket or moving from one ticket step to the next. These events are called triggers.

Every custom script requires a matching mediator script, the purpose of which is to communicate between SecureChange and the custom script. The mediator script contains no business logic, must be written in a fixed format, and must be uploaded to TOS Aurora. SecureChange calls the mediator script, which sends an XML payload to the web server. This payload is used as input to the custom script.

Mediator Scripts

The mediator script must be uploaded to TOS using the command sudo tos scripts sc push. When triggered by a SecureChange event, it sends a request to the web server to run its matching custom script. You must create a unique mediator script for every custom script.

Mediator Script Types

There are different types of mediator scripts - each with a different syntax.

Type	Expects Return Code	Expects XML Script
Workflow event triggers, as configured in Settings > SecureChange API
External risk analysis
Ticket validation script
Assignment mode: Skip assignment step
Dynamic assignment
Assignment mode: Pre-assignment scripts

Workflow Event Triggers

A script can run after a workflow event occurs. These events include:

Trigger	Action
Advance	Runs a script when a handled ticket has advanced to a new step on the specified workflow.
Automatic step failed	Runs a script when an automatic step has failed in a ticket.
Create	Runs a script when a ticket is created.
Close	Runs a script when a ticket is closed.
Cancel	Runs a script when a ticket is canceled.
Redo	Runs a script when a handler of a ticket has returned to an earlier step on a specified workflow.
Reject	Runs a script when a ticket is rejected.
Reopen	Runs a script when the requester reopens a ticket after the handlers have completed their tasks.
Resolve	Runs a script when all handlers have completed their tasks and is pending confirmation by the requester.
Resubmit	Runs a script when an expired ticket is resubmitted.

XML Input to the Custom Script

When invoked, SecureChange passes ticket information to the mediator script in XML format containing the following attributes:

completion_step_id
completion_step_name
createDate
current_stage_id
current_stage_name
id
open_request_id
open_request_name
subject
updateDate

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ticket_info>
  <id>64</id>
  <subject>test_mediator_tutorial</subject>
  <priority>
    <id>3</id>
    <name>Normal</name>
  </priority>
  <createDate>1704707276656</createDate>
  <updateDate>1704707524268</updateDate>
  <requester>
    <id>4</id>
    <login>api</login>
    <display_name>api api</display_name>
  </requester>
  <current_stage>
    <id>253</id>
    <name>test_mediator</name>
    <ticket_task>
      <id>253</id>
      <name>Default</name>
      <handler>
        <id>4</id>
        <login>api</login>
        <display_name>api api</display_name>
      </handler>
    </ticket_task>
  </current_stage>
  <open_request_stage>
    <id>252</id>
    <name>Open request</name>
    <ticket_task>
      <id>252</id>
      <name>Default</name>
      <handler>
        <id>4</id>
        <login>api</login>
        <display_name>api api</display_name>
      </handler>
    </ticket_task>
  </open_request_stage>
  <comment xsi:type="RedoCommentType" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <content>test</content>
    <user>
      <id>4</id>
      <login>api</login>
      <display_name>api api</display_name>
    </user>
  </comment>
</ticket_info>

Implementing your Custom Script

These are the steps to implement a mediator script. Each step includes sample code.

Create the web server that will be used to run your custom scripts (see Custom Scripting Solution).

Write a custom script.

You can create your custom scripts in any programming language.

TOS Aurora users can use Pytos 2 (a Python package) to create scripts. This package, which the Tufin Professional Services team maintains, contains common SecureTrack, SecureChange, and GraphQL API calls. You can find the package repository here: https://gitlab.com/tufinps/pytos2-ce

Here is a tutorial that explains how to use pytos2: https://gitlab.com/tufinps/pytos2-ce/-/blob/master/docs/Basic%20Usage.ipynb?ref_type=heads

Here is an example of a custom script that updates field values in a ticket.

#!/usr/bin/env python3

import asyncio
from datetime import datetime
import json
from os import getenv
from sys import stdin
from xml.etree.ElementTree import fromstring

import httpx
from pydantic import AnyUrl, BaseSettings


class Settings(BaseSettings):
    securechange_url: AnyUrl = "https://user:password@localhost/securechangeworkflow/api/securechange"  # type: ignore

    class Config:
        # .env file overrides
        env_file = ".env"
        env_file_encoding = "utf-8"


settings = Settings()


async def get_ticket(ticket_id):
    async with httpx.AsyncClient(
        base_url=settings.securechange_url, verify=False, timeout=30
    ) as client:
        res = await client.get(f"/tickets/{ticket_id}.json")
        res.raise_for_status()
        ticket_json = res.json()
        return ticket_json


async def update_field(ticket, field_name, value):
    ticket_id = ticket["ticket"]["id"]
    current_step = ticket["ticket"]["steps"]["step"][-1]
    current_task = current_step["tasks"]["task"]
    x = [f for f in current_task["fields"]["field"] if f["name"] == field_name]
    field = x[0] if len(x) > 0 else None
    if not field:
        return None
    field["reason"] = value
    put_field_url = f"/tickets/{ticket_id}/steps/{current_step['id']}/tasks/{current_task['id']}/fields/"
    async with httpx.AsyncClient(
        base_url=settings.securechange_url,
        verify=False,
        timeout=30,
        headers={"Accept": "application/json"},
    ) as client:
        return await client.put(
            put_field_url,
            json={"fields": {"field": [field]}},
        )


async def process(ticket_id, previous_step):
    ticket = await get_ticket(ticket_id)
    if previous_step != ticket["ticket"]["steps"]["step"][-2]["name"]:
        print("Ticket is no longer at the expected step")
    res = await update_field(
        ticket,
        "Approve Access Request",
        "newval" + str(datetime.now()),
    )
    print(res.text if res else "no field match")
    if res and not res.is_error:
        print("Successfully updated field")
    return res


async def run_from_stdin():
    scw_event = getenv("SCW_EVENT")
    if scw_event == "ADVANCE":
        ticket_info = stdin.read()

        ticket_info_xml = fromstring(ticket_info)

        # Parse the ticket id
        x = ticket_info_xml.find("id")
        ticket_id = x.text if x is not None else None

        # parse the previous step
        previous_stage = ticket_info_xml.find("current_stage")
        x = previous_stage.find("name")
        previous_step_name = (
            (x.text if x is not None else None) if previous_stage else None
        )
        return await process(ticket_id, previous_step_name)


if __name__ == "__main__":
    loop = asyncio.get_event_loop()
    loop.run_until_complete(run_from_stdin())
    # asyncio.run(run_from_stdin())

These scripts are intended to allow TOS Aurora-specific addons only. Scripts should be designed to utilize the TOS Aurora APIs or web service to interact with the software.
Scripts should not impede the performance or functionality of TOS Aurora. If Tufin Support provides assistance with troubleshooting or performance issues, you may be asked to disable scripts as part of the troubleshooting process.

Create the mediator script.

From this template, replacing <hostname>, <endpoint>,<user-name>, <password>, and <script_name> with values that define the path and location of its matching custom script.

#! /bin/bash

ARGS=($@)
TICKET_INFO=$(cat | base64 -w0)

# User hardcoded arguments 
HOST=<hostname>
ENDPOINT=<endpoint>
USERNAME=<user-name>
PASSWORD=<password>
EXEC_SCRIPT=<script_name>

#all additional arguments taken from SC
EXEC_ARGS=${ARGS[@]:1}

# define the payload to send to your webserver
PAYLOAD="{ \
  \"ticket_info\":\"${TICKET_INFO}\",
  \"event\":\"${SCW_EVENT}\",
  \"script\": { \
    \"name\": \"${EXEC_SCRIPT}\",
    \"argv\": \"${EXEC_ARGS}\"
  }
}"

RESP=$(curl -sS --fail -X POST -u "${USERNAME}:${PASSWORD}" "${HOST}/${ENDPOINT}" \
    -H "Content-Type: application/json" \
    -d "${PAYLOAD}" 2>&1)

HTTP_EXT_CODE=$?
[ $HTTP_EXT_CODE -ne 0 ] && \
    echo $RESP > /dev/stderr && exit $HTTP_EXT_CODE 

export RESP

# parse the response json in python, the schema may differ from
# server to server implementation
python -c "
import os, sys, json

p = json.loads(os.getenv('RESP') or {})
stdout = p.get('stdout', '')
stderr = p.get('stderr', '')
message = p.get('message', '')
ext_code = p.get('ext_code', 0)

sys.stdout.write(message)
sys.stdout.write(stdout)

if ext_code != 0:
  sys.stderr.write(stderr)
exit(ext_code)
"

Upload the mediator script.

Upload to TOS Aurora; it is placed in /opt/tufin/data/securechange/scripts/.

Push Mediator

[<ADMIN> ~]$ sudo tos scripts sc push <path on local host> <relative path on SecureChange> [--overwrite]

Verify that the Mediator is in the correct location

[<ADMIN> ~]$ sudo tos scripts sc list [relative path on SecureChange] [--detailed]

Set up the web server.
Configure the web server to run your custom scripts. They can run either on your TOS Aurora server outside the cluster or on a different server altogether. Select one:

Test the mediator trigger.

Note that this procedure is only relevant for pure bash scripts that do not depend on any other library or infrastructure.

Log into SecureChange using API account.
Go to: Settings > SecureChange API
Click: Add script
Enter the full path to the script, for example:

/opt/tufin/data/securechange/scripts/mediator1.sh
Add any arguments that you want to pass to the script.
Click Test to make sure that SecureChange can run the script.
Select the SecureChange workflow that triggers the script.
Select the workflow events that trigger the script.
Click Save to save the script configuration.

Check the web server for the response.

data: {'ticket_info': 'PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/Pjx0aWNrZXRfaW5mbz48aWQ+NjQ8L2lkPjxzdWJqZWN0PnRlc3RfbWVkaWF0b3JfdHV0b3JpYWw8L3N1YmplY3Q+10.244.0.144 - - [08/Jan/2024 11:52:04] "POST /submit HTTP/1.1" 200 -

Decode base64 to xml to get ticket information.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ticket_info>
    <id>64</id>
    <subject>test_mediator_tutorial</subject>
    <priority>
        <id>3</id>
        <name>Normal</name>
    </priority>
    <createDate>1704707276656</createDate>
    <updateDate>1704707524268</updateDate>
    <requester>
        <id>4</id>
        <login>api</login>
        <display_name>api api</display_name>
    </requester>
    <current_stage>
        <id>253</id>
        <name>test_mediator</name>
        <ticket_task>
            <id>253</id>
            <name>Default</name>
            <handler>
                <id>4</id>
                <login>api</login>
                <display_name>api api</display_name>
            </handler>
        </ticket_task>
    </current_stage>
    <open_request_stage>
        <id>252</id>
        <name>Open request</name>
        <ticket_task>
            <id>252</id>
            <name>Default</name>
            <handler>
                <id>4</id>
                <login>api</login>
                <display_name>api api</display_name>
            </handler>
        </ticket_task>
    </open_request_stage>
    <comment xsi:type="RedoCommentType"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <content>test</content>
        <user>
            <id>4</id>
            <login>api</login>
            <display_name>api api</display_name>
        </user>
    </comment>
</ticket_info>

If SecureChange does not succeed in starting the script following a selected trigger, a message is added to Settings > Message Board

Resources

Tufin Developer Community: This site is useful if you have questions about Pytos2.
SecureTrack API
SecureChange API
GraphQL API
Examples

How do I Get Here?

SecureChange > Settings > SecureChange API