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:

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.

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.

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            
         }   
     ]   
}

Last updated