Multi-environment orchestration allows ThreatConnect® users that have an Environment Server behind a firewall to use their instance to communicate with that server and run applications inside their firewall. The Playbooks Environments screen provides information to Organization Administrators and higher on the Environments available to their ThreatConnect instance and allows them to administrate the Environments from within their instance. See Multi-Environment Orchestration: Executing Playbook Apps Through a Firewall for information about how users can execute Playbook Apps remotely.
The Playbook Environments Screen
On the top navigation bar (Figure 1), click PLAYBOOKS to display the Playbooks screen (Figure 2).
Click on the Environments tab at the top left of the screen, and the Environments screen will appear, displaying all available Environments for the Organization Administrator's Organization (Figure 3).
NOTE: This screen may also be accessed by clicking on the Settings icon on the top navigation bar, selecting ORG SETTINGS, clicking the Apps tab, clicking on the vertical ellipsis menu at the top right, and selecting the Environments option.
If no Environments have been configured for the Organization, then it will look like the screen in Figure 4.
The top part of an Environment will be green if the environment is active and configured to an Environment Server; yellow if the Environment is active, but not configured to an Environment Server; and gray if the Environment is inactive.
NOTE: Active and configured environments will initially display with a yellow top. The top will turn green as the ThreatConnect instance communicates with the Environment Server and recognizes the Environment as configured. Depending on how quickly that communication occurs, there may be a bit of a delay before the top turns green.
The box for an Environment provides several types of information:
- Executions Today: the number of executions that have occurred on the Environment on the present day.
- Queue Size: the number of items in the queue waiting for execution on the Environment.
- Dependent Playbooks: the number of Playbooks that are dependent on the Environment (i.e., that have an App that is configured to run on the given Environment).
- Dependent Jobs: the number of Jobs (Playbooks and other applications) that are dependent on the Environment (i.e., that are configured to run on the given Environment).
- Owner: the Organization that owns the Environment.
- Environment Server: the name of the Environment Server that is attached to the configuration represented by the given Environment box.
- Remote Workers: the number of Workers available on the Environment Server. See Playbook Activity for more information about Workers.
Activating an Environment
Toggle the Active slider at the bottom right of an Environment to switch it between active and inactive.
Editing, Viewing, and Downloading an Environment
- Click on the vertical ellipsis icon at the top right of an Environment, and a menu with the following options will appear: Edit Name, View, and Download.
- To edit the name of an Environment, select the Edit Name option from the vertical ellipsis menu. The Edit Environment window will appear (Figure 5).
- Enter a new name for the Environment, and then click the SAVE button.
- To view an Environment (that is, to view the administration page for the Environment, which provides information about the Environment in real time), select the View option from the vertical ellipsis menu, or click on the name of the Environment at the top of the box. The Environments tab will now show the administration page for the Environment (Figure 6). To return to the view in Figure 3, refresh the screen.
NOTE: When this screen is first loaded, there may be a short delay before all of the information appears.
- To download an Environment, select the Download option from the vertical ellipsis menu. A window will appear from which the following Download options can be selected from a dropdown menu: Download Bundle (All-in-one), Environment Config Only, and Environment Server Only. The Download Bundle (All-in-one) option includes both the Environment Config and the Environment Server as well as the KeyStore files required to make a secure connection to the host ThreatConnect instance. Make a selection and then click the DOWNLOAD button.
Configuring an Environment Server
Follow these steps to configure an Environment Server to an Environment:
- Ensure that the ThreatConnect Environment Server system requirements are met. In particular, Java® 8 (Java Development Kit version 1.8) must be installed locally on the user’s computer.
- Download the All-in-one Bundle from an Environment. See Step 5 and Figure 7 in the previous section.
- The name of the downloaded file will be environment-server-bundle.zip. Unzip the file from the command-line interface with the following command:
- Use the following command to change to the Environment Server directory:
- If desired, view the README file with the following command:
- Enter the following commands:
chmod +x ./run.sh
- When prompted, create and enter a Master Password. This password will be used to encrypt all keychain variables in a secure vault.
- In the ThreatConnect user interface, the top of the Environment from which the bundle was downloaded will turn green, indicating that it has been configured to an Environment Server.
Administrating an Environment
The administration page for an Environment (Figure 6) provides a number of options for viewing details about an Environment and changing aspects of its configuration.
The Environment Statistics section provides statistics on the number of messages per hour received by the Environment, the average amount of time that a job waits in the queue for the Environment before being executed, the roundtrip latency of the Environment [i.e., the amount of time it takes for a roundtrip communication to complete between the host ThreatConnect instance and the Environment Server(s)], and the current size of the queue.
The Environment Details section provides information on the Environment, including the number of Playbooks that reference it (i.e., Dependent Playbooks from the box view in Figure 3), the number of Jobs that reference it (i.e., Dependent Jobs from the box view in Figure 3), the name of the command queue used by the Environment (i.e., the queue for all requests to the host ThreatConnect instance), the name and size of the response queue used by the Environment (i.e., the queue for all responses from Environment Servers), and information about the number of executions on the Environment during the current day and over the previous week and month.
To view a list of all Playbooks using the Environment, click on the number next to Playbook References. The Playbooks using <Environment Name> window will appear with a list of all Playbooks using the Environment and whether each Playbook is active or inactive (Figure 8). The name of each Playbook is a link to the Playbook in the Playbook Designer.
To view a list of all Jobs using the Environment, click on the number next to Job References. The Jobs using <Environment Name> window will appear with a list of all Jobs using the Environment and whether each Job is active or inactive (Figure 9).
Recent App Executions
The Recent App Executions section lists details about the Jobs that have been executed recently on the Environment.
If an Environment Server has been configured to the environment, the Environment Servers section will display version, hardware, memory, and other information about the Environment Server:
- The colored strip on the left of this section will be green if the Environment Server is running. The strip will be red if the Environment Server is shut down or in the process of restarting.
NOTE: When this screen is first loaded, there may be a short delay in which the strip will be red even if the Environment Server is running, after which it will turn green.
- Name: the name of the Environment Server.
- Version: the version of the Environment Server. Version 1.2.x operates on instances of ThreatConnect that are at version 5.6 or older. Version 2.0.x operates on instances of ThreatConnect that are at version 5.7 or newer.
- Machine ID: the unique identification number of the machine on which the Environment Server operates.
- Agent Status: The color of the circle indicates whether the Environment Server is configured to the Environment. It will typically be green, even when the Environment Server is shut down or restarting, indicating that the Environment Server remains configured to the Environment regardless of the Environment Server’s status. It will turn red if the agent fails or loses connectivity from the remote network.
NOTE: When this screen is first loaded, there may be a short delay in which the circle will be red, after which it will turn green. The delay for the circle’s color change may be slightly longer than the delay for the colored strip’s color change.
- CPU, 24h Peak CPU, 24h Peak Memory, Disk Usage, and Memory: statistics on the hardware and memory capacities of the Environment Server.
- Remote Workers: the number of Workers allocated to the Environment Server. See Playbook Activity for more information on Workers. Click the pencil next to this section to change the number of Workers allocated to the Environment Server.
- Running Tasks: a list of the apps that are currently running on the Environment Server and the amount of time for which they have been running.
Use the vertical ellipsis menu at the top right of the Environment Servers section to shut down, start up, restart, or delete the Environment Server (Figure 10).
If an Environment Server is running, then only the Shutdown and Restart options will be available, as in Figure 10. If the Server has been shut down, then only the Start Up and Delete options will be available.
Command-Line Configuration of an Environment Server
The command-line interface provides options for viewing, editing, and exporting system configuration values and viewing, editing and deleting keychain variables for an Environment Server:
NOTE: The Environment Server must first be shut down (see Figure 10 in the previous sub-section, “Environment Servers”) in order to use the command-line interface administration options.
- Use the following command to change to the Environment Server directory:
- Enter the following command to initiate configuration mode:
- The following menu will appear:
Please select an option:
1: System Configuration
- The System Configuration menu provides a sub-menu with the following options:
System Configuration: Please select an option:
1: List all System Config
2: Edit System Config
3: Export Configuration
4: Go Back
- Selecting List all System Config lists all system configuration values. Selecting Edit System Config allow the user to select a system configuration value and replace its value with a new one. Selecting Export Configuration allows the user to export the system configuration. Table 1 provides a description of each system configuration value.
System Configuration Value Description apiURL This setting should point to the URL for the API at port 8443 (e.g., https://api.threatconnect.com:8443). appDeliveryToken This setting is the token that is used to authenticate with the App Catalog Server. appsJavaHome This setting holds the path to the Java binary. appsNumberofJobExecutors This setting is the number of Job Executors that can run concurrently. It is a factor of the number of CPUs and the available memory on the server. It should not exceed available resources. appsPythonHome This setting holds the path to the Python® binary. appsSandboxUser This setting represents the user account used to execute Jobs. It is pertinent only in Linux® installs. appsSessionDaystoKeep This setting is placed at 5 in Cloud. It indicates the number of days that logs will be kept in the Jobs log directory: %threatconnect%/exchange/jobs. brokerHost This setting is the remote host name of the messaging server to which the Environment Server will connect. brokerToken This setting is the secure key used to authenticate a connection to the remote message broker. proxyExternal This setting is set to true when all external connections for apps should be routed through a proxy server. proxyHost This setting is the proxy host to use if a proxy server is required. Acceptable values are a valid IP address or host name for a proxy accessible by the ThreatConnect instance. proxyPassword This setting is the proxy password to use if a proxy server requires authentication. proxyPort This setting is the proxy port to use if a proxy server is required. Enter a valid proxy port number. proxyTC This setting is set to true when all connections to the ThreatConnect host server should be routed through a proxy server. proxyUsername This setting is the proxy username to use if a proxy server requires authentication. relaySystemInfoPublishSeconds The frequency at which to notify the remote ThreatConnect instance of the status of the Environment Server. serverName The name of the Environment Server to display on the ThreatConnect Environments screen and administration page. serverXid This setting is a static number that uniquely identifies the given Environment Server. Its value should not be changed.
- The Variables menu provides a sub-menu with the following options:
Variables: Please select an option:
1: List all Variables
2: Create a Variable
3: Delete a Variable
4: Go Back
- Selecting List all Variables lists all keychain variables for the Environment. Selecting Create a Variable allows the user to create a keychain variable for the Environment. Selecting Delete a Variable allows the user to delete a variable from the Environment.
- The Exit option causes the command-line interface to exit from the Environment Server configuration.
When the number of Apps and Jobs that are being remotely executed is larger than the number of available Workers, the remaining Apps are put into a queue. Use the vertical ellipsis menu at the top right of the screen to pause, resume, and flush the queue (Figure 11).
Click the Settings icon at the top right of the screen to view the Environment Settings window (Figure 12).
The Environment Settings window lists all remote variables defined for the Environment. The trash can icon can be used to delete a listed variable.
NOTE: Clicking the trash can icon immediately deletes the variable without prompting the user for confirmation.
To add a variable, click the ADD VARIABLE button. The Create Remote Variable window will appear (Figure 13).
Enter the Name of a keychain variable that has been defined via the command-line configuration options for the Environment Server (see the “Command-Line Configuration of an Environment Server” sub-section earlier in this article), and then click the SAVE button. The variable will then appear in the corresponding keychain list for Playbook Apps running on the Environment.
The DOWNLOAD CONFIGURATION button in the Environment Settings window (Figure 12) allows the user to download the configuration file for the environment.
Linux® is a registered trademark of Linus Torvalds.
Java® is a registered trademark of the Oracle Corporation.
Python® is a registered trademark of the Python Software Foundation.