# Configuration File ## 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.](#sample) {% code title="config/config.js" %} ```javascript module.exports = { name: "Sample", acronym: "SI", description: "A partial sample of an integration config file", entityTypes: ['IPv4'], logging: { level: 'info', fileName: 'sample-integration.log' } } ``` {% endcode %} ## 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`](https://docs.polarity.io/integrations/build-an-integration/readme-guide) 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: {% code title="config/config.js" %} ```javascript { entityTypes: ['IPv4', 'hash', 'domain'] } ``` {% endcode %} ### customTypes **optional** *object* An array of one or more custom entity type objects. {% hint style="info" %} Any types specified as`customTypes` do not also need to be included in the `entityTypes` option. {% endhint %} 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. {% hint style="info" %} Please see the [MDN guide on Regular Expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) for more information. {% endhint %} **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. {% code title="config/config.js" %} ```javascript 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 } ] ``` {% endcode %} {% hint style="info" %} 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. {% endhint %} ### 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. ```javascript 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 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](https://app.gitbook.com/components.md) for more information). **block.component.file** (required | *string* ) **block.template.file** (required | *string* ) {% hint style="info" %} If you include the `block` property you must include both a `block.component.file` and a `block.template.file` {% endhint %} {% code title="config/config.js" %} ```javascript block: { component: { file: "./components/sample-integration.js" }, template: { file: "./templates/sample-integration.hbs" } } ``` {% endcode %} ### 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](https://github.com/trentm/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: {% code title="config/config.js" %} ``` logging:{ level: 'info', fileName: 'sample-integration.log', directoryPath: 'logs' } ``` {% endcode %} ### 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. | {% hint style="info" %} See the section on [select options](#select-options) for additional information on these more advanced option types. {% endhint %} **option.default** (required | *string, boolean, numeric*) The default value for the option. Note this value can be either a `string`, `boolean` , `number`or `object`depending on the @type specified by the `type` property. | Type | Valid default values | Example | | -------- | ------------------------------------------------ | --------------------------------------------------------------------- | | text | any string wrapped in double or single quotes | "" | | 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. {% code title="config/config.js" %} ```javascript { adminOnly: true // Note that value of userCanEdit has no effect } ``` {% endcode %} 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. {% code title="config/config.js" %} ```javascript { adminOnly: false, userCanEdit: true } ``` {% endcode %} 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. {% code title="config/config.js" %} ```javascript { adminOnly: false, userCanEdit: false } ``` {% endcode %} ## 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. {% code title="Select Option Object" %} ``` { value: 'intel', display: 'Threat Intel' } ``` {% endcode %} **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. {% code title="config/config.js" %} ```javascript { 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 } ``` {% endcode %} ### Example Single Select The following is an example option for a single select option. {% code title="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 } ``` {% endcode %} ## Sample Configuration The following is a sample integration configuration that makes use of all the properties specified above. {% code title="config/config.js" %} ```javascript 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 } ] } ``` {% endcode %}