Updated on September 11, 2024

Illumio Plugin for Threat Exchange

Illumio Plugin for Threat Exchange

This document explains how to configure the v1.0.1 Illumio plugin with the Threat Exchange module of the Netskope Cloud Exchange platform. The Illumio plugin is designed to fetch the URLs (IP Addresses and Hostname) from Workloads > Interfaces and store them in Netskope CE. This plugin does not support push functionality.

Prerequisites

To complete the plugin configuration, you’ll need:

  • A Netskope tenant (or multiple, for example, production and development/test instances) that is already configured in Cloud Exchange.
  • A Netskope Cloud Exchange tenant with the Threat Exchange module already configured.
  • A Secure Web Gateway subscription for URL sharing. Refer to URL Lists for more information.
  • Connectivity to the following host: https://login.illum.io/login (Illumio platform).
CE Version Compatibility

Netskope CE v4.2.0, v5.0.1

Illumio Plugin Support

This plugin is used to pull IoCs of the type URLs (IP Addresses and Hostname) from Workloads on the Illumio PCE-based on the configured Label scope. This plugin does not support sharing of indicators to the Illumio platform.

Fetched indicator types URLs (IP Addresses, Hostname)
Shared indicator types Not Supported
Mappings
Pull Mapping
Netskope CE Fields Illumio Fields
value workload.interfaces, workload.hostname
type IndicatorType.URL
firstSeen workload.created_at
lastSeen workload.updated_at
comments Illumio Workload – {workload.name} {workload.description}
extendedInformation {pce_url}/#/workloads/{workload_id}
tags workload.labels
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 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

This performance has been conducted on a large CE instance with below-mentioned specifications by pulling 100K IOCs.

Stack details Size: Large
RAM: 32 GB
CPU: 16 Cores
Indicators fetched from Illumio ~7K per minute
Indicators shared with Illumio Not Supported
User Agent

netskope-ce-5.0.1-cte-illumio-v1.0.1

Workflow

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

Click play to watch a video.

 

Generate the API Authentication Username, Password and Organization ID

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

Get Labels

  1. In Illumio, go to Servers and 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.
  2. Search for and select the Illumio plugin box to open to the plugin configuration page.
  3. Enter the Basic Information page for the plugin:
    • Configuration Name: Enter a valid name for the plugin (alphanumeric and spaces).
    • Sync Interval: Adjust the resync interval for the plugin.
    • Aging Criteria: Adjust the expiration time for the Threat IoCs created by the plugin.
    • Override Reputation: Optionally, set the reputation values for Threat IoCs created by the plugin.
    • Enable SSL verification: Toggle TLS certificate verification when connecting to the PCE.
    • Use System Proxy: Toggle the use of the HTTP/S proxy configured in Netskope when connecting to the PCE.

  4. Click Next.
  5. Enter the Configuration Parameters for the plugin:
    • PCE URL: Enter the PCE Base URL. 
    • PCE Port Number: Enter the port number the PCE cluster is listening on. Use 443 for SaaS instances.
    • PCE Organization ID: Enter the Org ID shown when creating the API key.
    • API Authentication Username: Enter the API Username for the key created previously.
    • API Authentication Password: Enter the API Password for the key created previously.
    • Labels: 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. 
    • Enable Tagging: Toggle whether Netskope tags will be created for labels on Workloads within the defined scope.

  6. Click Save in the top-right corner of the page. The configuration will be validated, and the plugin will test the connection to the PCE. The new plugin can now be viewed under Threat Exchange > Plugins.

Configure a Threat Exchange Business Rule for Illumio

A Business Rule is used to filter out the indicators that are to be shared. In order to share IoCs with Illumio, create a business rule using these steps:

  1. Go to Threat Exchange > Business Rules. and click Create New Rule.
  2. Add the Rule name and select the fields through which you want to filter the IoCs. When finished, click Save.

Configure Threat Exchange Sharing for Illumio

Follow these steps to configure the Sharing in order to share the Illumio IoCs to Netskope.

  1. Go to Threat Exchange > Sharing and click Add Sharing Configuration.
  2. Select the Source configuration (Illumio), your Business Rule, and Destination (Netskope).
  3. Select the Target value:
    • For URL List, provide a List Name or create a new list on Netskope by selecting the Create new list option and providing the Create New List name.
    • For Add to Private Apps, provide a Private App Name or you can create a new private app using Create New Private App. Provide a Protocol, TCP Ports, UDP Ports, Publisher, Use Publisher DNS, and other needed values.

  4. Click Save.

Validate the Illumio Plugin

Validate the Pull

To validate the pulling of IoCs from CE, go to Threat Exchange > Threat IoCs and search for the IoCs pulled from the Illumio plugin.

Expand the IoCs to check the tags added.

If the tags are removed or updated on Illumio, they will be reflected on the IoCs stored in CE.

Go to Logging and check the Logs from Illumio platform for pulls.

IoCs are pulled from Servers and Endpoints > Workloads in the Illumio platform.

Note the pull workload.interfaces, workload.hostname from the list of Workloads available on the above page.

Validate the Push

Illumio does not support pushing IoCs.

To validate the IoCs pushed on Netskope from Illumio, go to Policies > Web > URL Lists.

To validate the sharing of Illumio IoCs to Netskope Private Apps, go to Settings > Security Cloud Platform > App Definition > Private Apps.

Troubleshooting

Receiving error while configuring the plugin or pulling data

If you are receiving the below error while configuring the plugin.

CTE Illumio: Illumio API Exception occurred while connecting to PCE for validating credentials. Validate the provided configuration parameters. Error: 401 Client Error: Unauthorized for url: https://poc1.illum.io:443/api/v2/health

It might be due to either of the following:

  • API Key and Secret is invalid/deleted.
  • Labels provided in CE do not exist on the platform.
  • Label format is not correct

What to do:

  • 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.
  • Verify the label added in the configuration and check if they exist on Illumio.
  • 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 data to pull on the Illumio is in bulk, there are high chances that the plugin takes time to pull data.

Share this Doc

Illumio Plugin for Threat Exchange

Or copy link

In this topic ...