Developer's Guide

Version R19-1

For additional technical information, please see our support website, at:
[Link]
 Tufin Orchestration Suite (TOS) Developer's Guide

Contents

The TOS Developers Guide ..................................................... 4

Tufin Orchestration Suite (TOS) REST API ............................ 5

Getting Started with the TOS API .................................................................................... 5

SecureTrack REST API Resources .................................................................................. 8

Device and Revision Resources ..................................................................................... 8

Bindings: Attaching Rules to Firewalls .......................................................................... 15

Object IDs ..................................................................................................................... 16

Domains ....................................................................................................................... 16

REST API Overview ...................................................................................................... 17

SecureChange and SecureApp REST API Resources ................................................. 23

REST API OVerview ..................................................................................................... 23

API Best Practices .......................................................................................................... 27

General ......................................................................................................................... 27

Performance ................................................................................................................. 29

Response Time ............................................................................................................. 30

SecureTrack APG CLI ............................................................ 34

APG CLI Overview .......................................................................................................... 34

Consolidating Rules ....................................................................................................... 35

Collecting Log Files ........................................................................................................ 36

Getting Check Point Logs for Upload ............................................................................ 36

Getting Log Files for Upload.......................................................................................... 39

Tufin Knowledge Center: [Link]/support/kc 2

Tufin Orchestration Suite (TOS) Developer's Guide

Running APG CLI ............................................................................................................ 39

Customizing APG CLI Results ....................................................................................... 40

Tufin Open Platform (TOP) .................................................... 44

Introduction to TOP ........................................................................................................ 44

TOP Plugin Architecture................................................................................................ 45

Creating a TOP Plugin .................................................................................................... 45

Overview: High-Level Plugin Creation Procedure.......................................................... 45

Creating the top_manifest.xml File ................................................................................ 46

Creating the Data Retrieval Executable ........................................................................ 51

Creating the Readme File ............................................................................................. 52

Packaging the TOP Plugin ............................................................................................ 52

Testing the TOP Plugin .................................................................................................. 53

Validating the TOP Plugin ............................................................................................. 53

Installing a TOP Plugin.................................................................................................. 53

SecureChange API Scripts .................................................... 55

Example: Send Mail on Close ........................................................................................ 55

Sample Script File ........................................................................................................... 56

Sample XML Output ........................................................................................................ 58

SecureChange Inbound Mail ................................................. 61

Adding an Inbound Mailbox ........................................................................................... 62

Example: Opening a Request by Mail............................................................................ 63

Patents and Trademarks ........................................................ 65

Tufin Knowledge Center: [Link]/support/kc 3

 Tufin™ Orchestration Suite (TOS) Developer's Guide

The TOS Developers Guide Getting Started with the TOS API

Chapter 1

The TOS Developers Guide

Tufin Orchestration Suite™ (TOS) includes many application programming interface (APIs)
that you can use to customize the way you use SecureTrack™, SecureChange™ and
SecureApp™. These APIs let you integrate with other systems and build custom applications
that leverage Tufin's security policy orchestration capabilities.

