Asset search fixes

.github/workflows/run-int-dev-checklist.yml

@@ -7,7 +7,7 @@ on:
 jobs:
   run-integration-development-checklist:
     runs-on: ubuntu-latest
-    container: 'centos:7'
+    container: 'rockylinux:8'
 
     steps:
     - uses: actions/checkout@v2

README.md

@@ -22,21 +22,39 @@ The username of the Service Now user you want the integration to authenticate as
 ### Password
 The password for the provided username you want the integration to authenticate as.
 
-### Search By String
-This will toggle whether or not to search the ServiceNow's Asset Table with strings found in your channels.
+### Search By Annotated Entities
+This will toggle whether to search ServiceNow for annotated entities found in your channels. The "string" Data Type must also be enabled for this option to have an effect.
+
+### Enable Incident Search
+If checked, the integration will search ServiceNow's Incident Table (incident) for IP Addresses, Domains, CVEs, annotated entities, and any added custom types
 
 ### Incident Query Fields
-A comma separated list of Fields to query against Incidents. 
-> NOTE: If a field is not in this list, it will not be searched on on in ServiceNow's Incident Table.
-> (This applies to IP Addresses, Domains, and String searches)
+A comma separated list of fields to search when querying for Incidents. Incident searches are done for IPs, domains, CVEs, annotated entities and any added custom types. NOTE: If a field is not in this list, it will not be searched for Incident Queries.
+
+### Incident Search Window in Days
+Number of days back to search when searching incidents. Filters based on the date that the Incident was opened. Defaults to 360.
 
 ### Enable Asset Search
-If checked, the integration will search ServiceNow's Asset Table (alm_asset) for IP Addresses, Domains, CVEs and annotated entities.
+If checked, the integration will search ServiceNow's Asset Table (alm_asset) for IP Addresses, Domains, CVEs, annotated entities, and any added custom types.
 
 ### Asset Query Fields
-A comma separated list of fields to search domains and IPs by in ServiceNow's Asset Table.
-> NOTE: If a field is not in this list, it will not be searched on in ServiceNow's Asset Table.
-> (This applies to IP Addresses, Domains, and String searches)
+A comma separated list of fields to search when querying for Assets. Asset searches are done for IPs, domains, CVEs, annotated entities and any added custom types. NOTE: If a field is not in this list, the field will not be searched in ServiceNow's Asset Table.
+
+This option defaults to searching the `ci.name` and `ci.asset_tag` fields.  The correct fields to search are dependent on your ServiceNow implementation.  A common additional field to add is `comments`.
+
+## Searching Assets
+
+Assets in ServiceNow are commonly found in the Assets table `alm_assets` or the Configuration Item table `cmdb_ci`.  The Polarity ServiceNow integration searches the `alm_assets` table as part of its asset search capability but fields within the `cmdb_ci` table can be referenced for searching by prepending the table's column name with `ci.`.  As an example, if you'd like to search the `asset_tag` field within the `cmdb_ci` table, you should set the "Asset Query Fields" option to `ci.asset_tag`.  
+
+Common "Asset Query Fields" include:
+
+* display_name
+* name
+* asset_tag
+* comments
+* ci.name
+* ci.display_name
+* ci.asset_tag
 
 ## IP Lookups and Finding Query Fields
 Because ServiceNow is often customized to fit specific needs, Polarity's ServiceNow Integration offers the ability to look up IPv4 matches on custom Incident and Asset fields. Simply add a comma separated list of custom fields to the `Custom Fields` integration option, and when Polarity recognizes an IP address, it will look up the address in the custom fields you listed and display the results.  To determine what value you should put in this field your can reference our guide [**Here**](./HowToFindCustomFields.md) using the dashboard.
@@ -49,6 +67,14 @@ They are usually prepended with a `u_` and then the name of the custom field, in
 |---|
 |*Custom Query Field Example*|
 
