Running Plugins

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

icon-plugin tooling

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

About icon-plugin

The best tooling of the methods
The icon-plugin tool is the primary plugin development tool that should be used to administrate any plugin
Installation instructions for icon-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:


 
1
$ icon-plugin run --help
2
usage: icon-plugin run [<flags>] [<args>...]
3

4
Runs plugin
5

6
Flags:
7
      --help               Show context-sensitive help (also try --help-long and --help-man).
8
  -v, --verbose            Verbose mode.
9
      --version            Show application version.
10
  -f, --specfile=SPECFILE  Path to plugin spec to use (e.g. ./plugin.spec.yaml).
11
  -A, --assessment         Create PR assessment around the given -T/-R options.
12
  -C, --cache              Enable cache (def: /var/cache).
13
  -c, --command=COMMAND    Command to run in container info|sample|samples|test|run|http|bash.
14
  -d, --debug              Debug mode.
15
  -j, --jq                 Pipe through JQ.
16
  -m, --rebuild            Build plugin before executing.
17
  -V, --volume=VOLUME      Volume mount (e.g.: /src/dst).
18
  -p, --port=PORT          Port forward (e.g.: 8000:8888/udp).
19
  -T, --Test=TEST ...      Run JSON test methods (e.g. <file.json> | all) all - Execution order can be specified via tests/order.txt.
20
  -R, --Run=RUN ...        Run JSON run methods (e.g. <file.json> | all) all - Execution order can be specified via tests/order.txt.
21

22
Args:
23
  [<args>]  Additional arguments for the command flag.

Info Command

The info command will print plugin metadata.


 
1
$ icon-plugin run -c info
2
INFO[0000] Running command:  docker run --rm -i rapid7/base64:1.1.1 info <
3
Name:        Base64
4
Vendor:      rapid7
5
Version:     1.1.1
6
Description: Encode and decode data using the base64 alphabet
7

8
Actions (2):
9
└── decode (Decode Base64 to data)
10
└── encode (Encode data to Base64)

Test Command

You can use the test command to test your plugin 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 komand_example/actions/say_goodbye/action.py and then rebuild with make:


python
1
...
2

3
    def test(self):
4
        # TODO: Implement test function
5
        self.logger.info('Saying goodbye to %s', 'test')
6
        return { 'message': 'Goodbye test!' }

Test

Run plugin's test method using icon-plugin:


 
1
$ icon-plugin run -T tests/decode.json -j
2
INFO[0000] Running command:  docker run --rm -i rapid7/base64:1.1.1 test < tests/decode.json
3
INFO[0003]  Output:
4
{
5
    "data": "base64"
6
}

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 --debug flag so that all output is displayed to stdin/stdout.

Note: --debug 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 komand_example/actions/say_goodbye/action.py and then rebuild with make:


python
1
...
2
    def run(self, params={}):
3
        # TODO: Implement run function
4
        name = params.get('name')
5
        self.logger.info('Saying goodbye to %s', name)
6
        msg = 'Goodbye {}!'.format(name)
7
        return { 'message': msg }

Run

Run plugin's run method using icon-plugin:


 
1
$ icon-plugin run -R tests/decode.json -j
2
INFO[0000] Running command:  docker run --rm -i rapid7/base64:1.1.1 run < tests/decode.json
3
INFO[0002]  Output:
4
{
5
    "data": "hey,this,is,cool,right\ntell,me,what,you,think\n"
6
}

Execute all runs and tests

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


 
1
$ icon-plugin run -R all -T all -j
2
INFO[0000] Running command:  docker run --rm -i rapid7/base64:1.1.1 run < tests/decode.json
3
INFO[0003]  Output:
4
{
5
    "data": "hey,this,is,cool,right\ntell,me,what,you,think\n"
6
}
7
INFO[0003] Running command:  docker run --rm -i rapid7/base64:1.1.1 run < tests/encode.json
8
INFO[0006]  Output:
9
{
10
    "data": "bGV0cyBlbmNvZGUgdGhpcyBtZXNzYWdlCnNpbGx5IGJveQ=="
11
}
12
INFO[0006] Running command:  docker run --rm -i rapid7/base64:1.1.1 test < tests/decode.json
13
INFO[0010]  Output:
14
{
15
    "data": "base64"
16
}
17
INFO[0010] Running command:  docker run --rm -i rapid7/base64:1.1.1 test < tests/encode.json
18
INFO[0013]  Output:
19
{
20
    "data": "YmFzZTY0"
21
}

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 icon-plugin using the flag -A.

Generate an assessment:


 
1
$ icon-plugin run -R tests/decode.json -A -j
2
INFO[0000] Running command:  docker run --rm -i rapid7/base64:1.1.1 run < tests/decode.json
3
INFO[0002]  Output:
4
{
5
    "data": "hey,this,is,cool,right\ntell,me,what,you,think\n"
6
}
7

8
## Assessment
9
### Run
10

11
<details>
12

13
    ```
14
{
15
    "body": {
16
        "log": "rapid7/Base64:1.1.1. Step name: decode\n",
17
        "meta": {},
18
        "output": {
19
            "data": "hey,this,is,cool,right\ntell,me,what,you,think\n"
20
        },
21
        "status": "ok"
22
    },
23
    "type": "action_event",
24
    "version": "v1"
25
}
26

27
    ```
28

29
<summary>
30
docker run --rm -i rapid7/base64:1.1.1 run
31
</summary>
32
</details>
33

34
### UI
35

36
Screenshots of the plugin being used in Komand for validating use go below this line.
37

38
#### Workflow Builder
39

40

41
#### Job
42

43

44
#### Artifact

Did this page help you?