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

CommandDescription
icon-plugin generate helpGenerate help
icon-plugin generate help > help.mdHelp redirect

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

CommandDescription
icon-plugin sample --sample action or trigger nameGenerate a sample
icon-plugin generate samplesGenerate all samples

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

CommandDescription
icon-plugin run -c infoDisplay plugin information
icon-plugin run -R tests/submit.json -jExecute the run method on the submit JSON test
icon-plugin run -R tests/submit.json -AExecute the run method on the submit JSON test file for a printed assessment to post in a PR on our open-source Github repository
icon-plugin run -T all -R all -jExecute the test and run methods for all JSON tests

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.