+## Known Issues
+
+If adding additional custom types to the ServiceNow integration, ensure the added custom types do not also match on the built-in custom types for Incidents, Change Requests, Knowledge Base, Request, and Request Item ids.
+
+As an example, if you add a new custom type that matches on the string `INC0001234`, this will conflict with the integration's built-in custom type for looking up incidents by ID.
+
+Ensure that newly added custom types (e.g., for hostnames), do not overlap with these custom types.
+
 ## Polarity
 
 Polarity is a memory-augmentation platform that improves and accelerates analyst decision making.  For more information about the Polarity platform please see:

config/config.js

@@ -1,69 +1,33 @@
 module.exports = {
-  /**
-   * Name of the integration which is displayed in the Polarity integrations user interface
-   *
-   * @type String
-   * @required
-   */
   name: 'ServiceNow',
-  /**
-   * The acronym that appears in the notification window when information from this integration
-   * is displayed.  Note that the acronym is included as part of each "tag" in the summary information
-   * for the integration.  As a result, it is best to keep it to 4 or less characters.  The casing used
-   * here will be carried forward into the notification window.
-   *
-   * @type String
-   * @required
-   */
   acronym: 'SN',
   defaultColor: 'light-purple',
-  /**
-   * Description for this integration which is displayed in the Polarity integrations user interface
-   *
-   * @type String
-   * @optional
-   */
   description:
     'ServiceNow automates and streamlines work and helps create great employee and customer experiences.',
   entityTypes: ['IPv4', 'email', 'domain', 'string', 'cve'],
   customTypes: [
     {
       key: 'incident',
-      regex: /INC[0-9]{7,}/
+      regex: 'INC[0-9]{7,}'
     },
     {
       key: 'knowledgeBase',
-      regex: /KB[0-9]{7,}/
+      regex: 'KB[0-9]{7,}'
     },
     {
       key: 'change',
-      regex: /CHG[0-9]{7,}/
+      regex: 'CHG[0-9]{7,}'
     },
     {
       key: 'request',
-      regex: /REQ[0-9]{7,}/
+      regex: 'REQ[0-9]{7,}'
     },
     {
       key: 'requestedItem',
-      regex: /RITM[0-9]{7,}/
+      regex: 'RITM[0-9]{7,}'
     }
   ],
-  /**
-   * An array of style files (css or less) that will be included for your integration. Any styles specified in
-   * the below files can be used in your custom template.
-   *
-   * @type Array
-   * @optional
-   */
   styles: ['./styles/styles.less'],
-  /**
-   * Provide custom component logic and template for rendering the integration details block.  If you do not
-   * provide a custom template and/or component then the integration will display data as a table of key value
-   * pairs.
-   *
-   * @type Object
-   * @optional
-   */
   block: {
     component: {
       file: './components/block.js'
@@ -73,32 +37,15 @@ module.exports = {
     }
   },
   request: {
-    // Provide the path to your certFile. Leave an empty string to ignore this option.
-    // Relative paths are relative to the ServiceNow integration's root directory
     cert: '',
-    // Provide the path to your private key. Leave an empty string to ignore this option.
-    // Relative paths are relative to the ServiceNow integration's root directory
     key: '',
-    // Provide the key passphrase if required.  Leave an empty string to ignore this option.
-    // Relative paths are relative to the ServiceNow integration's root directory
     passphrase: '',
-    // Provide the Certificate Authority. Leave an empty string to ignore this option.
-    // Relative paths are relative to the ServiceNow integration's root directory
     ca: '',
-    // An HTTP proxy to be used. Supports proxy Auth with Basic Auth, identical to support for
-    // the url parameter (by embedding the auth info in the uri)
-    proxy: ""
+    proxy: ''
   },
   logging: {
-    level: 'info' //trace, debug, info, warn, error, fatal
+    level: 'info'
   },
-  /**
-   * Options that are displayed to the user/admin in the Polarity integration user-interface.  Should be structured
-   * as an array of option objects.
-   *
-   * @type Array
-   * @optional
-   */
   options: [
     {
       key: 'url',
@@ -132,29 +79,47 @@ module.exports = {
       key: 'shouldSearchString',
       name: 'Search By Annotated Entities',
       description:
-        "This will toggle whether or not to search the ServiceNow for annotated entities found in your channels.",
+        'This will toggle whether to search ServiceNow for annotated entities found in your channels.  The "string" Data Type must also be enabled for this option to have an effect.',
       default: false,
       type: 'boolean',
       userCanEdit: false,
       adminOnly: true
     },
+    {
+      key: 'enableIncidentSearch',
+      name: 'Enable Incident Search',
+      description:
+        "If checked, the integration will search ServiceNow's Incident Table (incident) for IP Addresses, Domains, CVEs, annotated entities, and any added custom types",
+      default: true,
+      type: 'boolean',
+      userCanEdit: false,
+      adminOnly: true
+    },
     {
       key: 'incidentQueryFields',
       name: 'Incident Query Fields',
       description:
-        'A comma separated list of Fields to query against Incidents.  \n' +
-        'NOTE: If a field is not in this list, it will not be searched on Incident Queries.\n' +
-        '(This applies to IP address, domain, and annotated entity searches)',
-      default: 'u_ip_addr_2, u_destination_ip, short_description, work_notes',
+        'A comma separated list of fields to search when querying for Incidents.  Incident searches are done for IPs, domains, CVEs, annotated entities and any added custom types. NOTE: If a field is not in this list, it will not be searched for Incident Queries.',
+      default: 'short_description, description, work_notes',
       type: 'text',
       userCanEdit: false,
       adminOnly: true
     },
+    {
+      key: 'incidentDaysAgoToSearch',
+      name: 'Incident Search Window in Days',
+      description:
+        'Number of days back to search when searching incidents.  Filters based on the date that the Incident was opened. Defaults to 360.',
+      default: 360,
+      type: 'number',
+      userCanEdit: false,
+      adminOnly: true
+    },
     {
       key: 'enableAssetSearch',
       name: 'Enable Asset Search',
       description:
-          "If checked, the integration will search ServiceNow's Asset Table (alm_asset) for IP Addresses, Domains, CVEs and annotated entities",
+        "If checked, the integration will search ServiceNow's Asset Table (alm_asset) for IP Addresses, Domains, CVEs, annotated entities, and any added custom types.",
       default: true,
       type: 'boolean',
       userCanEdit: false,
@@ -164,10 +129,8 @@ module.exports = {
       key: 'assetTableFields',
       name: 'Asset Query Fields',
       description:
-        "A comma separated list of fields to search domains and IPs by in ServiceNow's Asset Table.  \n" +
-        "NOTE: If a field is not in this list, the field will not be searched in ServiceNow's Asset Table.\n" +
-        '(This applies to IP Addresses, Domains, and String searches)',
-      default: 'dns_domain, sys_domain_path, ip_address, short_description',
+        "A comma separated list of fields to search when querying for Assets. Asset searches are done for IPs, domains, CVEs, annotated entities and any added custom types. NOTE: If a field is not in this list, the field will not be searched in ServiceNow's Asset Table.",
+      default: 'name, display_name, asset_tag, ci.name, ci.asset_tag',
       type: 'text',
       userCanEdit: false,
       adminOnly: true

config/config.json

@@ -4,7 +4,14 @@
   "acronym": "SN",
   "defaultColor": "light-purple",
   "description": "ServiceNow automates and streamlines work and helps create great employee and customer experiences.",
-  "entityTypes": ["IPv4", "email", "domain", "string", "cve"],"customTypes": [
+  "entityTypes": [
+    "IPv4",
+    "email",
+    "domain",
+    "string",
+    "cve"
+  ],
+  "customTypes": [
     {
       "key": "incident",
       "regex": "INC[0-9]{7,}"
@@ -26,10 +33,16 @@
       "regex": "RITM[0-9]{7,}"
     }
   ],
-  "styles": ["./styles/styles.less"],
+  "styles": [
+    "./styles/styles.less"
+  ],
   "block": {
-    "component": { "file": "./components/block.js" },
-    "template": { "file": "./templates/block.hbs" }
+    "component": {
+      "file": "./components/block.js"
+    },
+    "template": {
+      "file": "./templates/block.hbs"
+    }
   },
   "request": {
     "cert": "",
@@ -38,7 +51,9 @@
     "ca": "",
     "proxy": ""
   },
-  "logging": { "level": "info" },
+  "logging": {
+    "level": "info"
+  },
   "options": [
     {
       "key": "url",
@@ -70,25 +85,43 @@
     {
       "key": "shouldSearchString",
       "name": "Search By Annotated Entities",
-      "description": "This will toggle whether or not to search the ServiceNow for annotated entities found in your channels.",
+      "description": "This will toggle whether to search ServiceNow for annotated entities found in your channels.  The \"string\" Data Type must also be enabled for this option to have an effect.",
       "default": false,
       "type": "boolean",
       "userCanEdit": false,
       "adminOnly": true
     },
+    {
+      "key": "enableIncidentSearch",
+      "name": "Enable Incident Search",
+      "description": "If checked, the integration will search ServiceNow's Incident Table (incident) for IP Addresses, Domains, CVEs, annotated entities, and any added custom types",
+      "default": true,
+      "type": "boolean",
+      "userCanEdit": false,
+      "adminOnly": true
+    },
     {
       "key": "incidentQueryFields",
       "name": "Incident Query Fields",
-      "description": "A comma separated list of Fields to query against Incidents.  \nNOTE: If a field is not in this list, it will not be searched on Incident Queries.\n(This applies to IP address, domain, and annotated entity searches)",
-      "default": "u_ip_addr_2, u_destination_ip, short_description, work_notes",
+      "description": "A comma separated list of fields to search when querying for Incidents.  Incident searches are done for IPs, domains, CVEs, annotated entities and any added custom types. NOTE: If a field is not in this list, it will not be searched for Incident Queries.",
+      "default": "short_description, description, work_notes",
       "type": "text",
       "userCanEdit": false,
       "adminOnly": true
     },
+    {
+      "key": "incidentDaysAgoToSearch",
+      "name": "Incident Search Window in Days ",
+      "description": "Number of days back to search when searching incidents.  Filters based on the date that the Incident was opened. Defaults to 360.",
+      "default": 360,
+      "type": "number",
+      "userCanEdit": false,
+      "adminOnly": true
+    },
     {
       "key": "enableAssetSearch",
       "name": "Enable Asset Search",
-      "description": "If checked, the integration will search ServiceNow's Asset Table (alm_asset) for IP Addresses, Domains, CVEs and annotated entities",
+      "description": "If checked, the integration will search ServiceNow's Asset Table (alm_asset) for IP Addresses, Domains, CVEs, annotated entities, and any added custom types.",
       "default": true,
       "type": "boolean",
       "userCanEdit": false,
@@ -97,8 +130,8 @@
     {
       "key": "assetTableFields",
       "name": "Asset Query Fields",
-      "description": "A comma separated list of fields to search domains and IPs by in ServiceNow's Asset Table.  \nNOTE: If a field is not in this list, the field will not be searched in ServiceNow's Asset Table.\n(This applies to IP Addresses, Domains, and String searches)",
-      "default": "dns_domain, sys_domain_path, ip_address, short_description",
+      "description": "A comma separated list of fields to search when querying for Assets. Asset searches are done for IPs, domains, CVEs, annotated entities and any added custom types. NOTE: If a field is not in this list, the field will not be searched in ServiceNow's Asset (alm_asset) Table.",
+      "default": "name, display_name, asset_tag, ci.name, ci.asset_tag",
       "type": "text",
       "userCanEdit": false,
       "adminOnly": true