Instructions for the usage of custom mappings (#1274)

opencybersecurityalliance · Jan 16, 2023 · 4e8fe1b · 4e8fe1b
1 parent 98650c3
commit 4e8fe1b
Show file tree

Hide file tree

Showing 39 changed files with 188 additions and 90 deletions.
diff --git a/README.md b/README.md
@@ -91,7 +91,11 @@ response = translation.translate('<MODULE NAME>', 'query', '{}', '<STIX PATTERN>
 
 print(response)
 ```
+### Use of custom mappings
 
+If a connector has been installed using pip, the process for editing the STIX mappings is different than if you have pulled-down the project. When working locally, you can edit the mapping files directly. See the [mapping files for the MySQL connector](stix_shifter_modules/mysql/stix_translation/json) as an example. Editing the mapping files won't work if the connector has been installed with pip; the setup script of the stix-shifter package includes the mapppings inside `config.json`. This allows stix-shifter to injest custom mappings as part of the connector's configuration.
+
+Refer to [Use of custom mappings](https://github.com/opencybersecurityalliance/stix-shifter/blob/develop/adapter-guide/custom_mappings.md) for more details on how to edit the mappings in the configuration.
 
 ## Contributing
 

diff --git a/adapter-guide/custom_mappings.md b/adapter-guide/custom_mappings.md
@@ -0,0 +1,94 @@
+# Use of custom mappings
+
+Follow the below steps, if a user or threat hunter wants to use custom mapping after installing stix-shifter libraries:
+
+
+1. Go to the standard python library installation location. The installation path usually looks like this ***lib/pythonX.Y/site-packages*** or go to https://docs.python.org/3/install/ for more details on the python library installation based on your system.
+
+2. Go to the ***stix_shifter_modules*** folder and find the connector name that is installed.
+
+3. Inside the connector folder, go to the ***config.json*** file found under the ***stix_shifter_modules/\<CONNECTOR\>/configuration/*** directory.
+
+4. There is a `mapping` object nested inside the `options` JSON object. This includes all the mappings from the `from_stix` and `to_stix` mapping files. Here's an example of the `config.json` file:
+
+```
+{
+    "connection": {
+        "type": {
+            "displayName": "MySQL",
+            "group": "mysql",
+            "type": "connectorType"
+        },
+        "options": {
+            "mapping": {
+                "type": "json",
+                "optional": true,
+                "previous": "connection.mapping",
+                "default": {
+                    "from_stix_map": {
+                        "ipv4-addr": {
+                            "fields": {
+                                "value": [
+                                    "source_ipaddr",
+                                    "dest_ipaddr"
+                                ]
+                            }
+                        },
+                        "file": {
+                            "fields": {
+                                "name": [
+                                    "filename"
+                                ]
+                            }
+                        }
+                    },
+                    "operators": {
+                        "ComparisonExpressionOperators.And": "AND",
+                        "ComparisonExpressionOperators.Or": "OR"
+                    },
+                    "to_stix_map": {
+                        "source_ipaddr": [
+                            {
+                                "key": "ipv4-addr.value",
+                                "object": "src_ip"
+                            },
+                            {
+                                "key": "network-traffic.src_ref",
+                                "object": "nt",
+                                "references": "src_ip"
+                            }
+                        ],
+                        "dest_ipaddr": [
+                            {
+                                "key": "ipv4-addr.value",
+                                "object": "dst_ip"
+                            },
+                            {
+                                "key": "network-traffic.dst_ref",
+                                "object": "nt",
+                                "references": "dst_ip"
+                            }
+                        ]
+                    }
+                }
+            }
+        }
+    },
+    "configuration": {
+        "auth": {
+            "type": "fields",
+            "username": {
+                "type": "password"
+            },
+            "password": {
+                "type": "password"
+            }
+        }
+    }
+}
+```
+
+
+5. You can change, update or use the existing custom mappings fields and save the file.
+
+6. The stix-shifter CLI commands should automatically pick up your custom mappings in the next command execution.
diff --git a/adapter-guide/develop-configuration-json.md b/adapter-guide/develop-configuration-json.md
@@ -126,11 +126,11 @@ Below example json is the language translation file of the above QRadar config j
         "host": {
             "label": "Management IP address or Hostname",
             "placeholder": "192.168.1.10",
-            "description": "Specify the IP address or  hostname of the data source so that IBM Cloud Pak for Security can communicate with it"
+            "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP"
+            "description": "Set the port number that is associated with the host name or IP address"
         },
         "help": {
             "label": "Need additional help?",

diff --git a/stix_shifter_modules/alertflex/configuration/lang_en.json b/stix_shifter_modules/alertflex/configuration/lang_en.json
@@ -1,13 +1,13 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "placeholder": "192.168.1.10",
-            "description": "Specify the IP address or hostname of the Alertflex controller"
+            "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP"
+            "description": "Set the port number that is associated with the hostname or IP address"
         },
         "help": {
             "label": "Help",

diff --git a/stix_shifter_modules/arcsight/configuration/lang_en.json b/stix_shifter_modules/arcsight/configuration/lang_en.json
@@ -1,20 +1,20 @@
 {
     "connection": {
         "host": {
-            "label": "ArcSight Logger IP address or Hostname",
-            "description": "Use IP address or Hostname of the ArcSight logger"
+            "label": "Management IP address or hostname",
+            "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP"
+            "description": "Set the port number that is associated with the hostname or IP address"
         },
         "help": {
             "label": "Need additional help?",
             "description": "More details on the datasource setting can be found in the specified link"
         },
         "selfSignedCert": {
-            "label": "ArcSight logger Connection Certificate",
-            "description": "Use self-signed SSL certificate and CA content(root and intermediate) of datasource"
+            "label": "Connection Certificate",
+            "description": "Use self-signed SSL certificate and CA content (root and intermediate) of datasource"
         },
         "sni": {
             "label": "Server Name Indicator",
@@ -24,11 +24,11 @@
     "configuration": {
         "auth": {
             "login": {
-                "label": "ArcSight Logger Username",
+                "label": "Username",
                 "description": "ArcSight Logger user's login name with access to the search API"
             },
             "password": {
-                "label": "ArcSight Logger Password",
+                "label": "Password",
                 "description": "ArcSight Logger user's password with access to the search API"
             }
         }

diff --git a/stix_shifter_modules/async_template/configuration/lang_en.json b/stix_shifter_modules/async_template/configuration/lang_en.json
@@ -1,13 +1,13 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "placeholder": "192.168.1.10",
-            "description": "Specify the IP address or  hostname of the data source so that IBM Cloud Pak for Security can communicate with it"
+            "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP"
+            "description": "Set the port number that is associated with the hostname or IP address"
         },
         "help": {
             "label": "Need additional help?",

diff --git a/stix_shifter_modules/azure_sentinel/configuration/lang_en.json b/stix_shifter_modules/azure_sentinel/configuration/lang_en.json
@@ -1,12 +1,12 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
-            "description": "Specify the IP address or  hostname of the data source so that IBM Cloud Pak for Security can communicate with it"
+            "label": "Management IP address or hostname",
+            "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP"
+            "description": "Set the port number that is associated with the hostname or IP address"
         },
         "help": {
             "label": "Need additional help?",

diff --git a/stix_shifter_modules/bigfix/configuration/lang_en.json b/stix_shifter_modules/bigfix/configuration/lang_en.json
@@ -1,13 +1,13 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "placeholder": "192.168.1.10",
-            "description": "Specify the IP address or  hostname of the data source so that IBM Cloud Pak for Security can communicate with it"
+            "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP"
+            "description": "Set the port number that is associated with the hostname or IP address"
         },
         "help": {
             "label": "Need additional help?",

diff --git a/stix_shifter_modules/carbonblack/configuration/lang_en.json b/stix_shifter_modules/carbonblack/configuration/lang_en.json
@@ -1,13 +1,13 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "placeholder": "192.168.1.10",
-            "description": "Specify the IP address or  hostname of the data source so that IBM Cloud Pak for Security can communicate with it"
+            "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP"
+            "description": "Set the port number that is associated with the hostname or IP address"
         },
         "help": {
             "label": "Need additional help?",

diff --git a/stix_shifter_modules/cbcloud/configuration/lang_en.json b/stix_shifter_modules/cbcloud/configuration/lang_en.json
@@ -1,17 +1,17 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "placeholder": "192.168.1.10",
-            "description": "Specify the IP address or hostname of the Carbon Black Cloud instance so that IBM Cloud Pak for Security can communicate with it."
+            "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP."
+            "description": "Set the port number that is associated with the hostname or IP address"
         },
         "help": {
             "label": "Need additional help?",
-            "description": "More details on the data source setting can be found in the specified link."
+            "description": "More details on the data source setting can be found in the specified link"
         }
     },
     "configuration": {

diff --git a/stix_shifter_modules/crowdstrike/configuration/lang_en.json b/stix_shifter_modules/crowdstrike/configuration/lang_en.json
@@ -1,13 +1,13 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "placeholder": "192.168.1.10",
-            "description": "Specify the IP address or  hostname of the data source so that IBM Cloud Pak for Security can communicate with it"
+            "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP"
+            "description": "Set the port number that is associated with the hostname or IP address"
         },
         "help": {
             "label": "Need additional help?",

diff --git a/stix_shifter_modules/cybereason/configuration/lang_en.json b/stix_shifter_modules/cybereason/configuration/lang_en.json
@@ -1,13 +1,13 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "placeholder": "192.168.1.10",
             "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP"
+            "description": "Set the port number that is associated with the hostname or IP address"
         },
         "help": {
             "label": "Need additional help?",

diff --git a/stix_shifter_modules/darktrace/configuration/lang_en.json b/stix_shifter_modules/darktrace/configuration/lang_en.json
@@ -1,7 +1,7 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "description": "Specify the IP address or hostname of the data source"
         },
         "help": {

diff --git a/stix_shifter_modules/datadog/configuration/lang_en.json b/stix_shifter_modules/datadog/configuration/lang_en.json
@@ -3,7 +3,7 @@
         "site_url": {
             "label": "Site URL",
             "placeholder": "https://app.datadoghq.com",
-            "description": "Specify the Site URL of the Datadog so that IBM Cloud Pak for Security can communicate with it"
+            "description": "Specify the Site URL of the datasource"
         },
         "selfSignedCert": {
             "label": "Datadog Certificate",

diff --git a/stix_shifter_modules/demo_template/configuration/lang_en.json b/stix_shifter_modules/demo_template/configuration/lang_en.json
@@ -1,13 +1,13 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "placeholder": "192.168.1.10",
-            "description": "Specify the IP address or  hostname of the data source so that the Application can communicate with it"
+            "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP"
+            "description": "Set the port number that is associated with the hostname or IP address"
         },
         "help": {
             "label": "Need additional help?",

diff --git a/stix_shifter_modules/elastic_ecs/configuration/lang_en.json b/stix_shifter_modules/elastic_ecs/configuration/lang_en.json
@@ -1,13 +1,13 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "placeholder": "192.168.1.10",
-            "description": "Specify the IP address or  hostname of the data source so that IBM Cloud Pak for Security can communicate with it"
+            "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP"
+            "description": "Set the port number that is associated with the hostname or IP address"
         },
         "help": {
             "label": "Need additional help?",

diff --git a/stix_shifter_modules/error_test/configuration/lang_en.json b/stix_shifter_modules/error_test/configuration/lang_en.json
@@ -3,7 +3,7 @@
         "url": {
             "label": "Full URL of a stix-bundle file",
             "placeholder": "https://url.to.stix_bundle.json.file",
-            "description": "Specify the URL of the STIX Bundle JSON file so that IBM Cloud Pak for Security can communicate with it"
+            "description": "Specify the URL of the STIX Bundle JSON file"
         },
         "help": {
             "label": "Need additional help?",

diff --git a/stix_shifter_modules/gcp_chronicle/configuration/lang_en.json b/stix_shifter_modules/gcp_chronicle/configuration/lang_en.json
@@ -1,7 +1,7 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "description": "Specify the IP address or hostname of the data source"
         },
         "help": {

diff --git a/stix_shifter_modules/guardium/configuration/lang_en.json b/stix_shifter_modules/guardium/configuration/lang_en.json
@@ -1,13 +1,13 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "placeholder": "192.168.1.10",
-            "description": "Specify the IP address or  hostname of the data source so that IBM Cloud Pak for Security can communicate with it"
+            "description": "Specify the IP address or hostname of the data source"
         },
         "port": {
             "label": "Host Port",
-            "description": "Set the port number that is associated with the Host name or IP"
+            "description": "Set the port number that is associated with the hostname or IP address"
         },
         "help": {
             "label": "Need additional help?",

diff --git a/stix_shifter_modules/ibm_security_verify/configuration/lang_en.json b/stix_shifter_modules/ibm_security_verify/configuration/lang_en.json
@@ -1,9 +1,9 @@
 {
     "connection": {
         "host": {
-            "label": "Management IP address or Hostname",
+            "label": "Management IP address or hostname",
             "placeholder": "192.168.1.1",
-            "description": "Specify the IBM Security verify IP address or Hostname."
+            "description": "Specify the data source IP address or hostname."
         },
         "port": {
             "label": "Host Port",