Insight Orchestrator Overview

The Insight Orchestrator is a server in your network or cloud environment that integrates your tools and systems with InsightConnect.

When a workflow is running, the Insight Cloud keeps the overall workflow logic and data that is generated from each step. When a step is set to run on an Orchestrator, the Insight Cloud delivers the input data and action instructions to the Orchestrator. The Orchestrator executes the action and passes the data output back up to the Insight Cloud. The Insight Cloud then proceeds to the next step in the workflow.

Credentials used in your connections are encrypted on the Orchestrator itself.

The Orchestrator uses Docker containers to run individual plugins. While you may log into the Orchestrator to view and manage these Docker containers, it is not necessary and is not advisable unless you have been directed to do so by the Rapid7 support team.

Centos 7 Orchestrator End-of-Life

The CentOS 7 Insight Orchestrator is reaching end-of-life in June 2024, meaning that it will no longer receive security updates or patches. Rapid7 highly recommends that you install the new Ubuntu Orchestrator. If you have existing CentOS 7 Orchestrators in your environment, you can follow the steps to Migrate an Orchestrator.

Orchestrator Installation

Decide which installation method works best for you:

Orchestrator Placement

When deploying your Orchestrator host, consider what you will need to integrate with InsightConnect. Your Orchestrator should be placed in a central location that can easily communicate with on-premise systems such as Active Directory, InsightVM, firewall management consoles, etc. The Orchestrator should also be able to communicate with cloud platforms like Microsoft Office 365, endpoint detection and response platforms, threat intelligence platforms, and of course the Insight Cloud.

Orchestrator Security

The Orchestrator has been designed to securely communicate with the Insight Cloud and to securely store sensitive connection configurations, including credentials. Every Orchestrator generates two pairs of private and public keys for communication with the cloud.

  • The first credential pair is for encryption and decryption of credentials
  • The second credential pair is for generic elliptic curve signatures to sign and verify the requests

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 encrypted in-transit via TLS and are 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—meaning the encrypted credential cannot be decrypted anywhere except locally on your Orchestrator.

The encrypted credentials are sent from the Insight Cloud to the Orchestrator on an as-needed basis to execute an action in a workflow. 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.

New Credentials

Each time you create a new credential, it’s encrypted once for every orchestrator you have currently registered, even if that orchestrator is not yet configured to use 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 re-enter them.

However, because we can’t reshare credentials without your express intervention by re-entering them, any orchestrators you add after entering a credential don’t have access to that credential.

Credentials and resetting 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 Insight Cloud has no ability 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 in InsightConnect or navigate to Data Collection > Orchestrators from the Insight Platform Home. 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.