InsightConnect Documentation

Creating Custom Plugins

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

  • Add triggers and actions to existing plugins
  • Augment or edit the behavior of existing plugins
  • Create new plugins to connect to your internal services
  • Create new plugins to connect to other third-party services

InsightConnect plugins are designed to integrate with Restful APIs written in Python, and are run by the Orchestrator within Docker containers. For more in Restful API's visit https://restfulapi.net/.

Before You Begin

Before you start building your own plugins, we recommend you review the Getting Started Guide in the plugins repository as well as our Development Documentation.

You also need to install the following tools to build or contribute to InsightConnect plugins:

Tool
Installation Instructions

Python 3

Make

Follow the “Downloading Make” instructions at https://www.gnu.org/software/make/

Docker Engine

Follow the instructions at https://docs.docker.com/get-started/

InsightConnect plugin tooling dependencies: InsightConnect plugin validators, pyyaml, js-yaml, jq, flake8, and mdl

Run update-tools.sh from the tools/ directory in the InsightConnect plugins repository.

Creating the Plugin

For developing plugins, 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.

Then visit our developer documentation for more in-depth resources as you build your plugins.

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 schema, connection configuration information, and troubleshooting suggestions.

For developing a plugin follow the steps below:

  1. Create Plugin Spec File.
    a. Custom Plugins cannot have vendor value of rapid7 or komand. If you are modifying an existing plugin, change the vendor value.
    b. The Plugin version must be incremented with each upload to InsightConnect. Versioning in InsightConnect follows Semantic Versioning (https://semver.org/) 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 .plg to InsightConnect from within the product UI.
    a. Custom Plugin import is found under Settings -> Plugins ->Import -> From Local Drive
    b. Once uploaded, the plugin can be used as a part of a workflow similar to how Plugins from the Marketplace are used.

Contribute to the Custom Plugins Repository

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

You can also follow these quick links to additional resources:

Developer Support

If you have developer questions, you can join the developer mailing list. For general questions and requests, reach out to the Rapid7 Integrations team at IntegrationAlliance@rapid7.com.

Troubleshooting

  • InsightConnect expects to import .tar files created from running an icon-plugin export. If you are attempting to import a legacy tar.gz, it will fail.
  • Custom Plugins cannot have vendor value of rapid7 or komand. If you are modifying an existing plugin,change the vendor value.
  • The Plugin version must be incremented with each upload to InsightConnect. Versioning in InsightConnect follows Semantic Versioning (https://semver.org/) down to pre-release versioning. Example: 1.0.1-1 for a bugfix on 1.0.0

Creating Custom Plugins


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.