Configuration File

configure your integration and setup options

Directory Location

sample-integration/
├── config/
|   └── config.js

Summary

Each integration requires a javascript configuration file. The config file should be located in a directory called config and the file itself should be named config.js. The config file is a node module that exports a javascript object literal containing a set of properties used to configure the integration. The following snippet shows the contents of a valid configuration file but does not include all possible configuration properties. For more information on all available properties see below.

View a complete sample configuration file at the end of this page.

config/config.js

module.exports = {
    name: "Sample",
    acronym: "SI",
    description: "A partial sample of an integration config file",
    entityTypes: ['IPv4'],
    logging: {
       level: 'info',
       fileName: 'sample-integration.log'
    }
}

Configuration Properties

name

required | string

The name of the integration. The value set here is displayed in the Polarity integrations user interface. The name field can include spaces and other special characters. In general, we recommend the name be short and descriptive. It is not necessary to include the word "Integration" in the name.

acronym

required | string

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 the acronym to 4 or less characters. The casing used here will be carried forward into the notification window. A blank acronym is valid.

description

optional | string

Description for this integration which is displayed in the Polarity integration user interface. The description should be no more than one or two sentences. More detailed instructions should be included in a readme.md file included as part of the integration project.

entityTypes

required | array of strings

An array of entity types that should be passed to this integration. If you do not specify any entity types to pass to your integration, your integration will not receive any data unless the customTypes option has been specified. The following is a list of valid types:

