Plugin Tooling

Introduction

This document describes the available plugin development tooling, with examples.

Tooling

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

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

Icon Plugin

This 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. Typically, this is the first thing you want to do when you’re working on an existing plugin, to make sure it builds successfully.

$ cd base64
$ icon-plugin build image
INFO[0000] Building image base64:1.1.1
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 Komand

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

Generate

The subcommand generate is used to create plugins skeletons. Skeletons that are produced from generate plugins structure, help and samples.

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 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

A key part in a plugin is the help.md file. 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
Command Description
icon-plugin generate help Generate Help
icon-plugin generate help > help.md Help redirect

To test a plugin, samples will be needed. When a sample is generates it will be create a JSON file that contains the parameters expected by the plugin.

Sample Examples
Command Description
icon-plugin generate sample --sample action or trigger name Generate a sample
icon-plugin generate samples Generate 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 document for more detail. A few examples are presented below.

Run Examples
Command Description
icon-plugin run -c info Display plugin information
icon-plugin run -R tests/submit.json -j Execute the run method on the submit JSON test
icon-plugin run -R tests/submit.json -A Execute 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 -j Execute 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:

curl -d @tests/forward.json http://127.0.0.1:10001/actions/forward
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.

$ cd base64
$ icon-plugin export
INFO[0000] Running Command: docker build --pull -t rapid7/base64:1.1.1 .
...
INFO[0010] Building tag
INFO[0010] Running Command: docker tag rapid7/base64:1.1.1 rapid7/base64:latest
INFO[0010] Building plugin tarball rapid7_base64_1.1.1.tar
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 which converts a JSON object to Komand plugin spec data. It takes a path to a file containing JSON as an argument. It’s located in the open-source plugins repo.

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

output:
  city:
    description: ENTER DESCRIPTION
    title: ENTER TITLE
    type: string
  hostname:
    description: ENTER DESCRIPTION
    title: ENTER TITLE
    type: string
  ip:
    description: ENTER DESCRIPTION
    title: ENTER TITLE
    type: string
  country_iso:
    description: ENTER DESCRIPTION
    title: ENTER TITLE
    type: string
  ip_decimal:
    description: ENTER DESCRIPTION
    title: ENTER TITLE
    type: integer
  country:
    description: ENTER DESCRIPTION
    title: ENTER TITLE
    type: string

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