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 base642$ icon-plugin build image3INFO[0000] Building image base64:1.1.14INFO[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 base642$ icon-plugin build tarball3INFO[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
Command | Description |
---|---|
icon-plugin generate help | Generate help |
icon-plugin generate help > help.md | Help 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
Command | Description |
---|---|
icon-plugin 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 page for more detail. Below are a few examples.
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:
1curl -d @tests/forward.json http://127.0.0.1:10001/actions/forward2curl -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 base642$ icon-plugin export3INFO[0000] Running Command: docker build --pull -t rapid7/base64:1.1.1 .4...5INFO[0010] Building tag6INFO[0010] Running Command: docker tag rapid7/base64:1.1.1 rapid7/base64:latest7INFO[0010] Building plugin tarball rapid7_base64_1.1.1.tar8INFO[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.json2$ tools/json_to_spec.py ifconfig.json3types: {}45output:6city:7description: ENTER DESCRIPTION8title: ENTER TITLE9type: string10hostname:11description: ENTER DESCRIPTION12title: ENTER TITLE13type: string14ip:15description: ENTER DESCRIPTION16title: ENTER TITLE17type: string18country_iso:19description: ENTER DESCRIPTION20title: ENTER TITLE21type: string22ip_decimal:23description: ENTER DESCRIPTION24title: ENTER TITLE25type: integer26country:27description: ENTER DESCRIPTION28title: ENTER TITLE29type: string
You can then copy and paste the output into your plugin spec rather than having to type it out manually.