Illumio Plugin for Risk Exchange

This document explains how to configure the Illumio v1.0.1 plugin with the Risk Exchange module of the Netskope Cloud Exchange platform. This plugin is used to fetch workloads from Illumio > Servers and Endpoints > Workloads. This plugin does not support any actions on hosts.

Prerequisites

To configure this plugin, you need:

• A Netskope tenant (or multiple, for example, production and development/test instances).
• A Netskope Cloud Exchange instance with the Tenant plugin and Risk Exchange plugin already configured.
• Illumio platform credentials (PCE URL, PCE Port Number, PCE Organization ID, API Authentication Username, API Secret, Label Scope) for API Authentication.
• Connectivity to the following host: Illumio Platform URL (like https://login.illum.io/login).

Illumio Plugin Support

This plugin fetches workloads from Illumio > Servers and Endpoints > Workloads.

Mappings

Mappings are used to view the pulled workloads and their respective details. Fields mapped during plugin configuration will be visible on the Records page after the data is pulled. Here are the suggested mappings to use while configuring the plugin.

Pull Mapping for Workloads

Permissions

Make sure you have Global Access for all scopes. You can check this by clicking on your profile name from the top right corner in My Roles.

pce = PolicyComputeEngine(
                url=configuration.get("pce_url", "").strip().strip("/"),
                port=configuration.get("pce_port"),
                org_id=configuration.get("org_id"),
                **kwargs
            )
            pce._session.headers.update(headers)
            pce.set_credentials(configuration.get("api_username").strip(), configuration.get("api_secret"))
            pce.set_tls_settings(verify=self.ssl_validation)
            if self.proxy:
                pce.set_proxies(
                    http_proxy=self.proxy.get('http', ''),
                    https_proxy=self.proxy.get('https', '')
                )

pce.must_connect()

labels = self.pce.labels.get(
                    params={"key": key, "value": value}
                )

Performance Matrix

These performance readings are conducted on a Large CE Stack with these VM specifications by pulling 500K workloads from the Illumio plugin.

User Agent

netskope-ce-6.0.0-cre-illumio-v1.0.1

Workflow

1. Generate the API Authentication Username, Password and Organization ID.
2. Get Labels.
3. Configure the Illumio plugin.
4. Add a Business Rule.
5. Add an Action.
6. Validate the plugin.

Watch a Video

Click play to watch a video.

Generate the API Authentication Username, Password, and Organization ID

1. Log in to the Illumio platform.
2. In the top right corner, select your account name and click My API Keys.
   

   

3. Click Add. You will see your Org ID. Copy it to use in your plugin. Enter your name and a description for creating an API Authentication Username password, and then click Create.
   

   

4. Save the Authentication Username and Secret value. These will be used to configure the plugin and are only visible this once.
   

   

Get Labels

1. In Illumio, go to Servers and Endpoints > Workloads.
2. Search the Labels available on the search tab. Get the Labels that you want to use in the plugin for pulling data. Hover over the label names to check the type of Label.
   

   

Configure the Illumio Plugin

1. In Cloud Exchange, go to Settings > Plugin Store. Search for and select the Illumiov1.0.1 (CRE) plugin box.
   

   

2. Add a plugin configuration name and change sync interval if needed.
   

   

3. Click Next and enter the Configuration Parameters:
   • PCE URL: Base URL of your Illumio Platform.
   • Port: PCE port number – use 443 for SaaS instances.
   • Organization ID: Illumio PCE Organization ID from My API Keys.
   • API Authentication Username: API Authentication Username generated on the Illumio PCE from My API Keys.
   • API Authentication Password: API Secret generated on the Illumio PCE from My API Keys.
   • Label Scope: One or more label key/value pairs that make up the policy scope for threat workloads. These must have the format key1:value1,key2:value2,… For example: env:Quarantine,loc:ca.
   
   
4. Click Next and select the Entity from the Entity dropdown. The Entity fields can be created on the Schema Editor page, or using the + Add Field option from the field dropdown. Provide the field mapping. For the suggested mappings, refer to ‘Mapping’.
   

   

   Note Workload ID and Hostname fields will be required to pull the hosts.

5. Click Save. Your plugin configuration will be seen at Risk Exchange > Plugins.
   

   

Add a Risk Exchange Business Rule for Illumio

1. In Risk Exchange, go to Business Rules and click Create New Rule.
2. Enter a Rule Name. Select the Entity in which Fields have been configured for the Illumio plugin, and configure the query based on your requirements. The example filters all the xyz fetched from the Illumio plugin.
   

   

3. Click Save.
   

   

Add a Risk Exchange Action for Illumio

The Illumio plugin only supports the following action type:

No Action

No action will be performed for this action. Users can generate UBA alerts in Ticket Orchestrator by using this action and enabling the Generate Alerts toggle in the action.

1. In Risk Exchange, go to Actions and click Add Action Configuration.
2. Select the required Business Rule, Configuration, and Action from their respective dropdowns.
3. Enable the Require Approval toggle if Approval is needed before performing action on the Hosts.
4. If Require Approval is enabled, then to approve the action, go to Cloud Risk Exchange > Action Logs, select the action to be approved, and then click Approve.
5. Click Save.
   

   

Validate the Illumio Plugin

Validate in Cloud Exchange

To validate the pulling in Cloud Exchange:

1. Go to Risk Exchange and click Records. Select the Entity that was selected while configuring the field mapping for Hosts to view the pulled Hosts.
   

   

2. Go to Logging and search for the logs of the plugin.
   

   

3. When a user matches one of the configured business rules, the configured action will be performed on the hosts. This can be seen in the Risk Exchange > Action Logs.
   

   

Validate in Illumio

The Hosts are pulled from Home > Servers & Endpoints > Workloads. All the workload hostnames, along with the associated interfaces address, are pulled from the Illumio platform.

Troubleshooting the Illumio Plugin

Unable to configure the CRE Illumio plugin.

If you are receiving the error while configuring the plugin.

CRE Illumio [CRE Illumio]: Invalid format provided for the Label Scope: must be key1:value1,key2:value2...

CRE Illumio [CRE Illumio]: Illumio API Exception occurred while connecting to PCE for validating credentials. Validate the provided configuration parameters. Error: HTTPSConnectionPool(host='poc1.illum', port=443): Max retries exceeded with url: /api/v2/health (Caused by NewConnectionError(': Failed to establish a new connection: [Errno -2] Name or service not known'))

These errors may be do to one of these reasons:

• API Key and Secret is invalid/deleted.
• PCE URL is invalid.
• Labels provided in CE do not exist on the platform or the format for the label is incorrect.

What to do:

1. Check the plugin credentials if the API Key and Secret is valid. If it is valid, check if the credentials that you are using are still available on Illumio.
2. Verify the labels added in the configuration, and check if they exist on the Illumio platform.
3. Verify the Label format added in the plugin. It is expected that the labels are added in key:value pair format, like loc:ca.

Unable to pull host details in Cloud Exchange

If you are unable to view hosts details on the record table, it could be due to one of the below-mentioned reasons.

• No hosts present on Illumio platform.
• Mapping for all the Illumio fields is not provided while configuring the CRE Illumio plugin.
• Plugin has encountered an error during the plugin lifecycle.

What to do:

1. Make sure hosts are present on Illumio platform.
2. Make sure to provide the needed mappings while configuring the plugin.
3. Make sure that the fields created in an entity are according to the Mapping.
4. Check the logs from the plugin on the Logging page to see if there are any errors. If you are receiving a 409 Conflict error, it will be resolved on its own after a while, but make sure the sync interval for the plugin configuration is 10 mins – 60 mins.