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:

sh
1
$ insight-plugin run --help
2
usage: insight-plugin run [-h] [-A] [-T] [-J [JQ]] [-R] [-V VOLUMES [VOLUMES ...]] [-d TARGET_DIR] [-v]
3
                          [json_target]
4

5
positional arguments:
6
  json_target           .json files to run
7

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

Info/View Command

The view command will print plugin metadata.

sh
1
❯ insight-plugin view
2
Name:        Base64
3
Vendor:      rapid7
4
Version:     1.1.6
5
Description: Encode and decode data using the base64 alphabet
6

7
Actions (2):
8
└── decode (Decode Base64 to data)
9
└── 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:

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

Test

Run plugin's test method using insight-plugin:

sh
1
$ insight-plugin run -T tests/test_action.json 
2
INFO: RunController: Running connection test with /Users/insight-user/insight-connect/example_insight_plugin/tests/test_action.json
3

4
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
5

6
Connect: Connecting...
7

8
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:

python
1
def run(self, params={}):
2
    name = params.get(Input.NAME)
3
    self.logger.info(f'Saying goodbye to {name}')
4
    
5
    message = f'Goodbye {name}!'
6
    return {'message': message}

Execute All Runs and Tests

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

 
1
$ insight-plugin run
2

3
INFO: RunController: Running /Users/insight-user/insight-connect/example_insight_plugin//tests/test_1.json
4

5
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
6

7
Connect: Connecting...
8

9
rapid7/Test Insight Plugin:1.0.0. Step name: test_action
10

11
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'}
12

13
{"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"}
14

15
INFO: RunController: Running /Users/insight-user/insight-connect/example_insight_plugin//tests/test_2.json
16

17
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
18

19
Connect: Connecting...
20

21
rapid7/Example Insight Plugin:1.0.0. Step name: test_action_2
22

23
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'}
24

25
{"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

sh
1
$ insight-plugin run -A
2

3
INFO: RunController: Running /Users/insight-user/insight-connect/example_insight_plugin/tests/test_1.json
4

5
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
6

7
Connect: Connecting...
8

9
rapid7/Test Insight Plugin:1.0.0. Step name: test_action
10

11
INFO: RunController: Running /Users/insight-user/insight-connect/example_insight_plugin/tests/test_2.json
12

13
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
14

15
Connect: Connecting...
16

17
rapid7/Example Insight Plugin:1.0.0. Step name: test_action
18

19
INFO: RunController: Running icon validators
20

21
INFO: RunController: 
22

23
## Assessment
24

25
### Run
26

27
<details>
28

29
{
30
  "body": {
31
    "log": "Connect: Connecting...\nrapid7/Example Insight Plugin:1.0.0. Step name: test_action\n",
32
    "status": "ok",
33
    "meta": {},
34
    "output": {}
35
  },
36
  "version": "v1",
37
  "type": "action_event"
38
}
39

40
<summary>
41
docker run --rm -i rapid7/test_insight_plugin:1.0.0 run < //Users/insight-user/insight-connect/example_insight_plugin/tests/test_1.json
42
</summary>
43
</details>
44

45

46
<details>
47

48

49
{
50
  "body": {
51
    "log": "Connect: Connecting...\nrapid7/Example Insight Plugin:1.0.0. Step name: test_action\n",
52
    "status": "ok",
53
    "meta": {},
54
    "output": {}
55
  },
56
  "version": "v1",
57
  "type": "action_event"
58
}
59

60

61
<summary>
62
docker run --rm -i rapid7/example_insight_plugin:1.0.0 run < /Users/insight-user/insight-connect/example_insight_plugin/tests/test_action.json
63
</summary>
64
</details>
65

66

67
### Validation
68

69

70
<details>
71

72
[*] Validating plugin with all validators at /Users/insight-user/insight-connect/example_insight_plugin
73

74

75
[*] Running Integration Validators...
76
[*] Executing validator HelpValidator
77
[*] Executing validator ChangelogValidator
78
[*] Executing validator CloudReadyConnectionCredentialTokenValidator
79
[*] Executing validator RequiredKeysValidator
80
[*] Executing validator UseCaseValidator
81
[*] Executing validator SpecPropertiesValidator
82
[*] Executing validator SpecVersionValidator
83
[*] Executing validator FilesValidator
84
[*] Executing validator TagValidator
85
[*] Executing validator DescriptionValidator
86
[*] Executing validator TitleValidator
87
[*] Executing validator VendorValidator
88
[*] Executing validator DefaultValueValidator
89
[*] Executing validator IconValidator
90
[*] Executing validator RequiredValidator
91
[*] Executing validator VersionValidator
92
[*] Executing validator DockerfileParentValidator
93
[*] Executing validator ProfanityValidator
94
[*] Executing validator AcronymValidator
95
[*] Executing validator JSONValidator
96
[*] Executing validator OutputValidator
97
[*] Executing validator RegenerationValidator
98
[*] Executing validator HelpInputOutputValidator
99

100

101
<summary>
102
icon-validate --all /Users/insight-user/insight-connect/example_insight_plugin
103
</summary>
104
</details>
105

106

107
### UI
108

109
Screenshots of the plugin being used in InsightConnect workflows (for validating functionality in the UI) go below this line.
110

111
#### Workflow Builder
112

113
#### Job
114

115
#### 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

sh
1
❯ insight-plugin run tests/encode.json --rebuild
2
[*] Use ``make menu`` for available targets
3
[*] Including available Makefiles: ../../tools/Makefiles/Colors.mk ../../tools/Makefiles/Helpers.mk
4
--
5
[*] Building plugin image
6
docker build --pull -t rapid7/base64:1.1.6 .
7
[+] Building 10.0s (11/11) FINISHED                                                   docker:desktop-linux
8
 => [internal] load build definition from Dockerfile                                                  0.0s
9
 => => transferring dockerfile: 665B                                                                  0.0s
10
 => [internal] load .dockerignore                                                                     0.0s
11
 => => transferring context: 131B                                                                     0.0s
12
 => [internal] load metadata for docker.io/rapid7/insightconnect-python-3-slim-plugin:5            1.7s
13
 => [1/6] FROM docker.io/rapid7/insightconnect-python-3-slim-plugin:5@sha256:40767f02134d5009cf44  0.0s
14
 => [internal] load build context                                                                     8.2s
15
 => => transferring context: 537.06MB                                                                 8.2s
16
 => CACHED [2/6] ADD ./plugin.spec.yaml /plugin.spec.yaml                                             0.0s
17
 => CACHED [3/6] ADD . /python/src                                                                    0.0s
18
 => CACHED [4/6] WORKDIR /python/src                                                                  0.0s
19
 => CACHED [5/6] RUN if [ -f requirements.txt ]; then pip install -r requirements.txt; fi             0.0s
20
 => CACHED [6/6] RUN python setup.py build && python setup.py install                                 0.0s
21
 => exporting to image                                                                                0.0s
22
 => => exporting layers                                                                               0.0s
23
 => => writing image sha256:113e3a7c7cb4b66a9112e2d398f97b612f4fb64f0781e6fba76f71e7315a41d4          0.0s
24
 => => naming to docker.io/rapid7/base64:1.1.6                                                        0.0s
25

26
What's Next?
27
  View summary of image vulnerabilities and recommendations → docker scout quickview
28
docker tag rapid7/base64:1.1.6 rapid7/base64:latest
29
2023-08-30 08:48:07 [info     ] rapid7/Base64:1.1.6. Step name: encode
30

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