Running Plugins
Copy link

The following describes how to run plugins and continues using the example plugin from Plugin Spec.

insight-plugin Tooling
Copy link

More documentation for insight-plugin can be found at Plugin Tooling

About insight-plugin
Copy link

  • The best tooling of the methods
  • The insight-plugin tool is the primary plugin development tool that should be used to administrate any plugin
  • Installation instructions for insight-plugin is available in the Getting Started document.

Running and Testing Your Plugin
Copy link

Now that your plugin shell has been built, let’s play around with some of the plugin commands that come code-generated with the plugin shell.

Help Command
Copy link

To see what commands your plugin executable supports, try running:

$ insight-plugin run --help usage: insight-plugin run [-h] [-A] [-T] [-J [JQ]] [-R] [-V VOLUMES [VOLUMES ...]] [-d TARGET_DIR] [-v] [json_target] positional arguments: json_target .json files to run optional arguments: -h, --help show this help message and exit -A, --assessment Flag to generate plugin PR template output for contributions -T, --test Run connection test. Uses first json file passed, or first in tests directory. -J [JQ], --jq [JQ] JQ Parser. Pass no args to use default (.body.output), or pass one used for all test/runs. -R, --rebuild Rebuild the Docker image before running it in a container and entering the shell -V VOLUMES [VOLUMES ...], --volumes VOLUMES [VOLUMES ...] Volume to mount from local machine to container, e.g. /Absolute/src:/Absolute/dest -d TARGET_DIR, --target-dir TARGET_DIR Provide plugin directory -v, --verbose Verbose Mode

Info/View Command
Copy link

The view command will print plugin metadata.

insight-plugin view Name: Base64 Vendor: rapid7 Version: 1.1.6 Description: Encode and decode data using the base64 alphabet Actions (2): └── decode (Decode Base64 to data) └── encode (Encode data to Base64)

Test Command
Copy link

You can use the test command to test your connection by running the test() method in the action/trigger file, unless there is a test method in the connection file. Note that test() should be set in the connection and not in the action or trigger. Often it’s used to test network access and validate any user provided credentials.

For this example, we will make the following code changes to insight_plugin_example/actions/test_action/action.py and then rebuild with make:

def test_action(self): self.logger.info('Saying goodbye to %s', 'test') return { 'message': 'Goodbye test!' }

Test
Copy link

Run plugin’s test method using insight-plugin:

$ insight-plugin run -T tests/test_action.json INFO: RunController: Running connection test with /Users/insight-user/insight-connect/example_insight_plugin/tests/test_action.json INFO: RunContoller: Running command: docker run --rm -i rapid7/example_insight_plugin:1.0.0 test < /Users/insight-user/insight-connect/example_insight_plugin/tests/test_action.json Connect: Connecting... rapid7/Example Insight Plugin:1.0.0. Step name: test_action

Run Command
Copy link

The run command is used to run your plugin by executing the run() method in the action/trigger file. When developing, please make sure you run your plugin with the --verbose flag so that all output is displayed to stdin/stdout.

Note: --verbose is special for testing triggers from the command-line and must be used to bypass the URL callback.

For this example, we made the following code changes to icon_example/actions/say_goodbye/action.py and then rebuild with make:

def run(self, params={}): name = params.get(Input.NAME) self.logger.info(f'Saying goodbye to {name}') message = f'Goodbye {name}!' return {'message': message}

Execute All Runs and Tests
Copy link

To run all actions and triggers instead of choosing a specific file.

$ insight-plugin run INFO: RunController: Running /Users/insight-user/insight-connect/example_insight_plugin//tests/test_1.json INFO: RunController: Running command: docker run --rm -i rapid7/test_insight_plugin:1.0.0 run < /Users/insight-user/insight-connect/example_insight_plugin//tests/test_1.json Connect: Connecting... rapid7/Test Insight Plugin:1.0.0. Step name: test_action Output is: {'body': {'log': 'Connect: Connecting...\nrapid7/Example Insight Plugin:1.0.0. Step name: test_action\n', 'status': 'ok', 'meta': {}, 'output': {}}, 'version': 'v1', 'type': 'action_event'} {"body": {"log": "Connect: Connecting...\nrapid7/Example Insight Plugin:1.0.0. Step name: test_action\n", "status": "ok", "meta": {}, "output": {}}, "version": "v1", "type": "action_event"} INFO: RunController: Running /Users/insight-user/insight-connect/example_insight_plugin//tests/test_2.json INFO: RunController: Running command: docker run --rm -i rapid7/test_insight_plugin:1.0.0 run < /Users/insight-user/insight-connect/example_insight_plugin/tests/test_2.json Connect: Connecting... rapid7/Example Insight Plugin:1.0.0. Step name: test_action_2 Output is: {'body': {'log': 'Connect: Connecting...\nrapid7/Example Insight Plugin:1.0.0. Step name: test_action_2\n', 'status': 'ok', 'meta': {}, 'output': {}}, 'version': 'v1', 'type': 'action_event'} {"body": {"log": "Connect: Connecting...\nrapid7/Example Insight Plugin:1.0.0. Step name: test_action_2\n", "status": "ok", "meta": {}, "output": {}}, "version": "v1", "type": "action_event"}

Create Assessment
Copy link

When a branch is ready to be merged into master on the open-source Github repo, each pull request requires an assessment. This can be generated with insight-plugin using the flag -A.

Generate an assessment
Copy link

