securecrt_tools.scripts

This module contains classes for representing the execution of a script in SecureCRT. The attributes and methods defined with these classes are more “global” in nature, meaning that they focus on either the interaction with the application, or anything that is common to the entire script regardless of how many sessions (in tabs) are open to remote devices.

The Script Base Class

class securecrt_tools.scripts.Script(script_path)

This is a base class for the script object. This class cannot be used directly, but is instead a blueprint that enforces what any sub-classes must implement. The reason for using this design (base class with sub-classes) is to allow the script to be run in different contexts without needing to change the code, as long as the correct sub-class is being used.

For example, the most important sub-class is the CRTScript subclass which is used when the script is executed from SecureCRT. This class is written to interact with SecureCRT’s Python API to be able to control the applications. If the script author wants to display something to the user, they can use the message_box() method to use SecureCRT’s pop-up message box (crt.Dialog.MessageBox() call). The other sub-class (currently) is the DebugScript sub-class, which was created to allow easier debugging of a script’s logic by letting you execute the script using a local python installation – ideally in your IDE of choice. This would allow you to use the fully debugging features of the IDE which are otherwise not available when executing a script inside SecureCRT. When the message_box() is called on the DebugScript sub-class, the message will be printed to the console.

This sub-class design can also allow for additional classes to be created in the future – perhaps one that uses Netmiko to connect to the remote devices. In this way, if a Netmiko sub-class was created, then all of the same scripts can be executed without needing to change them, because the Netmiko class would be required to implement all of the same methods that are defined in the base class (just like CRTScript and DebugScript)

