Regenerating Plugins | InsightConnect Documentation

Regeneration occurs when you want to update the plugin schema to add, remove, or modify any actions, triggers, improved title and descriptions, etc. without loss of code and manual updates to the JSON schema.

⚠️

Instructions for Insight Plugin

The primary instructions are for the new Insight Plugin. For legacy instructions, see sections labeled Legacy Content. Please read carefully to make sure the instructions are relevant to the version you have installed.

Compatability

The latest plugin architecture is V2, which refers to SDK and insight-plugin tool improvements. The improvements split plugin components such as action and triggers into their own directories. For each directory, a code (e.g. action.py) and schema (e.g. schema.py) file exists. The schema files are generated directly off plugin.spec.yaml (source of truth) and should not be modified by the user. In this design, developers only need to modify the code files.

An example of a Python plugin that is V2 compliant:


base64
├── Dockerfile
├── Makefile
├── bin
│   └── icon_base64
├── icon_base64
│   ├── __init__.py
│   ├── actions
│   │   ├── __init__.py
│   │   ├── decode
│   │   │   ├── __init__.py
│   │   │   ├── action.py
│   │   │   └── schema.py
│   │   └── encode
│   │       ├── __init__.py
│   │       ├── action.py
│   │       └── schema.py
│   ├── connection
│   │   ├── __init__.py
│   │   ├── connection.py
│   │   └── schema.py
│   ├── triggers
│   │   ├── __init__.py
│   │   ├── trigger.py
│   │   └── schema.py
│   └── util
│       ├── __init__.py
│       └── api.py
├── plugin.spec.yaml
├── requirements.txt
├── setup.py
└── tests
|   ├── decode.json
|   └── encode.json
└── unit_tests
    ├── __init__.py
    ├── test_encode.json
    └── test_decode.json

Plugins developed after October 1, 2016 have the ability to be regenerated using the older git method.
- V1 method of Regenerating Plugins
Plugins developed after January 1, 2018 or plugins that have been ported to V2 have the ability to be regenerated using the newer method.
- The plugin V2 architecture provides regeneration natively with insight-plugin refresh.
- All our plugins have been ported to V2 but your custom plugins may have not, if they haven’t, it’s best to port them first to make development easier for the long term.

Generation Command

As described in the SDK Spec document, plugin skeletons are generated by running:

insight-plugin create plugin.spec.yaml

Legacy Content

icon-plugin generate python plugin.spec.yaml

Regeneration Command

If you decide to modify your plugin’s scheme, by editing plugin.spec.yaml, you’ll need to regenerate the plugin skeleton using insight-plugin refresh inside the plugin’s directory to apply the changes to all the files throughout the plugin.

Legacy Content

If you decide to modify your plugin’s scheme, by editing plugin.spec.yaml, you’ll need to regenerate the plugin skeleton using make regenerate inside the plugin’s directory. The make regenerate target is a shortcut that calls the full regenerate command which is icon-plugin generate python --regenerate.

Process

The following process will automatically put the new schema changes from plugin.spec.yaml into effect:

Update the plugin.spec.yaml file
Run insight-plugin refresh
Update any code files needed (e.g. action.py)

Example

Here’s an example of plugin regeneration by updating the schema (plugin.spec.yaml) to support:

A new action
A new plugin description
A schema for an existing action


❯ insight-plugin refresh
Refresh process complete!

Here’s a list of the changes with git status. You can see that a few files were modified as well as the new addition of the malware_lookup action directory.


$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

      modified:   .CHECKSUM
      modified:   bin/komand_cymon
      modified:   komand_cymon/actions/__init__.py
      modified:   plugin.spec.yaml
      modified:   setup.py

Untracked files:
  (use "git add <file>..." to include in what will be committed)

      komand_cymon/actions/malware_lookup/

We can see the exact changes using git diff. Notice that the description and version were updated in multiple files, specifically: cymon/bin/komand_cymon and setup.py. The new action resulted in the creation of new directory komand_cymon/actions/malware_lookup/ which contains an action.py and schema.py file. The rest of the output are the references to the new action.


diff --git a/cymon/bin/komand_cymon b/cymon/bin/komand_cymon
index ccd4c109d..7aed3ab00 100755
--- a/cymon/bin/komand_cymon
+++ b/cymon/bin/komand_cymon
@@ -6,8 +6,8 @@ from komand_cymon import connection, actions, triggers

 Name = 'Cymon'
 Vendor = 'rapid7'
-Version = '0.1.4'
-Description = 'Cymon Open Threat Intelligence'
+Version = '1.0.0'
+Description = 'Cymon is the largest tracker of open-source security reports about phishing, malware, botnets and other malicious activities'


 class KomandCymon(insightconnect_plugin_runtime.Plugin):
@@ -31,6 +31,8 @@ class KomandCymon(insightconnect_plugin_runtime.Plugin):

         self.add_action(actions.DomainLookup())

+        self.add_action(actions.MalwareLookup())
+
         self.add_action(actions.UrlLookup())


diff --git a/cymon/komand_cymon/actions/__init__.py b/cymon/komand_cymon/actions/__init__.py
index 41ac95ec7..44a025ccb 100755
--- a/cymon/komand_cymon/actions/__init__.py
+++ b/cymon/komand_cymon/actions/__init__.py
@@ -3,4 +3,5 @@ from .address_blacklist.action import AddressBlacklist
 from .address_lookup.action import AddressLookup
 from .domain_blacklist.action import DomainBlacklist
 from .domain_lookup.action import DomainLookup
+from .malware_lookup.action import MalwareLookup
 from .url_lookup.action import UrlLookup
diff --git a/cymon/plugin.spec.yaml b/cymon/plugin.spec.yaml
index a435d9eaf..23dda41a8 100644
--- a/cymon/plugin.spec.yaml
+++ b/cymon/plugin.spec.yaml
@@ -1,8 +1,8 @@
 plugin_spec_version: v2
 name: cymon
 title: Cymon
-description: "Cymon Open Threat Intelligence"
-version: 0.1.4
+description: "Cymon is the largest tracker of open-source security reports about phishing, malware, botnets and other malicious activities"
+version: 1.0.0
 vendor: rapid7
 @@ -529,3 +529,14 @@ actions:
       url:
         type: "[]string"
         title: Cymon URL References
+  malware_lookup:
+    description: Lookup malware hash
+    input:
+      hash:
+        type: string
+        description: MD5 or SHA1 hash
+        required: true
+    output:
+      found:
+        type: boolean
+        title: Malware Found
diff --git a/cymon/setup.py b/cymon/setup.py
index e72761182..6e8117680 100755
--- a/cymon/setup.py
+++ b/cymon/setup.py
@@ -3,8 +3,8 @@ from setuptools import setup, find_packages


 setup(name='cymon-komand-plugin',
-      version='0.1.4',
-      description='Cymon Open Threat Intelligence',
+      version='1.0.0',
+      description='Cymon is the largest tracker of open-source security reports about phishing, malware, botnets and other malicious activities',
       author='komand',
       author_email='',
       url='',

In addition, you will see changes to the plugin.spec.yaml file itself, since it’s the source of truth and we created those changes manually.

Now, add your code to the new komand_cymon/actions/malware_lookup/action.py file, test, and finalize your changes with:


$ git add .
$ git commit -m "Regenerate Cymon with new description and new malware lookup action"