$ insight-plugin run -A INFO: RunController: Running /Users/insight-user/insight-connect/example_insight_plugin/tests/test_1.json INFO: RunController: Running command: docker run --rm -i rapid7/test_insight_plugin:1.0.0 run < /Users/insight-user/insight-connect/example_insight_plugin/tests/test_1.json Connect: Connecting... rapid7/Test Insight Plugin:1.0.0. Step name: test_action INFO: RunController: Running /Users/insight-user/insight-connect/example_insight_plugin/tests/test_2.json INFO: RunController: Running command: docker run --rm -i rapid7/test_insight_plugin:1.0.0 run < /Users/insight-user/insight-connect/example_insight_plugin/tests/test_2.json Connect: Connecting... rapid7/Example Insight Plugin:1.0.0. Step name: test_action INFO: RunController: Running icon validators INFO: RunController: ## Assessment ### Run <details id="docker-run---rm--i-rapid7test_insight_plugin100-run--usersinsight-userinsight-connectexample_insight_pluginteststest_1json"> { "body": { "log": "Connect: Connecting...\nrapid7/Example Insight Plugin:1.0.0. Step name: test_action\n", "status": "ok", "meta": {}, "output": {} }, "version": "v1", "type": "action_event" } <summary>docker run --rm -i rapid7/test_insight_plugin:1.0.0 run < //Users/insight-user/insight-connect/example_insight_plugin/tests/test_1.json</summary> </details> <details id="docker-run---rm--i-rapid7example_insight_plugin100-run--usersinsight-userinsight-connectexample_insight_pluginteststest_actionjson"> { "body": { "log": "Connect: Connecting...\nrapid7/Example Insight Plugin:1.0.0. Step name: test_action\n", "status": "ok", "meta": {}, "output": {} }, "version": "v1", "type": "action_event" } <summary>docker run --rm -i rapid7/example_insight_plugin:1.0.0 run < /Users/insight-user/insight-connect/example_insight_plugin/tests/test_action.json</summary> </details> ### Validation <details id="icon-validate---all-usersinsight-userinsight-connectexample_insight_plugin"> [*] Validating plugin with all validators at /Users/insight-user/insight-connect/example_insight_plugin [*] Running Integration Validators... [*] Executing validator HelpValidator [*] Executing validator ChangelogValidator [*] Executing validator CloudReadyConnectionCredentialTokenValidator [*] Executing validator RequiredKeysValidator [*] Executing validator UseCaseValidator [*] Executing validator SpecPropertiesValidator [*] Executing validator SpecVersionValidator [*] Executing validator FilesValidator [*] Executing validator TagValidator [*] Executing validator DescriptionValidator [*] Executing validator TitleValidator [*] Executing validator VendorValidator [*] Executing validator DefaultValueValidator [*] Executing validator IconValidator [*] Executing validator RequiredValidator [*] Executing validator VersionValidator [*] Executing validator DockerfileParentValidator [*] Executing validator ProfanityValidator [*] Executing validator AcronymValidator [*] Executing validator JSONValidator [*] Executing validator OutputValidator [*] Executing validator RegenerationValidator [*] Executing validator HelpInputOutputValidator <summary>icon-validate --all /Users/insight-user/insight-connect/example_insight_plugin</summary> </details> ### UI Screenshots of the plugin being used in Automation (InsightConnect) workflows (for validating functionality in the UI) go below this line. #### Workflow Builder #### Job #### Artifact

Rebuild
Copy link

Optionally, when developing plugins, you also have the ability to rebuild the plugin using the rebuild flag -R/--rebuild. When making code changes to a plugin, to test the code locally a user will need to re-run make as previously mentioned. The rebuild flag re-runs make image so a user can test their new changes quicker.

insight-plugin run tests/{test}.json --rebuild

insight-plugin run tests/encode.json --rebuild [*] Use ``make menu`` for available targets [*] Including available Makefiles: ../../tools/Makefiles/Colors.mk ../../tools/Makefiles/Helpers.mk -- [*] Building plugin image docker build --pull -t rapid7/base64:1.1.6 . [+] Building 10.0s (11/11) FINISHED docker:desktop-linux => [internal] load build definition from Dockerfile 0.0s => => transferring dockerfile: 665B 0.0s => [internal] load .dockerignore 0.0s => => transferring context: 131B 0.0s => [internal] load metadata for docker.io/rapid7/insightconnect-python-3-slim-plugin:5 1.7s => [1/6] FROM docker.io/rapid7/insightconnect-python-3-slim-plugin:5@sha256:40767f02134d5009cf44 0.0s => [internal] load build context 8.2s => => transferring context: 537.06MB 8.2s => CACHED [2/6] ADD ./plugin.spec.yaml /plugin.spec.yaml 0.0s => CACHED [3/6] ADD . /python/src 0.0s => CACHED [4/6] WORKDIR /python/src 0.0s => CACHED [5/6] RUN if [ -f requirements.txt ]; then pip install -r requirements.txt; fi 0.0s => CACHED [6/6] RUN python setup.py build && python setup.py install 0.0s => exporting to image 0.0s => => exporting layers 0.0s => => writing image sha256:113e3a7c7cb4b66a9112e2d398f97b612f4fb64f0781e6fba76f71e7315a41d4 0.0s => => naming to docker.io/rapid7/base64:1.1.6 0.0s What's Next? View summary of image vulnerabilities and recommendations → docker scout quickview docker tag rapid7/base64:1.1.6 rapid7/base64:latest 2023-08-30 08:48:07 [info ] rapid7/Base64:1.1.6. Step name: encode {"body": {"log": "", "status": "ok", "meta": {}, "output": {"data": "UmFwaWQ3"}}, "version": "v1", "type": "action_event"}