Running Plugins

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

insight-plugin Tooling

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

About insight-plugin

  • 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

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

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

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

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

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

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

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

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

$ 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>
 
{
  "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>
 
 
{
  "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>
 
[*] 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 InsightConnect workflows (for validating functionality in the UI) go below this line.
 
#### Workflow Builder
 
#### Job
 
#### Artifact

Rebuild

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"}