Illumio v1.0.0 Plugin for Risk Exchange

Illumio v1.0.0 Plugin for Risk Exchange

This document explains how to configure the Illumio v1.0.0 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 complete this integration, you need:

  • A Netskope tenant (or multiple, for example, production and development/test instances).
  • A Netskope Cloud Exchange tenant with the Tenant plugin and Risk Exchange module 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).
CE Version Compatibility

Netskope CE v5.1.0

Illumio Plugin Support

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

 Type of data pulled Workloads
Action No Action
Mappings

Mapping will be used to view the pulled workloads and their respective details. Mapped fields during plugin configuration will be visible on the Records page once the data is pulled. Below is the suggested mapping that should be used while configuring the plugin.

Pull Mapping for Workloads
Plugin Field Expected Datatype Suggested Field Name Suggested Field Aggregate Strategy
Workload ID String Workload ID Unique
Hostname String Hostname Unique
Labels List Labels Overwrite
OS ID String OS ID Overwrite
OS Detail String OS Detail Overwrite
OS Type String OS Type Overwrite
Permissions

Make sure you have “Global access” for all scopes. You can check the same by clicking on your profile name from the top right corner > My Roles.

API Details

This plugin uses Python libraries to authenticate with the Illumio API.
Library: illumio (version = ‘1.1.3’)
Create a PCE(PolicyComputeEngine) Object

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', '')
                )

Checks the connection to the PCE

pce.must_connect()

Retrieve Label object HREFs from the PCE

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

Fetch All the workloads matching the Label Scope

workloads = self.pce.workloads.get_async(
                # the labels query param takes a JSON-formatted nested list of
                # label HREFs - each inner list represents a separate scope
                params={
                    'labels': json.dumps(refs),
                    # include label keys/values in the response data
                    'representation': 'workload_labels'
                }
            )
Performance Matrix

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

Stack details Size: Large
RAM: 32 GB
CPU: 16 Cores
Time take to store the pulled and updated Hosts records ~ 25 mins
User Agent

netskope-ce-5.1.0-cre-illumio-v1.0.0

Workflow

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

Click play to watch a video.

 

Generate the API Authentication Username, Password, and Organization ID

  1. Log in to the Illumio platform.
  2. From the top right corner, click on your account name and select My API Keys.
  3. Click Add and enter your name and a description for creating an API Authentication Username password. Click Create.
  4. Save the Authentication Username and Secret value. These needed used to configure the plugin and will only be visible once.

Get Labels

  1. In Illumio, go to Servers & Endpoints > Workloads.
  2. Search the Labels available on Illumio from 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 > Plugins. Search for and select the Illumio v1.0.0 (CRE) plugin box.
  2. Add a plugin configuration name and change the sync interval if needed.
  3. Click Next and enter these 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. Must be of the format key1:value1,key2:value2,… For example: env:Quarantine, loc:ca.

  4. Click Next. Select the Entity from the Entity dropdown. The Entity fields can be created from the Schema Editor page or using the “+ Add Field” option from the field dropdown. Provide the field mapping. For the suggested mappings, refer to Mappings.
    Note that the Workload ID and Hostname fields will be required to pull the hosts.
  5. Click Save.

Add a Risk Exchange Business Rule for Illumio

  1. In Risk Exchange, go to Business Rules.
  2. Click Create New Rule in the top right corner.
  3. Enter a Rule Name. Select the Entity for the Fields configured for the Illumio plugin, and then configure the query based on your requirements. 
  4. Click Save.

Add Risk Exchange Actions for Illumio

The Illumio plugin 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 button.

Notes

  • You can perform the actions on the hosts pulled from Illumio on the Netskope tenant.
  • Configure Netskope related actions (such as Add host to Private App) for the host records pulled from Illumio. To configure the other actions supported by Netskope, refer to the Risk Exchange plugin guide.

Steps to configure the Action

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

Validate the Illumio Plugin

Validate on Cloud Exchange

To validate the pull in Cloud Exchange:

  1. In Risk Exchange, go to 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 Action Logs.

Validate on 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('<urllib3.connection.HTTPSConnection object at 0x7f6eb920a700>: Failed to establish a new connection: [Errno -2] Name or service not known'))

These issues might be due 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

To resolve these issues, follow these steps:

  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 label added in the configuration, and check if they exist on Illumio.
  3. Verify the Label format added in the plugin, it is expected that the labels are added in key:value pair, like loc:ca.

Note that if the hosts to fetch on the Illumio are in bulk, there’s a high chance that the plugin will take some time to fetch data.

Unable to View hosts details on the Record

If you are unable to view hosts details on the record table, it could be due to one of these reasons:

  • No hosts present on Illumio platform.
  • Mapping for all the Illumio fields is not provided while configuring the Illumio plugin.

To resolve these issues, follow these steps:

  1. Make sure hosts are present on Illumio.
  2. Make sure the needed mapping was provided while configuring the plugin.
  3. Make sure that the fields created in an entity are according to the Mappings section.
Share this Doc

Illumio v1.0.0 Plugin for Risk Exchange

Or copy link

In this topic ...