Auto Subscribe CLI Tool

The integration auto subscribe CLI tool allows you to subscribe a one or more users to one or more specified integrations. Prior to running the script, you should ensure that the integration has been properly configured for all users (i.e., API keys and other required options have been set to "Only Admins can view and edit" or "Users can view only").

If a user does not have access to the specified integration, they will not be subscribed to the integration.

Installation

To install the script, you can download it directly to your Polarity Server and place it inside your /app directory. You should replace the existing script of the same name. You can use the following commands to install the script into the correct location:

cd /app
sudo wget https://dl.polarity.io/C7BFBB1CF5A58C7DBA57CD0941F635BF1895366064713E88DAA7F05A5295B8B1/PROD/server/scripts/polarity-integration-auto-subscribe-3.0.6.tgz
sudo tar -xvzf polarity-integration-auto-subscribe-3.0.6.tgz
cd polarity-integration-auto-subscribe
chmod a+x polarity-integration-auto-subscribe.sh

To confirm that you have the correct script installed you can run the --version command:

cd /app/polarity-integration-auto-subscribe
sudo ./polarity-integration-auto-subscribe.sh --version

You should see the following output:

Polarity CLI Integration Auto Subscribe v3.0.6

After running the script, users will immediately start receiving data from the auto-subscribed integrations when using the Polarity Client.

When using Polarity Web Search you will need to reload the browser window.

To view the new subscription state (i.e., see the subscribe toggle), you will need to reload the window or client.

Options

To quickly view all the available options you can run the following command:

sudo ./polarity-integration-auto-subscribe.sh --help

This will output the following:

Subscribe users to integrations

Options:
  --help                Show help  [boolean]
  --version             Show version number  [boolean]
  --username            Polarity Username to authenticate as  [string]
  --password            Password for the given Polarity username  [string]
  --url                 Polarity server url to include schema  [string] [required]
  --config              Path to the Polarity Server's config file.  [string] [default: "/app/polarity-server/config/config.js"]
  --env                 Path to the Polarity Server's .env file.  [string] [default: "/app/polarity-server/.env"]
  --integrations        A comma delimited list of integration ids to search  [string] [required]
  --subscribeUsernames  A comma delimited list of usernames to subscribe to the provided integration list.  If not provided all users granted explicit access to the integration will be subscribed (including admins).  [string] [default: ""]
  --includeAdmins       If provided, Polarity admin users will also be subscribed to the integration even if they do not have explicit access.  [boolean] [default: false]
  --simulate            If provided, the loader will log a preview of the actions it would take but no actions will be taken.  [boolean] [default: false]
  --rejectUnauthorized  If provided, the loader will reject unauthorized SSL connections  [boolean] [default: true]
  --proxy               If provided, the connection to the Polarity server will use the provided proxy setting  [string] [default: ""]
  --logging             The logging level for the script.  [string] [choices: "error", "warn", "info", "debug"] [default: "info"]

--env

--env=<path-to-env>

This is an optional flag you can use to provide an absolute path to your server's default .env file. For most installations the default value of /app/polarity-server/.env is correct and this option is not needed.

--config

--config=<path-to-config-file>

This is an optional flag you can use to provide an absolute path to your server's default config.js file. For most installations the default value of /app/polarity-server/config/config.js is correct and this option is not needed.

--url

--url=https://<polarity-server-fqdn>

This is the URL of the Polarity Server you wish to authenticate to. You should include the scheme https://.

--username

--username=<username>

This is the username of the Polarity user you wish to authenticate to your Polarity server as

--password

--password=<password>

This is the password of the Polarity user you wish to authenticate to your Polarity server as

If your password contains special characters make sure to enclose it in single quotes

--password='<password>'

--integrations

--integrations=<integrationDirName>
--integrations=<integrationDirName1>,<integrationDirName2>

One or more integration directory names specified using a comma delimited list.

If specifying a comma delimited list, no spaces should be included between integration directory names.

Example

--integrations=arin,ldap,alientvault-otx

You should specify the name of the directory of the integration and not the name of the integration in the user interface.

--subscribeUsernames

--subscribeUsernames=<username1>,<username2>,<username3>

A comma delimited list of usernames you would like to subscribe to the integration. If this options is not provided, all users that have explicit access to an integration will be subscribed to the specified integration(s).

If the user you specify via --subscribeUsernames is a Polarity Admin user, they will be subscribed to the integration even if they are not explicitly listed on the permissions page.

Example

Subscribe a single user with the username alice:

--subscribeUsernames=alice

Subscribe multiple users:

--subscribeUsernames=alice,bob,mallory

If specifying a comma delimited list, no spaces should be included between usernames

--includeAdmins

By default, if you do not specify specific users to subscribe via the --subscribeUsernames option, the script will subscribe all users that have explicit access to the integration. This means that only users that are listed under the Permissions tab of the integration or users that are in a group listed under the Permissions tab will be subscribed. If you would like to subscribe all "admin" users to the integration (even if they do not have explicit access granted), you can pass in the --includeAdmins flag.

--includeAdmins

--rejectUnauthorized

Set this to false if your Polarity Server has a self signed SSL certificate that is not trusted

--rejectUnauthorized=false

--proxy

Set this to a proxy configuration string if you need to use a proxy to access your Polarity Server.

--proxy=https://USERNAME:PASSWORD@PROXYSERVER:PROXYPORT

As the CLI tool is running on your Polarity Server you can typically work around any proxy issues by simply setting the --url option to https://localhost

Example Usage

Prior to running any of the below script commands, change into the scripts directory

cd /app/polarity-integration-auto-subscribe

In all of these examples we assume we are connecting to our Polarity server hosted at https://my-polarity-server.corp with the admin user who has a password of password123!.

You can see what your command will do without making any changes by adding the --simulate option to the end of your command.

Subscribe a single user named polarity_user to a single integration arin

sudo ./polarity-integration-auto-subscribe.sh \
  --url=https://my-polarity-server.corp \
  --username=admin \
  --password='password123!' \
  --subscribeUsernames=polarity_user \
  --integrations=arin

Subscribe all eligible users to a single integration called arin

sudo /polarity-integration-auto-subscribe.sh \
  --url=https://my-polarity-server.corp \
  --username=admin \
  --password='password123!' \
  --integrations=arin

Subscribe a single user named polarity_user to both the arin and ldap integrations:

sudo /polarity-integration-auto-subscribe.sh \
  --url=https://my-polarity-server.corp \
  --username=admin \
  --password=password123! \
  --subscribeUsernames=polarity_user \
  --integrations=arin,ldap

Subscribe a two users named polarity_user and polarity_user_2 to both the arin and ldap integrations:

sudo /polarity-integration-auto-subscribe.sh \
  --url=https://my-polarity-server.corp \
  --username=admin \
  --password='password123!' \
  --subscribeUsernames=polarity_user,polarity_user_2 \
  --integrations=arin,ldap

Subscribe all users to both arin and ldap integrations

sudo /polarity-integration-auto-subscribe.sh \
  --url=https://my-polarity-server.corp \
  --username=admin \
  --password='password123!' \
  --integrations=arin,ldap

Subscribe all eligible users including all admins to both arin and ldap integrations

sudo /polarity-integration-auto-subscribe.sh \
  --url=https://my-polarity-server.corp \
  --username=admin \
  --password='password123!' \
  --integrations=arin,ldap
  --includeAdmins