Skip to main content

Illumio Core

Bring your Illumio Core segmentation inventory and policy into the JupiterOne graph. The integration reads the Policy Compute Engine (PCE) of your choice, on-premises or Illumio-hosted, and ingests workloads with their IP addresses, operating system, online state and enforcement mode, the VEN agents installed on them, the labels and label groups that drive label-based policy, IP lists, service definitions, the active rulesets and their rules, paired container clusters, and the PCE's users. Connect workloads to the VENs and labels assigned to them, and connect rules to the service definitions and IP lists they use. You can then query for workloads that are not in full enforcement or have gone offline, workloads with no labels, VENs that are not active, disabled rulesets and rules, and the rules that reference a given IP list or service. Policy objects are read from the active (provisioned) policy only. Draft policy, traffic flows and audit events are not collected.

Installation​

This integration connects to an Illumio Core Policy Compute Engine (PCE) using the PCE REST API v2 (https://<pce-fqdn>:<port>/api/v2/...). It ingests workloads, VENs, labels, label groups, IP lists, service definitions, rulesets and rules, container clusters, and PCE users. Every request is a read-only GET, and security policy objects are read from the active (provisioned) policy, not the draft.

The integration can run in two ways:

  • In the JupiterOne cloud. Use this when your PCE is Illumio-hosted (SaaS) or is reachable from the internet.
  • On a JupiterOne collector in your own network. Use this for an on-premises PCE that the JupiterOne cloud cannot reach.

Prerequisites​

  • An Illumio Core PCE, on-premises or Illumio-hosted, and its FQDN and API port.
  • The organization ID of the PCE organization you want to ingest.
  • An Illumio API key (the authentication username and secret) whose role can read the organization. A service account with the Global Viewer role is recommended.
  • For an on-premises PCE that uses a certificate from a private or internal certificate authority, the CA certificate in PEM format.
  • Access to JupiterOne with permission to configure integrations.

Configuration in Illumio Core​

The integration authenticates with HTTP Basic authentication: the API key's authentication username is the username and the API key secret is the password. On save and at the start of every run, the integration calls GET /api/v2/orgs/{org_id}, which checks the credentials and the organization ID together.

Choose the role​

The integration only reads, so give the credential a read-only role. We recommend the global Global Viewer role. Older PCE versions call this role Global Read Only. It can view any resource and organization setting, but it cannot perform any operations.

The integration does not need the Global Organization Owner or Global Administrator roles, or any provisioning role.

The Users data source reads GET /api/v2/users, which lists the users of the whole PCE, not only one organization. Illumio does not document which roles can call this endpoint. If the credential's role cannot list users, the Users step fails with an authorization error and the other data sources still run. In that case, leave Users disabled.

A service account is not tied to a person, so its access does not end when an employee leaves. Creating one requires an organization owner:

  1. In the PCE web console, go to Access Management > Service Accounts.
  2. Click Add and enter a unique name and, optionally, a description.
  3. Optionally, restrict the API key by IP address. If you do, allow the addresses the integration connects from: your collector's address, or the addresses JupiterOne connects from.
  4. Optionally, change the API key expiration. It cannot be longer than your organization's maximum.
  5. In the Roles and Scopes table, assign the Global Viewer role.
  6. Click Save, then Download Credentials. Keep the authentication username and the secret. You will paste them into JupiterOne.

Service account API keys can expire. Note the expiration date: when the key expires, the PCE rejects it and the integration stops ingesting until you add a new key to the instance.

Option 2: Create an API key for a user​

A user API key has the same access as the user who created it. Sign in as a user who has the Global Viewer role, then:

  1. Open the User menu and select My API Keys.
  2. Click Add, enter a Name and, optionally, a Description, and click Save.
  3. In the API Key Created window, expand Show credentials and copy the Authentication Username and the Secret, or click Download Credentials.

User API keys do not expire. They stay valid until they are deleted.

caution

The credentials are shown only once. If you lose the secret, create a new API key. Paste the Authentication Username (it starts with api_) into the API Key Authentication Username field in JupiterOne, not the Key ID. The PCE uses the authentication username as the Basic-auth username.

Find the port and organization ID​

  • Port: An Illumio-hosted (SaaS) PCE serves the API on 443. An on-premises PCE uses 8443 by default, but the port can differ between implementations. Confirm the port with your PCE administrator.
  • Organization ID: The number in the /orgs/<org_id>/ part of the PCE's API URLs. The integration uses 1 when the field is left empty. Confirm the ID with your PCE administrator if you are unsure.

Configuration in JupiterOne​

To install the Illumio Core integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select Illumio Core. Click New Instance to begin configuring your integration.

Creating an instance requires the following:

  • The Account Name used to identify the Illumio Core account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.

  • Description to assist in identifying the integration instance, if desired.

  • Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.

  • The Authentication fields below.

Authentication fields​

FieldRequiredDescription
PCE URLYesThe PCE FQDN, such as pce.company.com, or its URL, such as https://pce.company.com. Without a scheme, https:// is used. Only the scheme and host are used: a path or a port in the URL is ignored, so set the port in PCE Port.
PCE PortNoThe PCE API port. Defaults to 443, the Illumio SaaS port, when left empty. For an on-premises PCE, enter 8443 or your PCE's configured API port.
Organization IDNoThe PCE organization ID. Defaults to 1 when left empty.
API Key Authentication UsernameYesThe API key's Authentication Username, which starts with api_, for example api_xxxxxxxxxxxx. This is not the Key ID.
API Key SecretYesThe API key secret.

When you save the instance, JupiterOne checks that PCE URL, API Key Authentication Username and API Key Secret are set, then requests GET /api/v2/orgs/{org_id}. A wrong port, an unknown organization ID, a TLS error or rejected credentials all fail this check and are reported as an authentication error.

caution

Leave PCE Port empty only for an Illumio-hosted (SaaS) PCE, which serves the API on 443. An on-premises PCE listens on 8443 by default, so set PCE Port explicitly, or the integration connects to the wrong port.

Filters​

This section holds the TLS settings for an on-premises PCE that uses a certificate from a private or internal certificate authority. Both fields are optional, and an Illumio-hosted PCE needs neither. The integration has no fields that filter which objects are ingested; use the data sources below to choose what to collect.

FieldDefaultDescription
CA CertificateEmptyThe PEM-encoded certificate of the CA that issued the PCE's TLS certificate. The PCE certificate is then verified against this CA.
Disable TLS VerificationOffSkips verification of the PCE's TLS certificate. Not recommended: prefer CA Certificate.

Click Create once all values are provided to finalize the integration.

Data Sources​

Each data source can be enabled or disabled on its own. All data sources are disabled by default, so enable the ones you want to ingest. The illumio_account entity for the PCE organization and the illumio_service entity for Illumio Core are always created.

Data SourceDescriptionEntities Created
WorkloadsWorkloads in the organization, with their hostname, IP addresses, operating system, last heartbeat, online state, enforcement mode and visibility level.illumio_workload
VENsVirtual Enforcement Node agents, with their status, version, platform, type and last heartbeat.illumio_ven
LabelsSegmentation labels, with their key (dimension) and value.illumio_label
Label GroupsLabel groups from the active policy.illumio_label_group
IP ListsIP lists from the active policy, with their IP ranges and FQDNs.illumio_ip_list
Service DefinitionsServices from the active policy, with their ports, protocols and Windows services.illumio_service_definition
Rulesets and RulesRulesets from the active policy and the rules listed in each ruleset, with whether each is enabled.illumio_rule_set, illumio_rule
Container ClustersKubernetes and OpenShift clusters paired with the PCE, with their manager type, container runtime, Kubelink version and online state.illumio_container_cluster
UsersUsers of the PCE, with their username, name, user type and whether the account is locked.illumio_user

To ingest everything the integration supports, enable all nine data sources.

Relationships between objects from two data sources are built only when every data source they need is enabled. If a required data source is disabled, the step that builds the relationship does not run.

RelationshipRequires
illumio_account PROVIDES illumio_serviceAlways created
illumio_account HAS illumio_workloadWorkloads
illumio_account HAS illumio_labelLabels
illumio_account HAS illumio_label_groupLabel Groups
illumio_account HAS illumio_ip_listIP Lists
illumio_account HAS illumio_service_definitionService Definitions
illumio_account HAS illumio_rule_setRulesets and Rules
illumio_rule_set HAS illumio_ruleRulesets and Rules
illumio_account HAS illumio_container_clusterContainer Clusters
illumio_account HAS illumio_userUsers
illumio_workload HAS illumio_venWorkloads and VENs
illumio_workload ASSIGNED illumio_labelWorkloads and Labels
illumio_container_cluster HAS illumio_workloadWorkloads and Container Clusters
illumio_label_group HAS illumio_labelLabel Groups and Labels
illumio_label_group HAS illumio_label_group (group to sub-group)Label Groups and Labels
illumio_rule USES illumio_service_definitionRulesets and Rules, Service Definitions and IP Lists
illumio_rule USES illumio_ip_listRulesets and Rules, Service Definitions and IP Lists
caution

VENs on their own are not connected to anything. A VEN is linked to the graph only through its workload, so enable Workloads together with VENs. Likewise, both USES relationships from rules are built by a single step that needs Rulesets and Rules, Service Definitions and IP Lists all enabled. If any of the three is disabled, no rule is connected to a service definition or an IP list.

A rule is connected to a service definition only when the rule references the service by its HREF. Ports and protocols written directly into a rule do not create a relationship. A rule is connected to an IP list when the IP list is one of the rule's providers or consumers. Rules are not connected to the labels, label groups or workloads in their scopes, providers or consumers.

Example queries​

Workloads that are not in full enforcement:

FIND illumio_workload WITH enforcementMode != 'full'

With the Labels data source also enabled, workloads that have no labels:

FIND illumio_workload THAT !ASSIGNED illumio_label

With Rulesets and Rules, Service Definitions and IP Lists enabled, the rules that use each IP list:

FIND illumio_rule AS r
  THAT USES illumio_ip_list AS l
RETURN r.displayName, r.isEnabled, l.displayName, l.ipRanges

What the integration does not collect​

  • Draft (unprovisioned) policy. Label groups, IP lists, services and rulesets are read from the active policy only.
  • Enforcement boundaries, traffic flows, events and audit logs, pairing profiles, and virtual services.
  • Container cluster pairing tokens. They are secrets and are never ingested.
  • The last login IP address of PCE users.

Rate limits and large organizations​

The PCE allows up to 500 API requests per minute per API key. The integration makes one request per collection, plus a few requests to follow each asynchronous job described below. It makes up to three attempts for a request that fails with 429 Too Many Requests, a 5xx response or a network error. On a 429 it waits for the time given in the Retry-After header, and otherwise it backs off starting at 30 seconds. A request that does not answer within three minutes is timed out and tried again.

A PCE returns at most 500 objects from a regular GET of a collection. When a collection is larger, the integration asks the PCE to build the collection as an asynchronous job, waits for the job to finish, and downloads the result. Each job can take up to 60 minutes. If a job fails or does not finish in time, that data source fails for the run.

If the PCE does not offer container clusters and returns 404 for that collection, the Container Clusters data source is skipped without an error.

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.

Additional resources​