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 base642❯ make image3[*] Use ``make menu`` for available targets4[*] Including available Makefiles: ../../tools/Makefiles/Colors.mk ../../tools/Makefiles/Helpers.mk5--6[*] Building plugin image7docker 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 base642❯ make tarball3INFO[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
Command | Description |
---|---|
insight-plugin create plugin.spec.yaml | Create 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
Command | Description |
---|---|
insight-plugin refresh | Refresh 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
Command | Description |
---|---|
insight-plugin samples | Generate all samples |
insight-plugin samples {target_component} | Generate a sample for a specific component |
1❯ insight-plugin samples2Samples 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
Command | Description |
---|---|
insight-plugin run tests/{test}.json | Runs the test file test.json |
insight-plugin run -T | Runs the connection test. Uses the first JSON file passed or first in the tests directory. |
insight-plugin run tests/test.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 |
insight-plugin run | Execute the test and run methods for all JSON tests |
insight-plugin run tests/{test}.json --rebuild | Rebuild the docker container before running the sample file |
1❯ insight-plugin run tests/encode.json22023-08-22 14:41:40 [info ] rapid7/Base64:1.1.6. Step name: encode34{"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
Command | Description |
---|---|
insight-plugin server | Run plugin docker container in http mode |
insight-plugin server --rebuild | Rebuild before running plugin docker container in http mode |
insight-plugin server -p 80:8080 | List of ports to expose to other containers and scripts |
insight-plugin server -V /Absolute/src:/Absolute/dest | Volume to mount from local machine to container |
1❯ insight-plugin server2[2023-08-22 14:39:58 +0000] [1] [INFO] Starting gunicorn 20.0.43[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: threads5[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:
1curl -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
Command | Description |
---|---|
insight-plugin shell | Runs the plugin in Docker so that it may be accessed locally. |
insight-plugin shell -rebuild | Rebuilds the Docker image before running it in a container and entering the shell. |
insight-plugin shell -V /Absolute/src:/Absolute/dest | Volume to mount from local machine to container |
1❯ insight-plugin shell2$ pwd3/python/src4$ ls5Dockerfile cisco_umbrella_destinations_rapid7_plugin.egg-info icon.png setup.py6Makefile dist icon_cisco_umbrella_destinations venv7bin extension.png plugin.spec.yaml8build help.md requirements.txt9$
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
Command | Description |
---|---|
insight-plugin validate | Validate / 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
Command | Description |
---|---|
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
Command | Description |
---|---|
insight-plugin export | Export a plugin Docker image to a tarball |
insight-plugin export --no-pull | Flag to skip pulling the latest SDK base image during plugin export |
1❯ cd test_plugin2❯ insight-plugin export3Beginning export..4Export process complete!
View
This subcommand allows a user to get a general overview of a plugin.
insight-plugin view
View Examples
Command | Description |
---|---|
insight-plugin view | Provides an overview of the plugin |
1❯ insight-plugin view2Name: Cisco Umbrella Destinations3Vendor: rapid74Version: 4.0.05Description: Cisco Umbrella Destinations allows users to manage, block, and allow network destinations based on policies within their organization67Actions (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.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.