Plugin Tooling

The tooling is intended to be used to develop new or existing plugins.

Tooling

You can find a list of open-source plugins to reference, add a new feature, or fix a bug. We welcome and encourage pull requests!

Icon Plugin

This is the main tool for developing plugins. Installation instructions for icon-plugin is available in the Getting Started document.

Build

The subcommand build constructs artifacts for plugin development.

Arguments

image is used to package the plugin code into a Docker image which makes it available to run. This is typically the first thing you want to do when you’re working on an existing plugin to ensure it builds successfully.

 
1
$ cd base64
2
$ icon-plugin build image
3
INFO[0000] Building image base64:1.1.1
4
INFO[0000] Running Command: docker build --pull -t rapid7/base64:1.1.1 .

tarball is used to build a tarball of the plugin. This is used for backward-compatible testing in InsightConnect.

 
1
$ cd base64
2
$ icon-plugin build tarball
3
INFO[0000] Building tarball rapid7-base64-1.1.1.tar.gz

Generate

The subcommand generate creates plugins skeletons.

It can be used to generate a new plugin from a plugin spec (Plugin Spec) with the path of the spec as an argument.

icon-plugin generate --regenerate python plugin.spec.yaml

Anytime you modify the plugin spec, use the subcommand generate with the --regenerate flag to rebuild the skeleton with the new schema without compromising previously written code. This makes adding actions and updating the plugin spec simple and fast.

icon-plugin generate --regenerate python plugin.spec.yaml

The help.md file is a key part in a plugin. This gives basic information and usage about the plugin. When running the command below, the help is output to stdout. If help.md is missing, use a redirect to help.md to create the base for help.

Help Examples

You will need samples to test a plugin. When a sample is generated it will create a JSON file that contains the parameters expected by the plugin.

Sample Examples

Run

The subcommand run in version 3.3.0 =< for icon-plugin aids in quickly testing and executing plugins from the command-line. It includes all functionality from the legacy runner that’s generated with make.

See the Running Plugins page for more detail. Below are a few examples.

Run Examples

HTTP Server

You can also interact with the plugin over HTTP when it's in REST mode:

icon-plugin run -c http

Then you can hit its run or test endpoint with a web request containing the JSON input as payload:

 
1
curl -d @tests/forward.json http://127.0.0.1:10001/actions/forward
2
curl -d @tests/forward.json http://127.0.0.1:10001/actions/forward/test

Export

The subcommand export will export the Docker image as a .tar file which you can import into InsightConnect. The output of this command is what you will import into InsightConnect as a Custom Plugin to begin using it. Note that this command will build the plugin first before exporting it.

 
1
$ cd base64
2
$ icon-plugin export
3
INFO[0000] Running Command: docker build --pull -t rapid7/base64:1.1.1 .
4
...
5
INFO[0010] Building tag
6
INFO[0010] Running Command: docker tag rapid7/base64:1.1.1 rapid7/base64:latest
7
INFO[0010] Building plugin tarball rapid7_base64_1.1.1.tar
8
INFO[0010] Running Command: docker save rapid7/base64:1.1.1 -o rapid7_base64_1.1.1.tar

JSON to Spec

A script called json_to_spec.py converts a JSON object to InsightConnect plugin spec data. It takes a path to a file containing JSON as an argument. It’s located in the open-source plugins repo.

 
1
$ curl -s https://ifconfig.co/json > ifconfig.json
2
$ tools/json_to_spec.py ifconfig.json
3
types: {}
4

5
output:
6
  city:
7
    description: ENTER DESCRIPTION
8
    title: ENTER TITLE
9
    type: string
10
  hostname:
11
    description: ENTER DESCRIPTION
12
    title: ENTER TITLE
13
    type: string
14
  ip:
15
    description: ENTER DESCRIPTION
16
    title: ENTER TITLE
17
    type: string
18
  country_iso:
19
    description: ENTER DESCRIPTION
20
    title: ENTER TITLE
21
    type: string
22
  ip_decimal:
23
    description: ENTER DESCRIPTION
24
    title: ENTER TITLE
25
    type: integer
26
  country:
27
    description: ENTER DESCRIPTION
28
    title: ENTER TITLE
29
    type: string

You can then copy and paste the output into your plugin spec rather than having to type it out manually.