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

CommandDescription
insight-plugin create plugin.spec.yamlCreate plugin files

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

CommandDescription
insight-plugin refreshRefresh plugin files

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

CommandDescription
insight-plugin samplesGenerate all samples
insight-plugin samples {target_component}Generate a sample for a specific component
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

CommandDescription
insight-plugin run tests/{test}.jsonRuns the test file test.json
insight-plugin run -TRuns the connection test. Uses the first JSON file passed or first in the tests directory.
insight-plugin run tests/test.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
insight-plugin runExecute the test and run methods for all JSON tests
insight-plugin run tests/{test}.json --rebuildRebuild the docker container before running the sample file
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

CommandDescription
insight-plugin serverRun plugin docker container in http mode
insight-plugin server --rebuildRebuild before running plugin docker container in http mode
insight-plugin server -p 80:8080List of ports to expose to other containers and scripts
insight-plugin server -V /Absolute/src:/Absolute/destVolume to mount from local machine to container
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

CommandDescription
insight-plugin shellRuns the plugin in Docker so that it may be accessed locally.
insight-plugin shell -rebuildRebuilds the Docker image before running it in a container and entering the shell.
insight-plugin shell -V /Absolute/src:/Absolute/destVolume to mount from local machine to container
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

CommandDescription
insight-plugin validateValidate / Run checks against the plugin

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

CommandDescription
insight-plugin semver {version_num}Update the plugin versioning

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

CommandDescription
insight-plugin exportExport a plugin Docker image to a tarball
insight-plugin export --no-pullFlag to skip pulling the latest SDK base image during plugin export
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

CommandDescription
insight-plugin viewProvides an overview of the plugin
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.