Entity Type	Description
hash	Includes all supported hash types (MD5, SHA1, SHA256)
MD5	Returns valid MD5 hash types
SHA1	Returns valid SHA1 hash types
SHA256	Returns valid SHA256 hash types
IPv4	Returns valid IPv4 addresses (does not include CIDR ranges)
IPv4CIDR	Returns valid IPv4CIDR ranges
IPv6	Returns valid IPv6 addresses.
cve	Returns CVE numbers of the format `CVE-XXXX-XXXX`
string	Will return any value that is tagged in Polarity
url	Matches on uniform resource locators and requires the URL include a scheme (i.e., http://, ftp:// etc.)
domain	Returns domains that match common top level domains. Domains will include www if available but will not match on the scheme (i.e., http://).
email	Matches on common email address formats
*	The special * entity type will match on all built-in entity types. It will currently be expanded into the following values: 'IPv4', 'IPv4CIDR', 'IPv6', 'MD5', 'SHA1', 'SHA256', 'MAC', 'string', 'email', 'domain', 'url', 'IPv4CIDR', 'cve'.

Example

As an example, if you wanted your integration to receive IPv4 addresses, hashes and domains you would specify the following in your integration config:

config/config.js

{
    entityTypes: ['IPv4', 'hash', 'domain']
}

customTypes

optional object

An array of one or more custom entity type objects.

Any types specified ascustomTypes do not also need to be included in the entityTypes option.

A custom type object specifies a custom entity that this integration should receive. The custom type is defined by key and regex properties. To define a custom type object you use the following properties:

key (required | string)

A key name for the custom type which is used to identify the type of the entity in your integration. This should be named using lowerCamelCase (e.g., propertyAddress, hostname, employeeId etc.).

regex (required | string)

A javascript regular expression literal or a javascript RegExp object. This regular expression will be used to match on entities. Any matching entities will then be passed to your integration and assigned the type key. By default any provided regular expression will be case insensitive and global.

Please see the MDN guide on Regular Expressions for more information.

isCaseSensitive (optional | boolean | default: false)

By default the provided regex for the custom type will be case insensitive. You can make the regex case sensitive by setting isCaseSentitive to true.

isGlobal (optional | boolean | default: true)

By default the provided regex for the custom type will be run as a global search which is meant to find all matches in a given text block for a particular regex. If you only care about finding a single match on your regex within a given text block or if your regex only looks for a single fixed string then you can set isGlobal to false.

config/config.js

customTypes: [
    {
        key: 'windowsHostname',
        regex: /\d\d[a-z]+_win/,
        isCaseSensitive: true,
        isGlobal: true
    },
    {
        key: 'linuxHostname',
        regex: /\d\d[a-z]+_rhel/,
        isCaseSensitive: true,
        isGlobal: true
    }    
]

When specifying a regex for your custom type do not use an regex modifiers such as i or g. For example, the following regex using the i and g regex modifiers is supported /\d\d[a-z]+_win/ig. Instead of using these modifiers please use the isCaseSensitive and isGlobal properties.

onDemandOnly

optional | boolean | default: false

A boolean indicating whether or not the integration is required to run in on-demand only mode. If set to true, the integration will always be set to on-demand only with no option for users to run the integration in a real-time mode (i.e., Stream or Highlight).

onDemandOnly: true

defaultColor

optional | string | default: 'light-gray'

A default color to set for the integration when it is first installed. If not set, the integration's default color is 'light-gray'.

defaultColor: 'light-gray'

The following is a list of valid colors:

dark-green
dark-brown
dark-red
dark-orange
dark-blue-green
dark-yellow
dark-blue
dark-pink
dark-gray
dark-blue-gray
light-brown
light-blue-gray
light-yellow
light-green
light-blue-green
light-blue
light-purple
light-pink
light-gray

styles

optional | array of strings

The styles property contains an array of one or more paths to less or css files that should be used to style the integration's template. The path is relative to the root of your integration.

styles:[
    './styles/sample_integration.less'       
]

javascript

optional | array of strings

The javascript property contains an array of one or more paths to javascript files that are loaded alongside your integration. These files provide a way to load third party "vendor" libraries such as the Google Maps API.

javascript:[
    './vendor/vendor.js'       
]

block

optional | object

The block property allows you to provide custom component logic and a 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.

You can specify a javascript file for the component (block.component.file) as well as a file for the handlebars template that should be used to render your integration (block.template.file). Note that component files are based on Ember Components (please see Components for more information).

block.component.file (required | string )

block.template.file (required | string )

If you include the block property you must include both a block.component.file and a block.template.file

config/config.js

block: {
    component: {
        file: "./components/sample-integration.js"
    },
    template: {
        file: "./templates/sample-integration.hbs"
    }
}

logging

optional | object

The logging configuration property allows for logging parameters to be set.

logging.level (optional | string | default: info)

Set the level of logging for this integration. Valid values are trace, debug, info, warn, error, fatal. When setting a logging level logs will be output for the specified level and all levels above it. For example, if you set the logging level to warn (40) then the integration will output all log levels greater than or equal to 40 (warn, error, and fatal). The logging system uses the Node Bunyan logging module.

// Logging Levels
fatal  60
error  50
warn   40
info   30
debug  20
trace  10

logging.directoryPath (optional | string | default: logs)

Set the directory path where the log file will be saved. If a relative directory is provided, the directory is relative to the integrations directory. For example, if the integration is in /app/polarity-server/integrations/sample-integration and the logging.directoryPath is set to integration-log then the sample-integration logs will be written to /app/polarity-server/integrations/sample-integration/integration-log/integration.log.

logging.fileName (optional | string | default: integration.log)

The name of the log file saved into the logging.directoryPath. Defaults to integration.log.

The following is an example of the loggin option with all options specified:

config/config.js

logging:{
    level: 'info',   
    fileName: 'sample-integration.log',
    directoryPath: 'logs'
}

options

optional | array of option objects

An array of option objects. Options are used to allow users of an integration to configure the behavior of the integration or provide required data (e.g., API keys or database connection information). Options are exposed to the end user via the Polarity integrations user interface. Any option object is made up of the following properties:

option.key (required | string)

A unique name for the option that is used to access the value of the option from within your integration. This value should be camelCased (lowercase first letter, uppercase letters for subsequent words) and not include spaces, dashes, or special characters. In general, you should name the key using the same naming conventions you would use for naming a javascript variable.

option.name (required | string)

Human readable name for the option which will be displayed in the Polarity user interface

option.description (required | string)

A short description for what the option does. This description is displayed in the Polarity user interface.

option.type (required | string)

The type for this option. The value for type can be either text, password, boolean, number, or select.

Type	Description
text	text options will show up as a standard HTML input field in the Polarity web interface.
password	password options will display as a password input and the stored value for the password will be encrypted using an AES 256 bit cipher when stored in the Polarity database. The private encryption key is randomly generated when you first install Polarity server and is located in the polarity server configuration file.
boolean	boolean options will be displayed as a checkbox and can have a value of true or false.
number	number options will only allow user to enter numeric values including integers and decimal values (e.g., -1, 0, 10, 12.5)
select	select options allow you to specify a predefined list of values that the user must choose from.

See the section on select options for additional information on these more advanced option types.

option.default (required | string, boolean, numeric)

The default value for the option. Note this value can be either a string, boolean , numberor objectdepending on the @type specified by the type property.

Type	Valid default values	Example
text	any string wrapped in double or single quotes	"http://server"
password	any string wrapped in double or single quotes	"password123"
boolean	the boolean value true or false (not quoted)	true
number	any number	10
select	A select object	{ value: 'intel', display: 'Threat intel' }

option.userCanEdit (required | boolean)

If true, non-admin users can edit the value of this option and the option will be stored on a per-user basis. If false, the option will be server wide (i.e., a single value will apply to all users and the value cannot be edited by non-admin users). Note that for this setting to have an effect, the property options[].adminOnly must be set to false.

option.adminOnly (required | boolean)

If set to true, the setting can only be viewed by admins. For all other users the setting will not appear. Note that if adminOnly is set to true, the value of userCanEdit is not applicable.

Sample adminOnly and userCanEdit configurations

This configuration will be visible only to Polarity Admins and the setting will be server wide (i.e., one setting value for the integration). This setting overrides the value of userCanEdit and should be used for sensitive values such as passwords that you do not want passed to a user's client or web browser.

config/config.js

{
    adminOnly: true    
    // Note that value of userCanEdit has no effect
}

This configuration will be visible to all users and each user can set their own value for the setting. This is useful for per user settings such as per user API Keys.

config/config.js

{
    adminOnly: false,
    userCanEdit: true
}

This configuration will be visible to all users but only Polarity Admins will be able to edit the value. This setting will be server-wide (i.e., one setting value for the integration). This setting is useful if you want to "lock" an option but still allow user's to see the value.

config/config.js

{
    adminOnly: false,
    userCanEdit: false
}

Select Options

Select options include an additional multiple property.

multiple (optional | boolean | default: false)

The multiple property can be set to true or false. When set to true, the select input will allow the user to select multiple values. If false the select input will only allow a single option to be chosen.

options (required | array)

The options property is an array of option objects where an option object contains a value property and display property. The display property is the text that is displayed in the select menu.

Select Option Object

{
   value: 'intel',
   display: 'Threat Intel'
}

default (required | object)

The default value for a multi select (multiple=true) is an array of select option objects. If the select option is not a multi-select (multiple=false) then the default value is a single select option object.

Example Multi Select

The following is an example of a multi-select option.

config/config.js

{
    key: 'userRoleMulti',
    name: 'Multi User Role',
    description: 'Choose your roles to automatically configure appropriate response data',
    default: [
        {
            value: 'intel',
            display: 'Threat Intel'
        }
    ],
    type: "select",
    options: [
        {
            value: 'intel',
            display: 'Threat Intel'
        },
        {
            value: 'ir',
            display: 'Incident Responder'
        },
        {
            value: 'rt',
            display: 'Red Team'
        }
    ],
    multiple: true,
    userCanEdit: false,
    adminOnly: false
}

Example Single Select

The following is an example option for a single select option.

config/config.js

{
    key: 'userRole',
    name: 'User Role',
    description: 'Choose your roles to automatically configure appropriate response data',
    default: {
        value: 'intel',
        display: 'Threat Intel'
    },
    type: "select",
    options: [
        {
            value: 'intel',
            display: 'Threat Intel'
        },
        {
            value: 'ir',
            display: 'Incident Responder'
        },
        {
            value: 'rt',
            display: 'Red Team'
        }
    ],
    multiple: false,
    userCanEdit: false,
    adminOnly: false
}

Sample Configuration

The following is a sample integration configuration that makes use of all the properties specified above.

config/config.js

module.exports = {
    name: "Sample Integration",
    acronym: "SI",
    description: "A partial sample of an integration config file",
    entityTypes: ['IPv4', 'IPv6'],
    customTypes: [
      {
          key: 'hostname',
          regex: /[a-z]+dc[0-9]/
      }  
    ],
    styles: [
         "./styles/sample_integration.less"
    ],
    javascript: [
      "./vendor/vendor.js"  
    ],
    block: {
        component: {
            file: "./components/sample-integration.js"
        },
        template: {
            file: "./templates/sample-integration.hbs"
        }
    },    
    logging: {
        level: 'debug',
        fileName: 'integration.log',
        directoryPath: 'logs'
    },
    options: [
        {
            "key"         : "apiKey",
            "name"        : "Sample API Key",
            "description" : "The API Key for your Sample Integration",
            "type"        : "text",
            "default"     : "",            
            "userCanEdit" : true,
            "adminOnly"   : false            
         }   
     ]   
}