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!

Insight Plugin

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

Make

The make command constructs artifacts for plugin development.

Arguments

make 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
❯ make image
3
[*] Use ``make menu`` for available targets
4
[*] Including available Makefiles: ../../tools/Makefiles/Colors.mk ../../tools/Makefiles/Helpers.mk
5
--
6
[*] Building plugin image
7
docker build --pull -t rapid7/base64:1.1.6 .

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

 
1
❯ cd base64
2
❯ make tarball
3
INFO[0000] Building tarball rapid7-base64-1.1.1.tar.gz

Create

The subcommand create creates all the necessary plugin files and directories.

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

insight-plugin create plugin.spec.yaml

Create examples

Refresh

Anytime you modify the plugin spec, use the subcommand refresh 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.

insight-plugin refresh

Refresh Examples

Samples

The samples command is used to create the json test files that we use to test actions and triggers against the plugin docker image. Once you build out the plugin using make or make image, create the json test files using: insight-plugin samples <path/to/specfile>

Sample Examples

 
1
❯ insight-plugin samples
2
Samples process complete!

Run

The subcommand run for insight-plugin allows a user to quickly test and execute plugins from the command-line.

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

Run Examples

 
1
❯ insight-plugin run tests/encode.json
2
2023-08-22 14:41:40 [info     ] rapid7/Base64:1.1.6. Step name: encode
3

4
{"body": {"log": "", "status": "ok", "meta": {}, "output": {"data": "UmFwaWQ3"}}, "version": "v1", "type": "action_event"}

Server

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

insight-plugin server

Server Examples

 
1
❯ insight-plugin server
2
[2023-08-22 14:39:58 +0000] [1] [INFO] Starting gunicorn 20.0.4
3
[2023-08-22 14:39:58 +0000] [1] [INFO] Listening at: http://0.0.0.0:10001 (1)
4
[2023-08-22 14:39:58 +0000] [1] [INFO] Using worker: threads
5
[2023-08-22 14:39:58 +0000] [8] [INFO] Booting worker with pid: 8

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

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

Shell

You can also interact with the plugin via command line by running the plugin and Docker and entering the shell:

insight-plugin shell

Shell Examples

 
1
❯ insight-plugin shell
2
$ pwd
3
/python/src
4
$ ls
5
Dockerfile  cisco_umbrella_destinations_rapid7_plugin.egg-info	icon.png			  setup.py
6
Makefile    dist						icon_cisco_umbrella_destinations  venv
7
bin	    extension.png					plugin.spec.yaml
8
build	    help.md						requirements.txt
9
$

Validate

The subcommand validate will run validation against the plugin, ensuring that all files including schema, plugin.spec.yaml and help.md are valid to the constraints applied by InsightConnect.

insight-plugin validate

Validate Examples

Semver

The subcommand semver will update the plugin files to a newly specified version as supplied as an argument in semantic versioning format.

insight-plugin semver 1.0.1

Semver Examples

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.

insight-plugin export

Export Examples

 
1
❯ cd test_plugin
2
❯ insight-plugin export
3
Beginning export..
4
Export process complete!

View

This subcommand allows a user to get a general overview of a plugin.

insight-plugin view

View Examples

 
1
❯ insight-plugin view
2
Name:        Cisco Umbrella Destinations
3
Vendor:      rapid7
4
Version:     4.0.0
5
Description: Cisco Umbrella Destinations allows users to manage, block, and allow network destinations based on policies within their organization
6

7
Actions (10):
8
└── dAdd (Add a destination to the destination list)
9
└── dDelete (Delete a list of destinations from a destination list)
10
└── dGet (Get a list of destinations related to a destination list)
11
└── dlCreate (Create a destination list)
12
└── dlDelete (Delete a destination list)
13
└── dlFilterAll (Filter and Retrieve all destination lists of organization)
14
└── dlGet (Get a destination list)
15
└── dlGetAll (Retrieve all destination lists of organization)
16
└── dlGetByName (Get destination list by name)
17
└── dlPatch (Rename a destination list)

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.