Create Custom Plugins

You can extend InsightConnect’s capabilities by building your own plugins or contributing to existing plugins. This lets you:

  • Create new plugins with new triggers and actions
  • Add triggers and actions to existing plugins
  • Connect your InsightConnect workflows to your internal services
  • Connect to other third-party services
  • Change the behavior of existing plugins

InsightConnect plugins are built on REST API design and run within Docker containers (you can learn more about REST APIs here).

We use RESTful design in order to ingest and send data in different types like plain text, JSON, CSV, and RSS. RESTful design best supports how InsightConnect triggers and steps pass variables through a workflow.

Before You Begin

Before you start building your own plugins, we recommend you review the Get Started Guide in the plugins repository.

Please note that plugin development is currently supported for Debian-based and Enterprise Linux distributions as well as MacOS. Microsoft Windows is not currently supported.

You also need to install the following tools in order to build or contribute to InsightConnect plugins. Use the installation instructions provided below or use the package manager (if available) for your operating system or distribution.

ToolInstallation Instructions
Python 3Follow the instructions at https://www.python.org/download/releases/3.0/.
GNU MakeFollow the instructions at https://docs.docker.com/get-started/.
Rapid7 InsightConnect plugin tooling dependenciesRun update-tools.sh from the tools/ directory in the InsightConnect plugins repository. Or use the following below:

Creating the Plugin

For developing plugins, make sure to review the Get Started Guide from the open-source plugin repository on GitHub. If you are planning to modify an existing plugin, you can pull the code for the plugin from that repository.

For existing plugin-specific resources, locate the help.md file in a plugin’s directory. This file contains information on that plugin’s version history, parameters, input and output schemas, connection configuration information, and troubleshooting suggestions.

Plugin Development High Level Steps:

  1. Create Plugin Spec File.
    • Custom plugins cannot have vendor value of rapid7 or komand. If you are modifying an existing plugin, make sure to change this value.
    • Each time you upload a plugin to InsightConnect, you must increment the version of that plugin.
    • Versioning in InsightConnect follows Semantic Versioning down to pre-release versioning. Example: 1.0.1-1 for a bugfix on 1.0.0
  2. Create the Plugin Locally.
    • Be sure to run make
  3. Write the custom code for the plugin’s connection, action(s), and trigger(s).
  4. Test the Plugin Locally.
  5. Run icon-plugin export to export the plugin Docker image.
  6. Upload the generated tar to InsightConnect from within the product UI!
    • Once uploaded the plugin can be used in a similar fashion to a marketplace plugin.
    • This is located under Settings -> Plugins, select Import to go to the Import page.

Custom plugin

  • Next, from Local Drive.

Local drive

  • Drag and Drop or select the tar file, from your window manager, which you exported via icon-plugin export in step 5. Tar file

Contribute to the Custom Plugins Repository

After installing the required tools and developing your plugin you can choose to contribute your changes back to the community!

You can also follow these links to additional resources:

Developer Support

For general questions and requests, reach out to the Rapid7 Integrations team at IntegrationAlliance@rapid7.com.