Insight Orchestrator overview

The Insight Orchestrator unlocks the ability for you to execute automated workflows inside your network. The orchestrator is an important part of the SOAR experience on the Insight Platform. Most InsightConnect workflows require an orchestrator to run, so familiarizing yourself with the tool, its specifications, and how it works is important for long-term success.

Orchestrator installation

Using a CentOS 7 .ova file or a self-extracting installer script, you install the orchestrator in your environment to provide access to on-premises products, services, and tools. If you have these across different networks, you’ll need to install an orchestrator on each network.

The orchestrator acts as an execution proxy for InsightConnect plugins, which are hosted in Docker containers, so every installation of the orchestrator also requires an installation of Docker to be co-resident on the OS. The initial installation of your orchestrator also handles Docker installation for you.

Orchestrator credentials

When provisioning an orchestrator, one of the first things it does is generate 2 pairs of private and public keys for communication with the cloud.

  • The first pair are for encryption and decryption of credentials, and are the ones we’ll be primarily discussing in this section.
  • The second pair are for generic elliptic curve signatures to sign and verify the requests. We discuss these keys and their purpose more in the Orchestrator-to-cloud communication section.

Credentials that you enter into InsightConnect, or other Insight products that rely on InsightConnect for automation functionality, are managed securely end-to-end. Initially, they are transmitted by your session to our backend over TLS, and they’re stored encrypted at rest in our systems using a public key that’s generated by the Orchestrator and sent to the cloud. (The private key never leaves the orchestrator.)

There are typically 4 types of credentials:

  • Username and password
  • Shared secret
  • Domain token
  • Asymmetric key

These types differ in terms of the shape of data that’s expected, and how our backend understands them. For this explanation, you can think of them as different types of credentials for different systems, but handled uniformly from the perspective of the orchestrator.

Credentials are sent on an as-needed basis to the orchestrator with the incoming request to kickoff an action from the cloud. They are then decrypted in memory and passed to the plugins directly, where the plugin makes use of the data to connect to a third party system.

Map credentials and orchestrators

It’s good to understand the relationship between orchestrators and credentials so you know how credentials are stored and transferred. This knowledge can also help you manage your orchestrators and troubleshoot any credential-related issues later on.

Each time you store a credential, it’s encrypted once for every orchestrator you have currently registered, even if that orchestrator is not yet configured to need that credential. This is done because once it’s encrypted, we lose the ability to make it available to any other orchestrator you may want to use it with later on. In this way, we make it slightly easier to reuse credentials between orchestrators without having to constantly reenter them.

However, because we can’t reshare credentials without your express intervention by reentering them, any orchestrators you add after entering a credential don’t have access to that credential. To get around this, you would need to recreate the credential with the same information after you register the new orchestrator.

Credentials and reset orchestrators

If you reset an orchestrator, you’ll lose access to the credentials from the cloud unless you registered at least one other orchestrator prior to you entering the credentials the first time. This is because you’ve severed the tie between the orchestrator and credentials that was created when you entered the credentials initially. This is why you shouldn’t reset an orchestrator unless you’re advised to do so by a support representative.

Orchestrator-to-cloud communication

The Insight Orchestrator routinely communicates with InsightConnect servers in our cloud. Communication is always initiated in a single direction, orchestrator to cloud, and never the other way around. The InsightConnect servers have no capability to directly communicate with the orchestrator installed on your environment.

These are the situations in which the orchestrator communicates with the cloud:

  • Heartbeat data: The orchestrator sends heartbeat data to inform the cloud that it’s still working and able to receive work. Heartbeat calls contain some metadata about the orchestrator and its health to help us support your orchestrator installations. The heartbeat call also returns a challenge token, which is used to sign requests. So if an orchestrator cannot send heartbeat data, it’s unable to communicate further with the cloud.
  • Work requests: The orchestrator requests work to be done by establishing a secure connection over TLS that then includes metadata about the orchestrator to identify it with the cloud. These requests are signed and verified.
  • Work results: Similar to work requests, the orchestrator responds with results from work that was done. These requests are signed and verified.

Orchestrator cards

You can view all of your orchestrators by going to Settings > Orchestrators to access the Orchestrators page. On the Orchestrators page, every orchestrator has a card that acts like a dashboard. These cards display orchestrator data, but also allow you to review the health of an orchestrator or delete any as needed.

Each orchestrator card displays:

  • Total number of events
  • Number of events currently processing
  • Total number of connections
  • CPU usage
  • Memory usage, in bytes
  • Storage usage, in bytes

Orchestrators have five states:

  • Healthy: Orchestrator is active and running properly
  • Warning: Orchestrator is running properly, but may require review
  • Error: Orchestrator is running, but you must review errors and troubleshoot them
  • Stopped: Orchestrator has stopped running
  • Activating: A newly installed orchestrator is activating and will not be available to run until activation completes

InsightIDR and InsightVM automation capabilities

The Insight Orchestrator enables the automation capabilities in InsightIDR and InsightVM. Once you install an orchestrator--whether it's in InsightConnect, InsightVM, or InsightIDR--you can use specific templates and any custom workflows from InsightConnect within InsightVM or InsightIDR.

To enable a workflow for use in other Insight products, the workflow must be activated and must have an Insight Platform Trigger.