DebugScript class is to allow the programmer to debug their code in their favorite IDE or debugger, which cannot be done when executing the script from SecureCRT (in which case you are forced to either use debug messages or write outputs to a messagebox. DebugScript allows the same code to run locally without SecureCRT and the class will prompt for the information it needs to continue running the main script.

Any methods that are not prepended with the @abstractmethod tag preceding the method definition will be inherited and available to the sub-classes without needing to define them specifically in each sub-class. Methods designed this way would use the exact same code in all sub-classes, and so there is no reason to re-create them in each subclass.

Methods defined with the @abstractmethod tag should be left empty in this class. They are required to be implemented in each sub-class. Methods are defined this way when they are required to exist in all sub-classes for consistency, but the code would be written completely different depending on which class is being used. One example is the message_box method below. Under the CRTScript class, this method uses the SecureCRT API to print messages and format the text box that should pop up to the user, but in the DebugScript class this method only prints the message to the console. In this way, a call to this method will work either way the script is called as long as the correct Script sub-class is being used (and the template are already written to do this).

get_main_session()

Returns a CRTSession object that interacts with the SecureCRT tab that the script was lauched within. This is the primary tab that will be used to interact with remote devices. While new tabs can be created to connect to other devices, SecureCRT does not support multi-threading so multiple devices cannot be interacted with simultaneously via a script.

Returns:A session object that represents the tab where the script was launched
Return type:sessions.Session
get_template(name)

Retrieve the full path to a TextFSM template file.

Parameters:name (str) – Filename of the template
Returns:Full path to the template location
Return type:str
import_device_list()

This function will prompt for a device list CSV file to import, returns a list containing all of the devices that were in the CSV file and their associated credentials. The CSV file must be of the format, and include a header row of [‘Hostname’, ‘Protocol’, ‘Username’, ‘Password’, ‘Enable’, ‘Proxy Session’]. An example device list CSV file is at ‘template/sample_device_list.csv’

The ‘Proxy Session’ options is looking for a SecureCRT session name that can be used to proxy this connection through. This sets the ‘Firewall’ option under a SecureCRT session to perform this connection proxy.

Some additional information about missing items from a line in the CSV: - If the hostname field is missing, the line will be skipped. - If the protocol field is empty, the script will try SSH2, then SSH1, then Telnet. - If the username is missing, this method will prompt the user for a default usernaem to use - If the password is missing, will prompt the user for a password for each username missing a password - If the enable password is missing, the method will ask the user if they want to set a default enable to use - If the IP is included then the device will be reached through the jumpbox, otherwise connect directly.

Returns:A list where each entry is a dictionary representing a device and the associated login information.
Return type:list of dict
validate_dir(path, prompt_to_create=True)

Verifies that the path to the supplied directory exists. If not, prompt the user to create it.

Parameters:path (str) – A directory path (not including filename) to be validated

CRTScript Class

class securecrt_tools.scripts.CRTScript(crt)

Bases: securecrt_tools.scripts.Script

This class is a sub-class of the Script base class, and is meant to be used in any scripts that are being executed from inside of SecureCRT. This sub-class is designed to interact with the SecureCRT application itself (not with tabs that have connections to remote devices) and represent a script being executed from within SecureCRT. This class inherits the methods from the Script class that are documented above, and is required to implement all of the abstract classes defined in the Script class.

connect(host, username, password, protocol=None, proxy=None, prompt_endings=('#', '>'))

Attempts to connect to a device by any available protocol, starting with SSH2, then SSH1, then telnet

Parameters:
  • host (str) – The IP address of DNS name for the device to connect
  • username (str) – The username to login to the device with
  • password (str) – The password that goes with the provided username. If a password is not specified, the user will be prompted for one.
  • protocol (str) – A string with the desired protocol (telnet, ssh1, ssh2, ssh). If left blank it will try all starting with SSH2, then SSH1 then Telnet. “ssh” means SSH2 then SSH1.
  • proxy (str) – The name of a SecureCRT session object that can be used as a jumpbox to proxy the SSH connection through. This is the same as selecting a session under the “Firewall” selection under the SSH settings screen for a SecureCRT session.
  • prompt_endings (list) – A list of strings that are possible prompt endings to watch for. The default is for Cisco devices (“>” and “#”), but may need to be changed if connecting to another type of device (for example “$” for some linux hosts).
connect_ssh(host, username, password, version=None, proxy=None, prompt_endings=('#', '>'))

Connects to a device via the SSH protocol. By default, SSH2 will be tried first, but if it fails it will attempt to fall back to SSH1.

Parameters:
  • host (str) – The IP address of DNS name for the device to connect
  • username (str) – The username to login to the device with
  • password (str) – The password that goes with the provided username. If a password is not specified, the user will be prompted for one.
  • version (int) – The SSH version to connect with (1 or 2). Default is None, which will try 2 first and fallback to 1 if that fails.
  • proxy (str) – The name of a SecureCRT session object that can be used as a jumpbox to proxy the SSH connection through. This is the same as selecting a session under the “Firewall” selection under the SSH settings screen for a SecureCRT session.
  • prompt_endings (list) – A list of strings that are possible prompt endings to watch for. The default is for Cisco devices (“>” and “#”), but may need to be changed if connecting to another type of device (for example “$” for some linux hosts).
connect_telnet(host, username, password, proxy=None, prompt_endings=('#', '>'))

Connects to a device via the Telnet protocol.

Parameters:
  • host (str) – The IP address of DNS name for the device to connect
  • username (str) – The username to login to the device with
  • password (str) – The password that goes with the provided username. If a password is not specified, the user will be prompted for one.
  • proxy (str) – The name of a SecureCRT session object that can be used as a jumpbox to proxy the SSH connection through. This is the same as selecting a session under the “Firewall” selection under the SSH settings screen for a SecureCRT session.
  • prompt_endings (list) – A list of strings that are possible prompt endings to watch for. The default is for Cisco devices (“>” and “#”), but may need to be changed if connecting to another type of device (for example “$” for some linux hosts).
create_new_saved_session(session_name, ip, protocol='SSH2', folder='_imports')

Creates a session object that can be opened from the Connect menu in SecureCRT.

Parameters:
  • session_name (str) – The name of the session
  • ip (str) – The IP address or hostname of the device represented by this session
  • protocol (str) – The protocol to use for this connection (TELNET, SSH1, SSH2, etc)
  • folder (str) – The folder (starting from the configured Sessions folder) where this session should be saved.
disconnect(command='exit')

Disconnects the main session used by the script by calling the disconnect method on the session object.

Parameters:command (str) – The command to be issued to the remote device to disconnect. The default is ‘exit’
file_open_dialog(title, button_label='Open', default_filename='', file_filter='')

Prompts the user to select a file that will be processed by the script. In SecureCRT this will give a pop-up file selection dialog window, and will return the full path to the file chosen.

Parameters:
  • title (str) – Title for the File Open dialog window (Only displays in Windows)
  • button_label (str) – Label for the “Open” button
  • default_filename (str) – If provided a default filename, the window will open in the parent directory of the file, otherwise the current working directory will be the starting directory.
  • file_filter (str) – Specifies a filter for what type of files can be selected. The format is: <Name of Filter> (.<extension>)|.<extension>|| For example, a filter for CSV files would be “CSV Files (.csv)|.csv||” or multiple filters can be used: “Text Files (.txt)|.txt|Log File (.log)|.log||”
Returns:

The absolute path to the file that was selected
Return type:

str
message_box(message, title='', options=0)

Prints a message for the user. In SecureCRT, the message is displayed in a pop-up message box with a variety of buttons, depending on which options are chosen. The default is just an “OK” button.

This window can be customized by setting the “options” value, using the constants listed at the top of the sessions.py file. One constant from each of the 3 categories can be OR’d (|) together to make a single option value that will format the message box.

Parameters:
  • message (str) – The message to send to the user
  • title (str) – Title for the message box
  • options (int) – Sets the display format of the messagebox. (See Message Box constants in sessions.py)
Returns:

The return code that identifies which button the user pressed. (See Message Box constants)
Return type:

int
prompt_window(message, title='', hide_input=False)

Prompts the user for an input value. In SecureCRT this will open a pop-up window where the user can input the requested information.

The “hide_input” input will mask the input, so that passwords or other senstive information can be requested.

Parameters:
  • message (str) – The message to send to the user
  • title (str) – Title for the prompt window
  • hide_input (bool) – Specifies whether to hide the user input or not. Default is False.
Returns:

The value entered by the user
Return type:

str

DebugScript Class

class securecrt_tools.scripts.DebugScript(full_script_path)

Bases: securecrt_tools.scripts.Script

This class is a sub-class of the Script base class, and is meant to be used in any scripts that are being executed directly from a local python installation. This sub-class is designed to simulate the interaction with SecureCRT while the script is being run from a local python installation. For example, when a script attempts to create a pop-up message box in SecureCRT, this class will simply print the information to the console (or request information from the user via the console).

This class inherits the methods from the Script class that are documented above, and is required to implement all of the abstract classes defined in the Script class. This way, it is a complete replacement for the CRTScript class if a script is run directly.

connect(host, username, password, protocol=None, proxy=None, prompt_endings=('#', '>'))

Pretends to connect to a device. Simply marks the state of the session as connected. Never fails.

Parameters:
  • host (str) – The IP address of DNS name for the device to connect
  • username (str) – The username to login to the device with
  • password (str) – The password that goes with the provided username. If a password is not specified, the user will be prompted for one.
  • protocol (str) – A string with the desired protocol (telnet, ssh1, ssh2, ssh). If left blank it will try all starting with SSH2, then SSH1 then Telnet. “ssh” means SSH2 then SSH1.
  • proxy (str) – The name of a SecureCRT session object that can be used as a jumpbox to proxy the SSH connection through. This is the same as selecting a session under the “Firewall” selection under the SSH settings screen for a SecureCRT session.
  • prompt_endings (list) – A list of strings that are possible prompt endings to watch for. The default is for Cisco devices (“>” and “#”), but may need to be changed if connecting to another type of device (for example “$” for some linux hosts).
connect_ssh(host, username, password, version=None, proxy=None, prompt_endings=('#', '>'))

Pretends to connect to a device via SSH. Simply tracks that we are now connected to something within this session (this method never fails).

Parameters:
  • host (str) – The IP address of DNS name for the device to connect
  • username (str) – The username to login to the device with
  • password (str) – The password that goes with the provided username. If a password is not specified, the user will be prompted for one.
  • version (int) – The SSH version to connect with (1 or 2). Default is None, which will try 2 first and fallback to 1 if that fails.
  • proxy (str) – The name of a SecureCRT session object that can be used as a jumpbox to proxy the SSH connection through. This is the same as selecting a session under the “Firewall” selection under the SSH settings screen for a SecureCRT session.
  • prompt_endings (list) – A list of strings that are possible prompt endings to watch for. The default is for Cisco devices (“>” and “#”), but may need to be changed if connecting to another type of device (for example “$” for some linux hosts).
connect_telnet(host, username, password, proxy=None, prompt_endings=('#', '>'))

Pretends to connect to a device via the Telnet protocol, just like connect_ssh above. Never fails.

Parameters:
  • host (str) – The IP address of DNS name for the device to connect
  • username (str) – The username to login to the device with
  • password (str) – The password that goes with the provided username. If a password is not specified, the user will be prompted for one.
  • proxy (str) – The name of a SecureCRT session object that can be used as a jumpbox to proxy the SSH connection through. This is the same as selecting a session under the “Firewall” selection under the SSH settings screen for a SecureCRT session.
  • prompt_endings (list) – A list of strings that are possible prompt endings to watch for. The default is for Cisco devices (“>” and “#”), but may need to be changed if connecting to another type of device (for example “$” for some linux hosts).
create_new_saved_session(session_name, ip, protocol='SSH2', folder='_imports')

Pretends to create a new SecureCRT session. Since we aren’t running in SecureCRT, it does nothing except print a message that a device was created.

Parameters:
  • session_name (str) – The name of the session
  • ip (str) – The IP address or hostname of the device represented by this session
  • protocol (str) – The protocol to use for this connection (TELNET, SSH1, SSH2, etc)
  • folder (str) – The folder (starting from the configured Sessions folder) where this session should be saved.
disconnect(command='exit')

Disconnects the main session used by the script by calling the disconnect method on the session object.

Parameters:command (str) – The command to be issued to the remote device to disconnect. The default is ‘exit’
file_open_dialog(title, button_label='Open', default_filename='', file_filter='')

Prompts the user to select a file that will be processed by the script. In a direct session, the user will be prompted for the full path to a file.

Parameters:
  • title (str) – Title for the File Open dialog window (Only displays in Windows)
  • button_label (str) – Label for the “Open” button
  • default_filename (str) – If provided a default filename, the window will open in the parent directory of the file, otherwise the current working directory will be the starting directory.
  • file_filter (str) – Specifies a filter for what type of files can be selected. The format is: <Name of Filter> (.<extension>)|.<extension>|| For example, a filter for CSV files would be “CSV Files (.csv)|.csv||” or multiple filters can be used: “Text Files (.txt)|.txt|Log File (.log)|.log||”
Returns:

The absolute path to the file that was selected
Return type:

str
message_box(message, title='', options=0)

Prints a message for the user. When used in a DirectSession, the message is printed to the console and the user is prompted to type the button that would be selected.

This window can be customized by setting the “options” value, using the constants listed at the top of the sessions.py file. One constant from each of the 3 categories can be OR’d (|) together to make a single option value that will format the message box.

Parameters:
  • message (str) – The message to send to the user
  • title (str) – Title for the message box
  • options (int) – Sets the display format of the messagebox. (See Message Box constants in sessions.py)
Returns:

The return code that identifies which button the user pressed. (See Message Box constants)
Return type:

int
prompt_window(message, title='', hide_input=False)

Prompts the user for an input value. In a direct session, the user will be prompted at the console for input.

The “hide_input” input will mask the input, so that passwords or other senstive information can be requested.

Parameters:
  • message (str) – The message to send to the user
  • title (str) – Title for the prompt window
  • hide_input (bool) – Specifies whether to hide the user input or not. Default is False.
Returns:

The value entered by the user
Return type:

str
ssh_in_new_tab(host, username, password, prompt_endings=('#', '>'))

Pretends to open a new tab. Since this is being run directly and no tabs exist, the function really does nothing but return a new Session object.

Parameters:
  • host (str) – The IP address of DNS name for the device to connect (only for API compatibility - not used)
  • username (str) – The username to login to the device with (only for API compatibility - not used)
  • password (str) – The password that goes with the provided username. If a password is not specified, the user will be prompted for one. (only for API compatibility - not used)
  • prompt_endings (list) – A list of strings that are possible prompt endings to watch for. The default is for Cisco devices (“>” and “#”), but may need to be changed if connecting to another type of device (for example “$” for some linux hosts). (only for API compatibility - not used)

Script Class Exceptions:

exception securecrt_tools.scripts.ScriptError

An exception type that is raised when there is a problem with the main scripts, such as missing settings files.

exception securecrt_tools.scripts.ConnectError

An exception type that is raised when there are problems connecting to a device.