For more about the APIs included in this guide, contact your sales representative or Tufin
Support ([Link]

Tufin Knowledge Center: [Link]/support/kc 4

 Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API Getting Started with the TOS API

Chapter 2

Tufin Orchestration Suite (TOS) REST

API

Getting Started with the TOS API

When you use the TOS API:

• You access a resource by sending an HTTP request to the TOS server. The server
replies with a response that either contains the data you requested, an HTTP status
indicator, or both.

• TOS APIs are organized by resources, as recommended by REST best practices. API
resources are located at:

SecureTrack [Link]

SecureChange [Link]
urechange/

SecureApp [Link]
app/

where <securetrack_ip>, <securechange_ip>, and <secureapp_ip> are the

IP address of the host server running TOS.

• You request a particular resource by appending a particular path to this base URL that
specifies the resource.

• Requests to the server must be sent over HTTPS, not HTTP.

• You must authenticate to the TOS server using HTTP basic access authentication with
a valid username and password. The permissions for the account you use for
authentication apply to your API request.

 SecureTrack - The user must be a RADIUS, LDAP or local SecureTrack user.

Authentication for the SecureTrack REST API via TACACS is available, if
SecureTrack is configured for TACACS authentication.
Tufin Knowledge Center: [Link]/support/kc 5
Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API Getting Started with the TOS API

 SecureChange and SecureApp - The user can be any user that has permissions for
the action that is done by the API call.

• You must specify the content-type header as either application/xml or

application/json.

• API Pagination is supported for many REST API calls that return large amounts of data,
making it easier for you to manage the results. If the API has the optional parameters
start and count, then pagination is supported for that API call.

 start (parameter) - zero-based, specifies the starting element to include in the

returned results

 count (parameter) - specifies the number of elements actually included in the

results

For example, if you wish to retrieve elements 51-60 in your results, set start = 50,
and count = 10.

The DTO for the results will contain a count and total field. Use these returned
values to determine how many paginated calls you will need to make to retrieve all the
desired results.

 count (DTO results field) - lists the actual number of elements included in the
returned results

 total (DTO results field) - lists the total number of elements available to be
included in the returned results

For example, if you set the start parameter to 120 and the total number of elements
from the search is 128, then the DTO results fields will be set as: total = 128 and
count = 8, because the returned results contain the last 8 elements of the total of
128 possible results.

• Access to TOS functionality via the REST API is determined by the specific
permissions granted to the username used for authentication, unless otherwise noted
explicitly otherwise for a specific API. For example if you run get_devices, the API
call will return only the devices you have permission to access. Additional information
about user permissions can be found at:

 Managing SecureTrack Users

Tufin Knowledge Center: [Link]/support/kc 6

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API Getting Started with the TOS API

 SecureChange Users and User Roles

• For security reasons, the OPTION http method is not supported. Supported REST API
methods will include: GET, POST, PUT, PATCH and DELETE.

Response Formats
For each resource, you can get the response in these formats:

• XML - add the .xml extension

The default response format is XML.

• JSON - add the .json extension

For R18-2 and above, TOS has started migrating APIs to use a new JSON marshaller. For
the APIs listed below, when returning a JSON list with a single element, the API passes the
element inside an array rather than as a single element. Source code will no longer have to
handle returned results differently depending on whether it is a single element or an array of
element. Strings like id of a device, that were previously returned as integers will now be
returned as a string containing the number surrounded with double quotes. Empty lists that
were previously omitted will now be included as empty arrays. The order in which the
properties appear in the returned JSON might be different from previous TOS versions.

(This change does not apply to returned XML data.) The change to the JSON returned data
applies to the following APIs:

• Get devices - [Link]

2/securetrack/apidoc/#!/Monitored_Devices/getDevices

• Get device by Id - [Link]

2/securetrack/apidoc/#!/Monitored_Devices/getDevice

• Add offline device - [Link]

2/securetrack/apidoc/#!/Monitored_Devices/addDevice

• Update offline device - [Link]

2/securetrack/apidoc/#!/Monitored_Devices/updateDevice

• Get rules by device - [Link]

2/securetrack/apidoc/#!/Security_Rules/getRules_0
Tufin Knowledge Center: [Link]/support/kc 7
Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

• Get specific rule -[Link]

2/securetrack/apidoc/#!/Security_Rules/getSpecificRules_0

• Rule Search APIs -

[Link]
2/securetrack/apidoc/#!/Security_Rules/findRulesOnDevices

[Link]
2/securetrack/apidoc/#!/Security_Rules/findRules

Additional Resources
The following additional REST API resources are available:

• Tufin REST API Getting Started github ([Link] page

Postman collections are available from the Tufin github page

• Tufin Developer Community ([Link]

SecureTrack REST API Resources

Some APIs, especially those that return large data sets, support the ability to define a partial
set of results (useful for large results sets) using the start and count parameters.

For example, to get only 10 revisions that start from revision 21, use:

[Link]
t=10

Device and Revision Resources

Some resources are associated with a device, for example, the rules resource. Retrieving a
resource through its device requires the device ID, which is available via the /devices API.
The following are the supported values for:

• vendor (see "supported vendors" on page 9)

• model (see "supported models" on page 10)

Tufin Knowledge Center: [Link]/support/kc 8

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

• virtual type (see "virtual type" on page 14)

Some resources are associated with a revision. This reflects SecureTrack’s ability to track
policy changes and store them as revisions. To retrieve a resource from a specific revision
you must provide the revision ID, which is available via the /devices/<device-
id>/revisions API.

supported vendors
The following values can be returned in the vendor field of the SecureTrack \devices
REST API.

• Amazon

• BlueCoat

• CheckPoint

• Cisco

• F5

• NewF5

• Stonesoft

• Fortinet

• Netscreen

• Azure

• Linux

• OpenStack

• PaloAltoNetworks

• VMware

• McAfee
Tufin Knowledge Center: [Link]/support/kc 9
Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

supported models
The following values can be returned in the modelfield of the SecureTrack \devices REST
API.

CheckPoint:
• cp_clm - Check Point CLM

• cp_mds - Check Point MDS

• cp_cma - Check Point CMA (R77 and below)

• cp_domain_r80plus - Check Point Domain (R80 and above)

• cp_smc_r80plus - Check Point SmartCenter (R80 and above)

• cp_mds_r80plus - Check Point MDS (R80 and above)

• cp_smrt_cntr - Check Point SmartCenter (R77 and below)

• module - Check Point Firewall

• module_cluster - Check Point Firewall cluster

Cisco:
• router - Cisco Router IOS

• xr_router - Cisco Router XR

• nexus - Cisco Nexus

• asa - Cisco ASA

• pix - Cisco PIX

• L3_switch - Cisco L3 Switch

• switch - Cisco L2 Switch

• fwsm - Cisco FWSM

Tufin Knowledge Center: [Link]/support/kc 10
Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

• csm - Cisco CSM device

• csm_asa - Cisco ASA which is being managed by CSM

• csm_fwsm - Cisco FWSM which is being managed by CSM

• csm_router - Cisco Router which is being managed by CSM

• csm_nexus - Cisco Nexus which is being managed by CSM

• csm_switch - Cisco Switch which is being managed by CSM

• fmc - Cisco FMC

• firepower - Cisco FirePower managed by the FMC

• fmc_domain - Domain under Cisco FMC

• aci - Cisco ACI

• aci_tenant - Cisco ACI tenant

Juniper:
• netscreen - Juniper Netscreen

• netscreen_cluster - Member of Netscreen cluster

• junos - Juniper SRX

• junosStateless - Juniper MX and M routers

• nsm - Juniper NSM

• nsm_device - Juniper SRX or MX which is being managed by NSM

• nsm_netscreen_isg - Juniper Netscreen which is being managed by NSM

Palo Alto:
• Panorama_ng - Palo Alto Panorama in advanced mode

Tufin Knowledge Center: [Link]/support/kc 11

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

• Panorama_device_group - Palo Alto Panorama Device Group

• Panorama_ng_fw - Palo Alto FW managed by Panorama in advanced mode

• Panorama - Palo Alto Panorama managed in basic mode

• PaloAltoFW - Palo Alto FW (managed as standalone)

• Panorama_device - Palo Alto FW managed under Panorama in basic mode

• Panorama_device_cluster - Palo Alto Cluster member managed under Panorama in

basic mode

Fortinet:
• fortimanager - Fortinet FortiManager in advanced mode (with ADOM)

• fmg_adom - Fortinet ADOM under FortiManager

• fmg_firewall - Fortinet firewall manged under FortiManager ADOM

• fmg - Fortinet FortiManager in basic mode

• fmg_vdom - Fortinet vdom under FortiManager in basic mode

• fmg_fw - Fortinet firewall under FortiManager in basic mode

• fmg_vdom_manager - Fortinet vdom manager under FortiManager basic mode

• fortigate - Fortinet firewall

Stonesoft:
• stonesoft_smc - Stonesoft Managament

• single_fw - Stonesoft Firewall

• master_engine - Stonesoft master engine

• virtual_fw - Stonesoft virtual firewall

• fw_cluster - Stonesoft cluster

Tufin Knowledge Center: [Link]/support/kc 12
Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

McAfee:
• mcafeeFW - McAfee Firewall

F5:
• bigip - F5 BigIP Top plugin

NewF5:
• new_bigip - F5 BigIP

BlueCoat:
• proxysg - BlueCoat ProxySG

Linux:
• iptables - Linux IPtables top plugin

VMware:
• nsx_manager - NSX manager

• nsx_fw - NSX distributed Firewall

• nsx_lrtr - NSX Logical Router

• nsx_edge - NSX Edge Firewall

Amazon:
• aws_manager - AWS Account

• aws_vpc - AWS VPC

Openstack:
• openStack_manager

• openStack_region

Tufin Knowledge Center: [Link]/support/kc 13

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

Azure:
• azure_rm_manager

• azure_rm_vnet

virtual type
The virtual_type field is returned in the DetailedDeviceDTO when the device is part of a
hierarchy. For example, all management devices are part of a hierarchy, where the
management device is the parent of the child firewall devices it manages.

If the device being returned via the GET API call is not part of a hierarchy, the
virtual_type field will be empty. If the device being returned via the GET API call is part of
a hierarchy, the virtual_type field will contain one of the following:

Value includes these Managed Device types

device ▪ Palo Alto Panorama with management mode = Basic firewall management
▪ Palo Alto PanOS with Virtual Systems
▪ Cisco ASA with Virtual Contexts
▪ Stonesoft SMC
▪ Juniper NSM
▪ F5 (not including devices using the TOP plugin)
▪ Fortinet FortiManager with management mode = Basic firewall management
▪ Fortinet FortiGate devices with virtual domains (VDOMs)
▪ Juniper SRX with logical system (LSYS)
▪ Microsoft Azure
▪ Cisco ACI
▪ OpenStack,
▪ Amazon AWS
▪ VMware NSX
▪ Cisco Security Manager (CSM)
management ▪ Fortinet FortiManager with management mode = Advanced management
▪ Palo Alto Panorama with management mode = Advanced management
▪ Cisco Firepower Management Center (FMC)
mdom ▪ Fortinet FortiManager with administrative domains (ADOMs)
▪ Cisco ACI tenant
▪ Palo Alto Panorama device group (DG)
▪ Cisco Firepower Management Center (FMC) domain

Tufin Knowledge Center: [Link]/support/kc 14

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

context ▪ Palo Alto PanOS virtual system (VSYS)

▪ Cisco ASA virtual context
▪ Forcepoint virtual engine
▪ Forcepoint firewall
▪ virtual domain (VDOM) or firewall managed by FortiManager administrative domain (ADOM)
▪ F5 partition
▪ Juniper SRX logical system (LSYS)
▪ Microsoft Azure VNET
▪ OpenStack project
▪ virtual system (VSYS) or firewall managed by Panorama device group (DG)
▪ NSX firewall and Edge Router
▪ firewall or virtual context managed by Cisco Security Manager (CSM)
▪ firewall managed by Cisco Firepower Management Center (FMC)
▪ AWS VPC
▪ firewall or logical system (LSYS) managed by Juniper NSM
vdom_manager ▪ Stonesoft Master Engine
▪ ASA with context managed by Cisco Security Manager (CSM) (does not include the context itself)
▪ Fortigate with virtual domain (VDOM) managed by FortiManager (does not include the vdom itself)
▪ PanOS with virtual system (VSYS) managed by Panorama (does not include the VSYS itself)
vt_standalone ▪ firewalls without virtual context managed by a Cisco CSM
▪ firewall without virtual system (VSYS) managed by Panorama in basic mode

vsx Check Point VSX firewall

vsx_switch Check Point VSX switch

vsx_bridged Check Point VSX bridge

vsx_box Check Point VSX

vsx_router Check Point VSX router

Bindings: Attaching Rules to Firewalls

Rules and ACLs are attached to firewalls and cloud platforms in different ways, depending on
the device type.

• Check Point rules are attached to a management server (SmartCenter or CMA)

through policies

Tufin Knowledge Center: [Link]/support/kc 15

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

• Cisco rules, also known as access control entries (ACEs), are attached to the firewall
itself or to a CSM through access lists (ACLs)

• Palo Alto, Fortinet, Juniper and Forcepoint (formerly McAfee) rules are attached to the
firewall itself (if monitored directly) or to a manager (such as Panorama, FortiManager,
NSM, SMC) through zone based policies

• AWS, Azure and OpenStack rules are attached to their platforms through Security
Groups

The collections of rules which are attached to devices are generally referred to as Bindings.
Rule resources will also have a bindings section, which describes how the rule is attached to
its management server or firewall.

Object IDs
REST resources are identified by their IDs. For example, /devices/<device-id>
identifies a specific device.

The ID of resources that are managed by TOS are persistent. For example, a device ID or a
ticket ID will not change once it has been created.

The ID of resources that are managed by the monitored devices (such as firewalls, routers, or
cloud platforms ) are not persistent, and may change each revision. For example, rule IDs
and network_object IDs are not persistent across revisions.

Domains
In some APIs, you can use the domain context parameter (context=2) to limit the results to
a specified SecureTrack domain.

For example, to get only the devices that are in domain 2, use:

[Link]

To find the domain ID, you can use the domains API to get a list of the domains.
Tufin Knowledge Center: [Link]/support/kc 16
Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

REST API Overview

Additional Policy Fields

Retrieve special field for firewall NAT Pools that are used by Fortinet.

This API is currently only supported for Palo Alto Networks firewalls and Fortinet devices
managed by FortiManager.

For complete details see Additional Policy Fields ([Link]

1/securetrack/apidoc/#!/Additional_Policy_Fields).

Application IDs
Retrieve information about Application Identities in Next-Generation firewalls. (For Palo Alto
Networks devices only.)

For complete details see Application IDs ([Link]

1/securetrack/apidoc/#!/Application_IDs).

Change Authorization
Identify changes that were not authorized by a SecureChange ticket.

For complete details see Change Authorization ([Link]

1/securetrack/apidoc/#!/Change_Authorization).

Device Interfaces and Zones

Retrieve information about network interfaces, routing tables, and security zones on devices.

For complete details see Device Interfaces and Zones

([Link]
1/securetrack/apidoc/#!/Device_Interfaces_and_Zones).

Domains
Manage SecureTrack domains. This is only relevant if multi-domain mode is enabled.

Tufin Knowledge Center: [Link]/support/kc 17

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

For complete details see Domains ([Link]

1/securetrack/apidoc/#!/Domains).

IPsec VPN
Retrieve information about VPN settings for supported device types. (For Check Point and
Cisco devices only.)

For complete details see IPsec VPN ([Link]

1/securetrack/apidoc/#!/IPsec_VPN).

Internet Objects
Manage the Internet object on devices that define this object.

For complete details see Internet Objects ([Link]

1/securetrack/apidoc/#!/Internet_Objects).

Review LDAP settings and search LDAP directory entries.

For complete details see LDAP ([Link]

1/securetrack/apidoc/#!/LDAP).

Monitored Devices
Manage the devices that are monitored in SecureTrack.

Adding devices is supported for offline devices only.

For complete details see Monitored Devices ([Link]

1/securetrack/apidoc/#!/Monitored_Devices).

NAT Policies
Retrieve NAT objects and rules for supported devices. Supported devices are Check Point,
Cisco, Juniper, Fortinet, Stonesoft.

For complete details see NAT Policies ([Link]

1/securetrack/apidoc/#!/NAT_Policies).

Tufin Knowledge Center: [Link]/support/kc 18

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

Network Objects
Retrieve network object data from devices.

For complete details see Network Objects ([Link]

1/securetrack/apidoc/#!/Network_Objects).

Network Topology
Retrieve network topology data from devices.

For complete details see Network Topology ([Link]

1/securetrack/apidoc/#!/Network_Topology).

Network Zone Manager - Patterns

Manage a set of text patterns, and then associate specific text patterns with SecureTrack
network zones. SecureTrack automatically associates all security groups where the name
matches the text patterns with the specified zones.

For complete details see Network Zone Manager - Patterns

([Link]
_Patterns).

Network Zone Manager - Subnets

Manage the subnets associated with SecureTrack network zones.

For complete details see Network Zone Manager - Subnets

([Link]
_Subnets).

Network Zone Manager - Zones

Manage SecureTrack zones. The zones are used to define security zone matrices for Unified
Security Policies.

For complete details see Network Zone Manager - Zones

([Link]
_Zones).

Tufin Knowledge Center: [Link]/support/kc 19

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

Policies and Sub-Policies

Retrieve information about bindings, including security policies, ACLs, zone-based policies,
and security groups.

For complete details see Policies and Sub-Policies ([Link]

1/securetrack/apidoc/#!/Policies_and_Sub-Policies).

Policy Analysis
Identify rules that correspond to traffic flows.

For complete details see Policy Analysis ([Link]

1/securetrack/apidoc/#!/Policy_Analysis).

Policy Optimization
Retrieve information about risky and sub-optimal policy configurations that can be cleaned
up.

For complete details see Policy Optimization ([Link]

1/securetrack/apidoc/#!/Policy_Optimization).

Revisions
Retrieve the historical policy revisions from a specific device.

For complete details see Revisions ([Link]

1/securetrack/apidoc/#!/Revisions).

Rule Documentation
Manage the rule metadata associated with a policy revision.

For complete details see Rule Documentation ([Link]

1/securetrack/apidoc/#!/Rule_Documentation).

Rule Usage
Retrieve information about last hit per rule, based on rule usage tracking that is monitored by
SecureTrack.

Tufin Knowledge Center: [Link]/support/kc 20

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

Retrieve information about last hit per user and application inside For Palo Alto Networks
rules.

For complete details see Rule Usage ([Link]

1/securetrack/apidoc/#!/Rule_Usage).

Security Rules
Retrieve security rules from both hardware devices and cloud platforms.

For complete details see Security Rules ([Link]

1/securetrack/apidoc/#!/Security_Rules).

Services and Ports

Retrieve the service definition (IP protocols and ports) from both hardware devices and cloud
policies.

For complete details see Services and Ports ([Link]

1/securetrack/apidoc/#!/Services_and_Ports).

Time Objects
Retrieve the time object definition from supported devices.

For complete details see Time Objects ([Link]

1/securetrack/apidoc/#!/Time_Objects).

Traffic Policy Matcher

Retrieve information about the details of an Amazon AWS policy that are relevant for
specified traffic.

For complete details see Traffic Policy Matcher ([Link]

1/securetrack/apidoc/#!/Traffic_Policy_Matcher).

Unified Security Policy - Access Request Violations

Retrieve the USP violations for an access request, in either synchronous or asynchronous
mode.

Tufin Knowledge Center: [Link]/support/kc 21

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureTrack REST API Resources

For complete details see Unified Security Policy - Access Request Violations
([Link]
1/securetrack/apidoc/#!/Unified_Security_Policy_Access_Request_Violations).

Unified Security Policy - Alerts

Manage your USP alerts.

For complete details see Unified Security Policy - Alerts

([Link]
_Alerts).

Unified Security Policy - Cloud Tag Policy

Retrieve information about policy definitions for Amazon AWS cloud tags.

For complete details see Unified Security Policy - Cloud Tag Policy
([Link]
_Cloud_Tag_Policy).

Unified Security Policy - Exceptions

Retrieve definitions of security zone exceptions.

For complete details see Unified Security Policy - Exceptions

([Link]
_Exceptions).

Unified Security Policy - Security Zone Matrix

Retrieve definitions of security zone matrices.

For complete details see Unified Security Policy - Security Zone Matrix
([Link]

Unified Security Policy - Violations

Retrieve information about firewall policies that violate security zone matrices.

Tufin Knowledge Center: [Link]/support/kc 22

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureChange and SecureApp REST API Resources

For complete details see Unified Security Policy - Violations

([Link]
_Violations).

SecureChange and SecureApp REST API Resources

To see documentation of the SecureChange and SecureApp REST APIs with your web
browser, go to: [Link]

REST API OVerview

Access Portal
Manage requests for application access from the SecureApp application access portal.

For complete details see Access Portal ([Link]

1/securechangeworkflow/apidoc/#!/Access_Portal).

Application Connections
Manage application connections in SecureApp.

For complete details see Application Connections ([Link]

1/securechangeworkflow/apidoc/#!/Application_Connections).

Application Identities
Retrieve list of Next Generation application identities that can be used in SecureApp
application connections and SecureChange access requests.

For complete details see Application Identities ([Link]

1/securechangeworkflow/apidoc/#!/Application_Identities).

Application Interfaces
Manage interfaces to SecureApp applications.

For complete details see Application Interfaces ([Link]

1/securechangeworkflow/apidoc/#!/Application_Interfaces).

Tufin Knowledge Center: [Link]/support/kc 23

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureChange and SecureApp REST API Resources

Application Migration
Copy (migrate) the application definitions to a new or existing application.

For complete details see Application Migration ([Link]

1/securechangeworkflow/apidoc/#!/Application_Migration).

Application Packs
Manage SecureApp application packs.

For complete details see Application Packs ([Link]

1/securechangeworkflow/apidoc/#!/Application_Packs).

Application Pending Changes

Retrieve pending application changes in SecureApp that are ready for ticket creation.

For complete details see Application Pending Changes

([Link]
1/securechangeworkflow/apidoc/#!/Application_Pending_Changes).

Application Servers (across all applications)

Retrieve servers across all SecureApp applications.

For complete details see Application Servers (across all applications)

([Link]
1/securechangeworkflow/apidoc/#!/Application_Servers_(across_all_applications)).

Application Servers (by application)

Manage servers for a specific SecureApp application.

For complete details see Application Servers (by application)

([Link]
1/securechangeworkflow/apidoc/#!/Application_Servers_(by_application)).

Application Services (global)

Manage global application services in SecureApp.

Tufin Knowledge Center: [Link]/support/kc 24

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureChange and SecureApp REST API Resources

For complete details see Application Services (global)

([Link]
1/securechangeworkflow/apidoc/#!/Application_Services_(global)).

Application Users
Manage application users in SecureApp.

For complete details see Application Users ([Link]

1/securechangeworkflow/apidoc/#!/Application_Users).

Applications
Manage SecureApp applications.

For complete details see Applications ([Link]

1/securechangeworkflow/apidoc/#!/Applications).

Cloud Console
Manage the SecureApp Cloud Console. The Cloud Console lets you view AWS instances
and associate them with SecureApp applications.

For complete details see Cloud Console ([Link]

1/securechangeworkflow/apidoc/#!/Cloud_Console).

Customers
Manage SecureApp customers. Customers are mapped to SecureApp domains.

For complete details see Customers ([Link]

1/securechangeworkflow/apidoc/#!/Customers).

Domains
Retrieve a listing of SecureTrack domains, which can be mapped to SecureApp domains.

For complete details see Domains ([Link]

1/securechangeworkflow/apidoc/#!/Domains).

Tufin Knowledge Center: [Link]/support/kc 25

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API SecureChange and SecureApp REST API Resources

Load Balancers
Retrieve a listing of F5 server pools that can be used in SecureApp connections.

For complete details see Load Balancers ([Link]

1/securechangeworkflow/apidoc/#!/Load_Balancers).

SecureChange Devices
Manage which devices will be used in SecureChange access requests.

For complete details see SecureChange Devices ([Link]

1/securechangeworkflow/apidoc/#!/SecureChange_Devices).

Server Decommissioning
Run and view the results of the automations tools available for server decommissioning.

For complete details see Servers Decommissioning ([Link]

1/securechangeworkflow/apidoc/#!/Servers_Decommissioning).

System Configuration
Configure the SecureTrack server and account used by SecureChange and SecureApp.

For complete details see System Configuration ([Link]

1/securechangeworkflow/apidoc/#!/System_Configuration).

System Users
Retrieve a listing of SecureChange and SecureApp users and user details.

For complete details see System Users ([Link]

1/securechangeworkflow/apidoc/#!/System_Users).

Ticket Lifecycle
Reassign tickets, redo ticket steps, and retrieve ticket history.

For complete details see Tickets Lifecycle ([Link]

1/securechangeworkflow/apidoc/#!/Tickets_Lifecycle).

Tufin Knowledge Center: [Link]/support/kc 26

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API API Best Practices

Tickets
Manage SecureChange tickets.

For complete details see Tickets ([Link]

1/securechangeworkflow/apidoc/#!/Tickets).

API Best Practices

The API Best Practices provides guidelines to help you use the Tufin REST APIs in the most
efficient and effective manner. Following the guidelines listed below will help ensure that your
application performs well, and safeguards all Tufin Orchestration Suite applications
(SecureTrack, SecureChange, and SecureApp) from performance degradations.

General
To ensure forward compatibility of your integration with Tufin Orchestration Suite we
recommend that you:

• Do not use unpublished APIs

• Do not directly access the internal PostgreSQL databases, for either retrieving or
modifying data

You should never embed authentication information into your applications.

Group Members
When you retrieve a single network_object element or a single services element of the type
group, the API response includes all the group members. This also occurs when you retrieve
a list of network_objects or services and restrict the returned type to group.

To make more efficient API calls, set the optional show_members = false: The call will
return only the names and IDs of the members.

show_members is available for the following APIs:

• Get network objects by device ([Link]

1/securetrack/apidoc/#!/Network_Objects/getNetworkObjects)

Tufin Knowledge Center: [Link]/support/kc 27

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API API Best Practices

• Get specific network object ([Link]

1/securetrack/apidoc/#!/Network_Objects/getSpecificNetworkObjects)

• Get network objects by revision ([Link]

1/securetrack/apidoc/#!/Network_Objects/getNetworkObjects_0)

• Get specific network objects by revision ([Link]

1/securetrack/apidoc/#!/Network_Objects/getSpecificNetworkObjects_0)

• Get services by device ([Link]

1/securetrack/apidoc/#!/Services_and_Ports/getServices_0)

• Get specific service ([Link]

1/securetrack/apidoc/#!/Services_and_Ports/getSpecificService)

• Get services by revision ([Link]

1/securetrack/apidoc/#!/Services_and_Ports/getServices)

• Get specific service by revision ([Link]

1/securetrack/apidoc/#!/Services_and_Ports/getSpecificService_0)

To maintain full backwards compatibility, the default value of the show_members parameter
is true.

Content Negotiation
Starting from R18-2, TOS is compliant with the REST API standard (JAX_RS) 2.1, which is
compliant with Java EE8
([Link] Compliance with the
updated standards requires supporting more strongly typed content negotiation in our REST
API. To prevent receiving HTTP error 415 (Unsupported Media Type) from the
server, the REST client must specify the correct Content-Type and the Java client must
provide the correct [Link].

Tufin Knowledge Center: [Link]/support/kc 28

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API API Best Practices

Performance

Data Retrieval Performance Considerations

Some APIs return large amounts of data, such as retrieving all tickets and retrieving Unified
Security Policy violations. When using APIs such as these, we recommend that you use
pagination wherever possible, rather than retrieving all the data in a single call. See the
pagination section in Getting Started with the TOS API (see "Getting Started with the TOS
API" on page 5) for additional details about pagination.

SecureTrack APIs that are used often that return large amounts of data include:

• Get Rules

• Get Network Objects

• Get USP violations - in devices with large amount of rules see Get Unified Security
Policy Violations

SecureChange APIs that are used often that return large amounts of data include:

• Get Tickets

• Get designer results

• Get ticket after few steps with tools results

Memory Resource Considerations

Excessive use of memory-intensive resources by APIs can cause substantial degradation in
system performance. Issues that may result include APIs returning the HTTP 500 error, and
the UI appearing frozen for users logged into the system. We recommend that you do not
make multiple parallel or concurrent calls to memory-intensive APIs.

If you are making many API calls serially that are data- or resource-intensive, we recommend
that you insert a 5-10 second sleep between the API calls.

To leverage the multi-core CPU on the server:

• If you use pagination, you can make up to 10 concurrent API calls on a single data
retrieval

Tufin Knowledge Center: [Link]/support/kc 29

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API API Best Practices

• If you are calling an API that returns a small amount of data (for example retrieving the
most recent policy revision on a device) you can make up to 10 concurrent API calls,
and retrieve the latest policy revision for 10 devices simultaneously

Response Time
REST API response time can be affected by many factors, including system characteristics
such number of cores and memory, as well as the amount of data in the TOS database and
the amount of data returned by an API call.

Indexed Data
For faster searching, TOS indexes commonly accessed data. The following APIs access
indexed data, and will therefore generally have a faster response time.

• Rule Usage

• Rule Search

• Network Object Search (Object Browser)

Device Data
Device data (for example, security rules or network objects) is included in revisions that are
retrieved by TOS from the device. To make this data available, these revisions must be
parsed and added to the Policy Model Cache in the TOS database. Data that is stored in the
Policy Model Cache is readily available for fast retrieval by the APIs. All other data is stored
unparsed and must be parsed prior to becoming available from the Policy Model Cache. This
data will have a lengthier retrieval time.

Data regarding the latest policy revision for every monitored device is stored in the Policy
Model Cache. Therefore, API calls to the retrieve the latest revisions or device data will
generally have a faster response time. If a historical revision is accessed via the APIs, the
data for that policy will remain in the Policy Model Cache for a period of time.

The first API call to retrieve historical data about a device will parse and store all the data in
the Policy Model Cache, and will have a slower response time. Subsequent API calls to
retrieve other data for the same revision will have a faster response time.

Tufin Knowledge Center: [Link]/support/kc 30

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API API Best Practices

Device data includes the following:

• Security Rules

• NAT Policies

• Network Objects

• Services and Ports

• Time Objects

• Crypto Maps

• Application IDs

• Additional Parameters

• Device Interfaces and Zones

• Policies and Sub-Policies

We recommend that API calls to retrieve historical data should be made in the background,
or alert the user with a message (for example “Processing in progress. Please wait”) and
changing the cursor icon.

Managing Generic Devices in the Interactive Map

If you are modifying multiple generic devices in consecutive API calls, you can set
update_topology=false on all API calls except for the last one. On the last call, set
update_toplogy=true or call the topology sync API call to synchronize the topology map.

Topology and Policy Analysis APIs

APIs that trigger topology and policy analysis calculations require internal TOS processing,
and will have a slower response time. We recommend that you call these APIs in the
background, or alert the user with a message (for example “Processing in progress. Please
wait”) and changing the cursor icon.

The APIs that trigger topology and policy analysis calculations are:

Tufin Knowledge Center: [Link]/support/kc 31

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API API Best Practices

• Path finder

This API cannot be executed more than 10 times in parallel

• Run Policy Analysis query

• Change Authorization

• Unified Security Policy - Access Request Violations

• Find Shadowing rules

Recommended and Maximum REST API Requests per Second

The following table lists the recommended and maximum REST API requests per second that
you can use in your applications.

average response time

Recommended Maximum
Requests/sec Requests/sec
<1 seconds 4 9
1-2 seconds 1 3
2-5 seconds 0.5 3
5-10 seconds 0.25 1

10-15 seconds 0.2 1

15-20 seconds 0.15 0.5

20-30 seconds 0.1 0.33

Estimating Average REST API Response Time

To estimate the average API response time for your environment, we recommend that you
time how long it takes to return the results for approximately 10 API calls. Use this data to
calculate your average response time. You can measure the response time manually using a
stop watch, or via the linux time command.

For example, to measure the actual amount of time it takes to retrieve all the rules for a single
device:

Tufin Knowledge Center: [Link]/support/kc 32

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Orchestration Suite (TOS) REST API API Best Practices

# time curl -u <admin_user>:<admin_password> -k --http1.0

[Link]

...

real 0m6.905s

user 0m0.030s

sys 0m0.050s

The results displayed in real 0m6.905s is the time it actually took for the server to return
the results. Repeat this ten times, and use the results to calculate the average response time.
Average response time can vary between API calls, so calculate the average response time
for each API you plan on using.

You can estimate response time for any commands that are relevant for your programming
requirements. For example, to determine the average response time to retrieve access
request violations, use the average response time from ten Access Request Violations API
calls. To determine the average response time to retrieve rules from a device, use the
average response time from ten Get Rules API calls. We recommend that you use devices
that contains many rules, so that your results will better model your environment.

Tufin Knowledge Center: [Link]/support/kc 33

 Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureTrack APG CLI APG CLI Overview

Chapter 3

SecureTrack APG CLI

The command line APG tool lets you analyze traffic logs from your firewalls to understand
how your policies are used. The command line tool includes some functionality that is not
available in the SecureTrack web interface.

APG CLI Overview

The APG analyzes firewall logs to determine actual business practices, and creates an
optimized rulebase that allows only this traffic. If you do not yet have a firewall policy in place,
you can begin by configuring a relatively permissive policy on the device and leave it in place
long enough to produce logs of the traffic. Then, use the APG to translate these logs into a
secure, optimized rulebase.

The APG uses configurable criteria to consolidate logs into rules. You can configure:

• When and how the APG generalizes multiple connections into whole networks or into
'Any' rules.

• Exclusions for rules that you do not want to include in the analysis.

After generating a policy, you should review it to make sure it isn't reflecting illegitimate traffic.
For example, a slow port scan or a generic botnet may have been active in the organization
and generating logs. In this case, configure the APG to ignore this traffic and generate a new
policy.

Because a rulebase generated by APG closely reflects actual traffic in an organization, this
rulebase is also useful for visualizing network traffic as a rulebase, even for purposes other
than actually replacing the firewall rulebase. For example, if you want to see all the traffic to
and from a specific subnet, you can configure a filter to analyze only logs to this subnet and
logs from this subnet, and automatically produce a rulebase that can be read as a list of
source-destination-service sets describing the traffic to and from the specified subnet.
Tufin Knowledge Center: [Link]/support/kc 34
Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureTrack APG CLI Consolidating Rules

Hints: To get familiar with the APG CLI, we recommend that you:

• Start with a simple case, such as a permissive rule you want to review.

• Run APG several times changing one configuration parameter at a time to see the
impact in the results.

• Try starting with changing the min-net-coverage and min-net-size parameters

and see how the results change. To see the difference clearly, make big changes in the
parameters, such as:

 Set the min-net-size to 28, and run the APG CLI first with min-net-coverage of
90 and then with min-net-coverage of 10.

Consolidating Rules
The Automatic Policy Generator (APG) consolidates logs according to:

• Ports to Any: Logs with ports matching ports specified in the <ports_to_any> tag of
the APG configuration file will define rules with 'Any' destination. This is useful for
services with which users need to be able to access the entire internet.

• Network Consolidation: Multiple sources or destinations are generalized to networks,

where the values of the other field (destination or source) and of the service field are
identical. The consolidation is to the largest possible network (smallest possible
netmask) where the logged traffic as a percentage of this network is at least the
configurable min_net_coverage value, and this network's netmask (in CIDR
notation) is no more than the configurable min_net_size value. These values can be
defined in the APG configuration file or in the APG command.

For example, with the following values configured, network consolidation will be to the
largest possible network of which the logged traffic is at least 50%, as long as this
network's prefix length is not more than 24 bits (3 octets).

min_net_coverage 50

min_net_size 24

• Any Consolidation: Multiple sources or destination are generalized to 'Any', where the
values of the other field (destination or source) and of the service field are identical,
and the number of different sources or destinations is at least the configurable
any_threshold value. This value can be defined in the APG configuration file or in
the APG command.
Tufin Knowledge Center: [Link]/support/kc 35
Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureTrack APG CLI Collecting Log Files

Collecting Log Files

Before you run the APG CLI analysis, you must collect log files for the analysis. You can do
this with, either:

• The Check Point log collector (see "Getting Check Point Logs for Upload" below)
(st_apg_collect) to collect and filter Check Point logs so that you can limit Check
Point log collection by rule UID or action (drop/accept), and/or by policy package and/or
by gateway.

• The standard log file format (see "Getting Log Files for Upload" on page 39) that you
can prepare from any firewall log file.

If you create an APG job in SecureTrack, you can configure the job to collect logs directly
from the device so that you can analyze future traffic.

Getting Check Point Logs for Upload

You can manually fetch Check Point logs with Check Point's fwm logexport command,
and then standardize them as with non-Check Point logs (see "Getting Log Files for Upload"
on page 39).

SecureTrack offers a simpler alternative method, using our st_apg_collect tool for
automatically collecting, standardizing, and filtering Check Point logs. The st_apg_collect
utility is included in the TOS installation and is typically run in the command line of your
SecureTrack machine. When using this tool, SecureTrack takes the logs for the specified
time frame from any relevant log files, filters and standardizes them, and generates an output
file in the required format for the APG.

You can limit log collection by rule UID or action (drop/accept), and/or by policy package
and/or by gateway. This can be useful for forensic purposes as well.

When using the output for an APG job in SecureTrack, if you want to filter the logs by rule
you must do that manually in the output before you send it to the APG. When using the
output for the APG CLI ([Link] you can filter the
output by rule and traffic pattern in the APG configuration.

Tufin Knowledge Center: [Link]/support/kc 36

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureTrack APG CLI Collecting Log Files

Procedure
To collect and prepare Check Point logs for the APG:

1. Get the SecureTrack device ID for the monitored Check Point management server.

To see the ID of a device, you can either:

 Open a command line to the SecureTrack host and run: st stat

 Click on the device in the SecureTrack device tree in Compare > Compare
Revisions, and type the letter t

2. Before collecting the logs, you can view a list of available log files, by running the
st_apg_collect utility on your SecureTrack machine:

st_apg_collect -m <mgmt_id> --list

where <mgmt_id> is the SecureTrack device ID for the monitored Check Point
management server or for the CLM that is associated with the monitored CMA..

For each log file, the following is displayed:

 File name: If the default naming has been used, the current file is named [Link], and
all other files are named according to the date and time they were closed.

 File time: The date and time of the first log in the file.

 Number of records in the file.

3. Decide on a time frame for which to collect logs, and run:

st_apg_collect -m <mgmt_id> -f <output_file> [--

from="<from_date>"] [--to="<to_date>"] [--append] [--policy-
name=<Policy>] [--log-file=<log_file>] [--rule-uid=<uid> | --
action=drop] [--module-name=<Name> | --module-ip=<IP>] --long-
mode

where:

 <mgmt_id> is the SecureTrack device ID for the monitored Check Point

management server or for the CLM that is associated with the monitored CMA..
Tufin Knowledge Center: [Link]/support/kc 37
Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureTrack APG CLI Collecting Log Files

 <output_file> is the path and filename for the generated log file.

 <from_date> is the date (and optionally, time) from which to collect logs. This
value must be included in quote marks, and its format is:

yyyy-mm-dd [hh:mm:ss]

 <to_date> is the date (and optionally, time) until which to collect logs. This value
must be included in quote marks, and its format is:

yyyy-mm-dd [hh:mm:ss]

 --append indicates that the generated log file should be added to an existing log
file, if found, rather than overwrite it.

 <Policy> is the name of a policy package. The --policy-name flag is used to

limit log collection to logs from this package.

 <log_file> is the name of a log file. The --log-file flag is used to limit log
collection to this log file.

 <uid> is a rule UID, to limit log collection to logs generated by this rule.

 --action=drop limits log collection to drop and reject actions. When this flag is
not used, log collection is limited to accept, authenticate, and encrypt actions
(unless the --rule-uid flag is used, in which case the logs for that rule are
collected, regardless of action).

Note: The --action and --rule-uid flags cannot both be used.

 <Name> is the case-sensitive name of a gateway. The --module-name flag is used

to limit log collection to logs from traffic handled by this gateway.

 <IP> is the primary IP address of a gateway. The --module-ip flag is used to limit
log collection to logs from traffic handled by this gateway.

Note: The --module-name and --module-ip flags cannot both be used.

 --long-mode exports verbose data for each log record. This is needed for
historical rule usage.

Tufin Knowledge Center: [Link]/support/kc 38

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureTrack APG CLI Running APG CLI

Getting Log Files for Upload

You can upload log files from your device to an APG job so that you can analyze past traffic,
but you must first prepare the log files so that they are in the correct format for analysis. For
Check Point devices, you can also do this from the command line (see "Getting Check Point
Logs for Upload" on page 36).

To prepare log files from firewall devices:

1. Collecting the log files from the firewall for the desired time frame.

2. Remove all logs not related to traffic.

3. Remove drop logs (unless you are analyzing dropped traffic).

4. Filter for other values, if necessary.

5. Identify and extract the relevant fields (source; destination; port; IP-protocol) in the logs.

6. Convert the field values to the standard format: source destination port IP-
protocol

For example:

[Link] [Link] 22 6

[Link] [Link] 53 17

7. Store the results in a single file.

Running APG CLI

After you prepare the log files (see "Collecting Log Files" on page 36), you can generate an
actual firewall policy from the log files with the command:

st_apg_gen <parameters>

where <parameters> is a list of any of the below parameters, each parameter name
followed by =<value> . For example:

Tufin Knowledge Center: [Link]/support/kc 39

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureTrack APG CLI Customizing APG CLI Results

st_apg_gen --conf=/usr/local/st/conf/apg_conf.xml --input=[Link] -

-output=policy --output-format=html --min-net-coverage=10 --min-net-
size=28 --include-broadcast=0 --any-threshold=100

Available parameters and values are:

Input/output parameters:

• --conf : The APG configuration file. The default is located in:

/usr/local/st/conf/apg_conf.xml

• --input :A prepared log file (see "Collecting Log Files" on page 36).

• --output : A prefix for the output filename. The APG output phase (default: 5) and an
extension will be appended to the filename.

• --output-format : The format for the generated firewall policy. The value must be
one of the following:

 txt

 xml

 html

Parameters for rule consolidation:

• --min-net-coverage : An integer between 1 and 100, indicating the minimum

percentage that logged traffic needs to be of a network for network consolidation.

• --min-net-size : An integer between 1 and 32, indicating the minimal subnet length
(in CIDR notation) that is allowed to be created by network consolidation.

• --include-broadcast : 0 or 1, determining whether or not to include the broadcast

address in network consolidation.

• --any-threshold : An integer indicating the minimum number of traffic logs for Any
consolidation.

Customizing APG CLI Results

You can edit the APG configuration file (apg_conf.xml) to:

Tufin Knowledge Center: [Link]/support/kc 40

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureTrack APG CLI Customizing APG CLI Results

• Customize when and how the APG consolidates (see "Consolidating Rules" on page
35) multiple connections into whole networks or into 'Any' rules

• Exclude connections from the APG analysis

• Specify the input file, and the output file and file format

You can define all of these options in the XML configuration file and specify that the APG
command use this configuration file. If you define any of these options directly as arguments
in the APG command, the CLI parameters override the definitions from the configuration file.

The default name of the configuration file is: /usr/local/st/conf/apg_conf.xml . If

you save the configuration file with a different name, you must specify the filename in the
APG command.

The default APG configuration file is:

<conf>
<!--ports_to_any>
<port>80/6</port>
<port>443/6</port>
<port>21/6</port>
</ports_to_any-->
<log_filter>
<!--rule>
<source>
<subnet>[Link]/16</subnet>
<negate>0</negate>
</source>
<destination>
</destination>
<!--service>
<port>80/6</port>
<port>443/6</port>
</service>
</rule-->
</log_filter>
<network_consolidation>

Tufin Knowledge Center: [Link]/support/kc 41

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureTrack APG CLI Customizing APG CLI Results

<min_net_coverage>50</min_net_coverage>
<min_net_size>24</min_net_size>
<include_broadcast>1</include_broadcast>
<any_threshold>500</any_threshold>
</network_consolidation>
<io>
<input>[Link]</input>
<output>policy</output>
<output_format>html</output_format>
<out_phases>final</out_phases>
</io>
</conf>

Note: Some sections of the default configuration file are commented out. To enable these
features, remove the !-- and -- from the tags.

The APG configuration file is delimited by the <conf> tag, and contains these optional
sections:

• <ports_to_any> : Ports defined in this section, when found in logs, define output
rules with 'Any' destination. This is useful for services with which users need to be able
to access the entire internet. Each <port> tag should contain a value in the format:
Port#/IP-protocol# .

• <log_filter> : Each <rule> contains a traffic pattern, that when matched by a log,
causes that log to be analyzed by the APG. When no traffic patterns are defined, all
logs are analyzed.

Each <rule> contains: <source>, <destination>, and <service>. <source>

and <destination> each contain any number of <subnet>s; or none, which is the
equivalent of: Any. <service> contains any number of <port>s; or none, which is the
equivalent of: Any.

<source>, <destination>, and <service> each can contain a <negate> value

that when set to 1 negates the defined subnets or ports, such that the defined subnets
or ports are ignored and only all other logs are analyzed.

• <network_consolidation> : Parameters for rule consolidation:

Tufin Knowledge Center: [Link]/support/kc 42

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureTrack APG CLI Customizing APG CLI Results

 <min_net_coverage> : An integer between 1 and 100, indicating the minimum

percentage that logged traffic needs to be of a network for network consolidation.

 <min_net_size> : An integer between 1 and 32, indicating the minimal subnet

length (in CIDR notation) that is allowed to be created by network consolidation.

 <include_broadcast> : 0 or 1, determining whether or not to include the

broadcast address in network consolidation.

 <any_threshold> : An integer indicating the minimum number of traffic logs for

Any consolidation.

• <io> : Input/output parameters:

 <input> : A prepared log file (see "Collecting Log Files" on page 36).

 <output> : A prefix for the output filename. The APG output phase (default: 5) and
an extension will be appended to the filename.

 <output_format> : The format for the generated firewall policy. The value must
be one of the following:

• txt

• xml

• html

 <out_phases> : This tag is for setting the level of analysis. 1 shows the rules with
hit counts on the flows, and 5 or final shows all of the APG analysis.

Tufin Knowledge Center: [Link]/support/kc 43

 Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Open Platform (TOP) Introduction to TOP

Chapter 4

Tufin Open Platform (TOP)

Introduction to TOP
Tufin Open Platform (TOP) provides an API that lets SecureTrack monitor and track
configuration changes for devices that are not natively supported. With TOP, SecureTrack
can monitor any device's configuration that can be retrieved as a text file, including:

• View and compare configurations

• Send notifications of new revisions

• Run Advanced Change reports

• See connectivity status

• Get connectivity administrative alerts

TOP monitoring requires a customized plugin, specific to the monitored device model. You
install the plugin in SecureTrack and SecureTrack uses the TOP plugin to retrieve
configuration text files from the device. The plugin defines how SecureTrack retrieves and
handles the configuration. The TOP plugin for each device type is a single .tgz file, which is
easily installed by a SecureTrack Administrator in the SecureTrack.

TOP plugins are created by Tufin and by other members of the TOP alliance, including
device members and Tufin customers. TOP plugins for Blue Coat ProxySG, F5 BIG-IP LTM,
and Linux iptables are preinstalled in SecureTrack. You can download other plugins from the
TOP plugins page of the Tufin website ([Link]
alliance/).

Note: Tufin does not provide support for plugins that are developed by members of the
TOP alliance.

Tufin Knowledge Center: [Link]/support/kc 44

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Open Platform (TOP) Creating a TOP Plugin

For assistance in developing the TOP plugin, please feel free to contact Tufin support
(support@[Link]).

TOP Plugin Architecture

A TOP Plugin is a single compressed tar file (.tgz). The tar archive contains the following
files:

• Data Retrieval executable (see "Creating the Data Retrieval Executable" on page 51):
Contains code for connecting to the monitored device, retrieving the configuration, and
sending it to standard output in the required format.

• Graphic icon file (optional): SecureTrack displays the monitored device with this icon,
in Compare view, Devices page, and Status page. This graphic must be a 16x16 GIF,
and is recommended to be transparent.

• top_manifest.xml (see "Creating the top_manifest.xml File" on page 46): The primary
plugin file used directly by SecureTrack. It defines values for SecureTrack, such as the
Data Retrieval executable, plugin metadata, error messages, and the icon file, and
defines parameters to be used by the Data Retrieval executable.

• Runtime Files: Any files required by the Data Retrieval executable at runtime, such as
shared libraries for C/C++. SecureTrack comes with JVM 1.6 (for Java), so this does
not need to be included in the plugin.

• Additional files (optional): The main Data Retrieval executable can call these files.

• Readme file (see "Creating the Readme File" on page 52) (optional): A text file with
information important to the plugin end-user.

Creating a TOP Plugin

Overview: High-Level Plugin Creation Procedure
To create a TOP plugin:

1. Create the top_manifest.xml file (see "Creating the top_manifest.xml File" on page 46).

2. Create the Data Retrieval executable (see "Creating the Data Retrieval Executable" on
page 51), and any additional files called by the main Data Retrieval file.

Tufin Knowledge Center: [Link]/support/kc 45

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Open Platform (TOP) Creating a TOP Plugin

3. In addition to the above files, obtain any files required by the Data Retrieval executable
(see "Creating the Data Retrieval Executable" on page 51), and (optional) a 16x16 GIF
graphic icon file for SecureTrack to display for the monitored device.

4. Create the Readme text file (see "Creating the Readme File" on page 52) (optional).

5. Package all of the above files (see "Packaging the TOP Plugin" on page 52).

6. Test the plugin (see "Testing the TOP Plugin" on page 53).

The plugin can now be installed by SecureTrack administrators (see "Installing a TOP Plugin"
on page 53), after which they can monitor devices of the relevant type.

Creating the top_manifest.xml File

top_manifest.xml is the primary plugin file used directly by SecureTrack. It defines values for
SecureTrack, such as the Data Retrieval executable, plugin metadata, error messages, and
the icon file, and defines parameters to be used by the Data Retrieval executable.

The following is an example top_manifest.xml file:

The above example can be copied from here to be used as a template file. The XML Schema
is documented in the [Link] file included in the TOP Developer's Package.

The top_manifest.xml file must consist of valid XML, and must contain the following sections,
under the root <plugin> tag:

• Plugin information: The following four mandatory tags. SecureTrack displays these
tags' values in the list of installed plugins:

 <name>: A name for the plugin, which must be unique when installed in
SecureTrack. Tufin recommends the following naming convention:

<name>[Link].device_vendor.device_model</name>

 <version>: A version number for the plugin, which should be incremented upon
changes to the plugin. The version number must be in the form [Link] .

For example:

Tufin Knowledge Center: [Link]/support/kc 46

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Open Platform (TOP) Creating a TOP Plugin

<version>1.0</version>

 <vendor>: The device vendor, such as Blue Coat or F5, with no spaces in the
name. This name appears in the device tree in Compare view and in the Devices
page.

For example:

<vendor>Blue_Coat</vendor>

 <model>: The device type. This text will also appear in the SecureTrack device tree
in Compare view and in the Devices page.

For example:

<model>ProxySG</model>

• Data retrieval information: This section is delimited by the <data-retriever> tag. It

contains the following tags:

 <command> (mandatory): The filename of the main Data Retrieval executable,

relative to the tar archive root. For example, if the executable is called
configuration_retriever, and is under an "exe" directory in the archive:

<command>exe/configuration_retriever</command>

 <protocols> (mandatory): A <protocol> tag for each protocol that can be used
for connecting to the device. SSH and Telnet are currently supported.

If more than one <protocol> tag are included, then when adding a device to
SecureTrack, the user will select which to use for the specific device.

For example:

<protocols>

<protocol>ssh</protocol>

<protocol>telnet</protocol>

</protocols>

 <command-line> and/or <standard-input> (optional): Parameters to be

passed to the Data Retrieval executable. These parameters pass values defined in
SecureTrack to the executable. SecureTrack passes multiple standard-input
parameters separated by ASCII LF (0x0A).
Tufin Knowledge Center: [Link]/support/kc 47
Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Open Platform (TOP) Creating a TOP Plugin

There are six available optional parameters, each of which can be passed via
command line or via standard input. It is recommended for sensitive information
(such as password, enable password) to be passed via standard input rather than
command line.

The command line parameters section is delimited by the <command-line> tag;

the standard input section - by the <standard-input> tag. Within each of the two
categories (command line and standard input), parameters will be passed in the
order they are defined.

Each parameter is delimited by the <param> tag, and contains a <value> tag,
which contains a variable prefixed with the $ sign. The <value> tag may be
preceded by a <key> tag, to pass a relevant flag to the executable, as required by
the executable. For example:

<param>

<key>-t<key>

<value>$timeout</value>

</param>

The six available parameters are:

• Connection protocol: Where the protocol is selected per device when adding the
device in SecureTrack, define this parameter, as follows:

<param>

<value>$protocol</value>

</param>

• Device IP address: Use the $ip-address variable, which will be resolved to the
IP address configured in SecureTrack per device:

<param>

<value>$ip-address</value>

</param>

Tufin Knowledge Center: [Link]/support/kc 48

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Open Platform (TOP) Creating a TOP Plugin

• Username for SecureTrack to log into the device: Use the $username variable:

<param>

<value>$username</value>

</param>

• Timeout: How long SecureTrack will wait for a response from device before
continuing, as configured in SecureTrack's Timing page. Use the $timeout
variable:

<param>

<value>$timeout</value>

</param>

• Device authentication password: Use the $password variable:

<param>

<value>$password</value>

</param>

• Device authentication enable password: A second password required by some

devices. Where relevant, use the $enable-password variable:

<param>

<value>$enable-password</value>

</param>

The following sections are optional:

• <error_codes> (note the plural: codes): Defines error messages to be displayed in

SecureTrack's Status page (and in st status output).

This section is delimited by the <error_codes> tag (note the plural: codes), and
contains an <error_code> (note the singular: code) tag for each error code that can
be returned by the Data Retrieval executable.

Tufin Knowledge Center: [Link]/support/kc 49

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Open Platform (TOP) Creating a TOP Plugin

Error code 0 is reserved for success, and should not be defined here. It is also
recommended not to use error code 1, which is a default error code in many script
shells.

Each <error_code> tag contains:

 A <code> tag, containing an error code that can be generated by the Data Retrieval
executable, and

 A <description> tag, containing the corresponding error message that should be

displayed by SecureTrack.

For example:

<error_codes>

<error_code>

<code>2</code>

<description>Invalid Number of Parameters</description>

</error_code>

<error_code>

<code>3</code>

<description>Connection Timeout</description>

</error_code>

...

</error_codes>

• <representation>: Contains the <icon> tag, which defines an icon graphic file.
SecureTrack displays the monitored device with this icon, in Compare view, Devices
page, and Status page. This graphic must be a 16x16 GIF, and is recommended to be
transparent. If no icon file is supplied, SecureTrack uses a default TOP icon.

For example:

<representation>

<icon>[Link]</icon>
Tufin Knowledge Center: [Link]/support/kc 50
Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Open Platform (TOP) Creating a TOP Plugin

</representation>

Creating the Data Retrieval Executable

The Data Retrieval executable contains code for connecting to the monitored device,
retrieving the configuration, and sending it to standard output in the required format. It can be
written in any programming or scripting language, as long as all files required at runtime are
available (they can be included in the plugin package). The executable can also call
additional files that are included in the package.

The runtime environment for the Data Retrieval executable is Linux (Red Hat Enterprise
Linux, CentOS, or TufinOS). The executable must be compatible with this environment. If
necessary, required files should be included in the plugin.

Some programming language options are:

• The Expect scripting language is appropriate for automating interactive applications,

and as such is appropriate for the Data Retrieval executable when the data retrieval
requires interaction. For example, when data retrieval requires commands to be
executed over SSH.

For an Expect Data Retrieval executable, no additional runtime files are required.

• C/C++ executables should be developed with GCC 3.2.3, which all Tufin platforms
support. GCC 3.2.3 exists in Red Hat Enterprise Linux version 3.

• Java executables can rely on JVM 1.6 included with SecureTrack.

• Other programming and scripting languages can be used, such as BASH and Python.

The executable file is defined by the top_manifest.xml file, in the command tag.

The executable should retrieve the configuration of the monitored device, and if necessary
convert it to text format.

The executable should add the following marker, followed by a line break, immediately
before the text to be read by SecureTrack:

=====config begin=====

Tufin Knowledge Center: [Link]/support/kc 51

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Open Platform (TOP) Creating a TOP Plugin

The executable should add the following marker, followed by a line break, immediately after
the text to be read by SecureTrack:

=====config end=====

For example (from a Data Retrieval executable written in Expect):

send_user "=====config begin=====\n"

...

send_user "=====config end=====\n"

The executable should send the retrieved text, along with the Begin and End markers, to
standard output.

The executable should send an exit code 0 when successful. For other error codes, make
sure to define error messages in top_manifest.xml (see "Creating the top_manifest.xml File"
on page 46).

Creating the Readme File

The Readme text file should contain information important to the plugin end-user, such as:

• Plugin developer details and contact information

• Supported monitorable devices and versions

• Tested platforms (operating system and SecureTrack versions)

• Programming language(s) used to develop the plugin

• Packages required to be in the environment (for example: Python interpreter)

Packaging the TOP Plugin

Once all the plugin files (see "TOP Plugin Architecture" on page 45) are ready, combine them
to create the plugin file, with the following command:

tar -czf <plugin_name>.tgz <filenames>

where

Tufin Knowledge Center: [Link]/support/kc 52

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Open Platform (TOP) Testing the TOP Plugin

<plugin_name> is the desired name for the file being created, and

<filenames> is the list of files to be included, separated by spaces (do not include the
containing directory).

Testing the TOP Plugin

To test the TOP plugin, validate it using the TOP plugin validation tool (see "Validating the
TOP Plugin" below) included in SecureTrack. Then, install the plugin (see "Installing a TOP
Plugin" below) and test actual device monitoring.

TOP plugins are supported in SecureTrack from version 5.0.

Validating the TOP Plugin

To validate the format of a TOP plugin, copy the plugin to the SecureTrack machine, and run:

st_top_validator <plugin_filename>

The validation tool will examine the plugin and report the results.

Installing a TOP Plugin

To install a TOP plugin in SecureTrack:

1. Go to the Tufin Download Center (see Download TOP plugins -

[Link] and
download the TOP plugin for your device.

2. In Settings > Monitoring > TOP Plugins.

3. Click New Plugin:

Navigate to the .tgz file, and click Open.

4. Wait for confirmation:

Tufin Knowledge Center: [Link]/support/kc 53

Tufin™ Orchestration Suite (TOS) Developer's Guide

Tufin Open Platform (TOP) Testing the TOP Plugin

The plugin is installed. You can now add devices of the relevant type, from the Devices
page.

Tufin Knowledge Center: [Link]/support/kc 54

 Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureChange API Scripts Example: Send Mail on Close

Chapter 5

SecureChange API Scripts

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 to send information to external systems about ticket progress. SecureChange
passes ticket information to the script in XML format. You can use a script which runs
depending on an argument that you specify in the SecureChange API script configuration.
For example, your script can collect ticket information and the argument specifies if the script
sends the information by email or saves it to a file on the local disk.

When you add a script, you select a workflow and a group of triggers that cause the script to
run. When a selected trigger happens, SecureChange attempts to run the script
asynchronously, up to a maximum of five times. If SecureChange does not succeed in
starting the script, a message is added to Settings > Message Board.

Example: Send Mail on Close

In this example, you configure SecureChange to run a script every time a ticket closes on a
specified workflow. The script sends an email notification to the recipients listed in the sample
script file (see "Sample Script File" on page 56).

To configure SecureChange to send mail on closed tickets:

1. In the sample script file, change:

a. HTTP_HOST to the IP of the mail server.

b. The email address in MAIL_TO="amir@[Link]" to the recipient.

2. For each additional recipient add at the end 2 lines:

export MAIL_TO="<recipient email address>"

Tufin Knowledge Center: [Link]/support/kc 55
Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureChange API Scripts Sample Script File

php /usr/local/st/[Link] < /tmp/t_$ticket_info_id.log

3. Copy the script to the SecureChange server, for example in: /usr/sbin

4. Verify that has execute permission for the tomcat user: chmod +x <script name>

If the script writes output, make sure that the tomcat user also has permission to write
to the /usr/sbin directory.

5. Configure SecureChange to use the script:

a. In SecureChange, go to Settings > SecureChange API.

b. Click Add script.

c. Enter a display name for the script and the full path to the script (for example,
/usr/bin/sc_send_mail).

d. Enter a display name for the trigger group, select the workflow that you want the
script to run on, and select the action that triggers the script (for example, close).

e. Click Save.

Now, the script runs every time a ticket is closed on that workflow.

Sample Script File

For the Send Mail on Close script, save this code as: sc_send_mail

#!/bin/bash

function parseXML() {
elemList=( $(echo $xmlFile | tr '\n' ' ' | XMLLINT_INDENT="" xmllint --format - |
/bin/grep -e "</.*>$" | while read line; do \
echo $line | sed -e 's/^.*<\///' | cut -d '>' -f 1; \
done) )

Tufin Knowledge Center: [Link]/support/kc 56

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureChange API Scripts Sample Script File

totalNoOfTags=${#elemList[@]}; ((totalNoOfTags--))
suffix=$(echo ${elemList[$totalNoOfTags]} | tr -d '</>')
suffix="${suffix}_"

for (( i = 0 ; i < ${#elemList[@]} ; i++ )); do

elem=${elemList[$i]}
elemLine=$(echo $xmlFile | tr '\n' ' ' | XMLLINT_INDENT="" xmllint --format - |
/bin/grep -m 1 "</$elem>")
echo $elemLine | grep -e "^</[^ ]*>$" 1>/dev/null 2>&1
if [ "0" = "$?" ]; then
continue
fi
elemVal=$(echo $elemLine | tr '\011' '\040'| sed -e 's/^[ ]*//' -e
's/^<.*>\([^<].*\)<.*>$/\1/' | sed -e 's/^[ ]*//' | sed -e 's/[ ]*$//')
xmlElem="${suffix}$(echo $elem | sed 's/-/_/g')"
eval ${xmlElem}=`echo -ne \""${elemVal}"\"`
attrList=($(echo $xmlFile | tr '\n' ' ' | XMLLINT_INDENT="" xmllint --format -
| /bin/grep "</$elem>" | tr '\011' '\040' | sed -e 's/^[ ]*//' | cut -d '>' -f 1 |
sed -e 's/^<[^ ]*//' | tr "'" '"' | tr '"' '\n' | tr '=' '\n' | sed -e 's/^[ ]*//'
| sed '/^$/d' | tr '\011' '\040' | tr ' ' '>'))
for (( j = 0 ; j < ${#attrList[@]} ; j++ )); do
attr=${attrList[$j]}
((j++))
attrVal=$(echo ${attrList[$j]} | tr '>' ' ')
attrName=`echo -ne ${xmlElem}_${attr}`
eval ${attrName}=`echo -ne \""${attrVal}"\"`
done
done
}

while read tmp; do

xmlFile=$xmlFile$tmp
done

parseXML

echo "<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'

'[Link]
<html xmlns='[Link]

Tufin Knowledge Center: [Link]/support/kc 57

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureChange API Scripts Sample XML Output

<head>
<meta http-equiv='Content-Type' content='text/html;
charset=UTF-8' />
</head>
<body>
<h2><u>Ticked Information</u></h2>
Ticket Subject: $ticket_info_subject <br/>
TicketID: $ticket_info_id <br/>
Ticket Requestor: $ticket_info_login <br/>
Priority: $ticket_info_name <br/>
</body>
</html>" > /tmp/t_$ticket_info_id.log

export MAIL_FROM="st@[Link]"
export MAIL_TO="guy@[Link]"
export MAIL_SUBJECT="Ticket Closed Notification"
export MAIL_CONTENT_LENGTH=1024
export REDIRECT_STATUS=1
export HTTP_HOST="[Link]"
export HTTP_HELO="SecureTrack"
export MAIL_PORT=25
export MAIL_EMBED=0
export MAIL_MHT=0
export MAIL_PDF=0

php /usr/local/st/[Link] < /tmp/t_$ticket_info_id.log

Sample XML Output

This is a sample of the XML output that SecureChange sends to the script when modifying a
ticket based on the ticket info field:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<ticket_info>
<id>4</id>
<subject>1</subject>
<priority>
<id>3</id>

Tufin Knowledge Center: [Link]/support/kc 58

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureChange API Scripts Sample XML Output

<name>Normal</name>
</priority>
<createDate>1301392380958</createDate>
<updateDate>1301586217732</updateDate>
<requester>
<id>3</id>
<login>1</login>
<display_name>1</display_name>
</requester>
<current_stage>
<id>9</id>
<name>Open Request</name>
<ticket_task>
<id>11</id>
<name>Default</name>
<handler>
<id>3</id>
<login>1</login>
<display_name>1</display_name>
</handler>
<ticket_field>
<name>text</name>
<TextAreaValue>
<id>143</id>
<value>1</value>
</TextAreaValue>
</ticket_field>
</ticket_task>
</current_stage>
<open_request_stage>
<id>9</id>
<name>Open Request</name>
<ticket_task>
<id>11</id>
<name>Default</name>
<handler>
<id>3</id>
<login>1</login>
<display_name>1</display_name>

Tufin Knowledge Center: [Link]/support/kc 59

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureChange API Scripts Sample XML Output

</handler>
<ticket_field>
<name>text</name>
<TextAreaValue>
<id>143</id>
<value>1</value>
</TextAreaValue>
</ticket_field>
</ticket_task>
</open_request_stage>
<comment xsi:type="RedoCommentType"
xmlns:xsi="[Link]
<content>asdasdas</content>
<user>
<id>3</id>
<login>1</login>
<display_name>1</display_name>
</user>
</comment>
<comment xsi:type="RedoCommentType"
xmlns:xsi="[Link]
<content>aaaaaaa</content>
<user>
<id>3</id>
<login>1</login>
<display_name>1</display_name>
</user>
</comment>
<comment xsi:type="RedoCommentType"
xmlns:xsi="[Link]
<content>asdasd</content>
<user>
<id>3</id>
<login>1</login>
<display_name>1</display_name>
</user>
</comment>
</ticket_info>

Tufin Knowledge Center: [Link]/support/kc 60

 Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureChange Inbound Mail Sample XML Output

Chapter 6

SecureChange Inbound Mail

SecureChange can receive email and open a new request with the information in the email.
This lets you open a request by mail, without logging into SecureChange.

To do this, you associate each mailbox with a workflow. When SecureChange receives an
email in a mailbox, it opens the request in the associated workflow and moves the request to
the next step in the workflow.

The process for opening a request by mail is:

1. Create an email account on your mail server where the requests will be sent.

2. Add an inbound mailbox in SecureChange that receives mail that is sent to the email
account.

3. Associate the inbound mailbox with a SecureChange workflow.

4. Tell users the email address to send their requests to.

When an email is received by the inbound mailbox, a ticket is opened in the selected
workflow and the email fields are copied to the ticket details:

Email Field Request Field

Subject Subject

Sender Requester

Body Description
Importance Priority
Date Sent Date Opened

Tufin Knowledge Center: [Link]/support/kc 61

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureChange Inbound Mail Adding an Inbound Mailbox

Adding an Inbound Mailbox

Before you add an inbound mailbox, you must create new email accounts in your
organization's mail server. The mail server must be the one that is configured in Mail
Settings. SecureChange connects to the server with the POP3 protocol and any mail that is
received is deleted from the mail server.

Each workflow for which you let users open requests by mail must have its own email
account in the mail server. SecureChange connects to the mail server and gets mail from
these email accounts.

To add an inbound mailbox:

1. Make sure your mail server is configured in Settings > Mail, and click Test to make
sure the connection is successful.

2. Create a new email account in your mail server to receive requests by mail.

3. Go to Settings > SecureChange API.

4. Click Add mail.

5. Enter a Name for the mailbox.

6. Select the workflow to which the mailbox will open requests.

The selected workflow is shown as the Active Workflow.

Note: If the active workflow is deleted or deactivated (in Workflows), the original
workflow will still be shown as the active workflow, but emails to the inbound
mailbox will not open requests.

7. Enter the username and password for the email account.

8. Test that SecureChange can access the email account.

9. Save.

SecureChange is ready to receive mail that is sent to the email account that you entered.

Tufin Knowledge Center: [Link]/support/kc 62

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureChange Inbound Mail Example: Opening a Request by Mail

Example: Opening a Request by Mail

To configure SecureChange so that users can open a request to the "Need Access" workflow
by email:

1. Create an email account on your mail server where the requests will be sent, for
example:

Username: need_access@[Link]

Password: password

2. In SecureChange, create the inbound mailbox:

a. Go to Settings > SecureChange API.

b. At the bottom of the page, click Add mail.

Enter the details for the mailbox:

• Name: Enter Requests for Need Access

• Select workflow: Select Need Access

• Username: Enter the username of the email account on your mail server, for
example: need_access@[Link]

• Password: Enter the password of the email account on your mail server, for
example: password

c. Click Test.

If the test fails, make sure that the details of your mail server are correct in Settings
> Mail, and that the username and password of the email account are correct.

d. Click Save.

To test the mailbox, send an email to the email account (need_access@[Link])

and enter Test as the subject. Within a few minutes, a request with the subject Test is

Tufin Knowledge Center: [Link]/support/kc 63

Tufin™ Orchestration Suite (TOS) Developer's Guide

SecureChange Inbound Mail Example: Opening a Request by Mail

opened in SecureChange and the date the email was sent is the Date Opened for the
request.

Tufin Knowledge Center: [Link]/support/kc 64

 Tufin™ Orchestration Suite (TOS) Developer's Guide

Patents and Trademarks Example: Opening a Request by Mail

Appendix I

Patents and Trademarks

PATENTS
See (see [Link] - [Link] .

TRADEMARKS

Tufin, SecureChange, SecureTrack, Automatic Policy Generator, and the Tufin logo are trademarks of Tufin
Software Technologies Ltd.

All other product names mentioned herein are trademarks or registered trademarks of their respective owners.

Some TOP plugins include software developed by Terrapin Communications, Inc. and its contributors for
RANCID.

Tufin Knowledge Center: [Link]/support/kc 65