Policy objects

Policy Objects

IP Lists

class illumio.policyobjects.IPList

Represents an IP list in the PCE.

IP lists are list of IP addresses, subnets, CIDR blocks, and/or FQDNs. They can be used in conjunction with other security policy objects to allow or deny traffic from these defined ranges.

See https://docs.illumio.com/core/21.5/Content/Guides/security-policy/security-policy-objects/ip-lists.htm

Usage:

>>> from illumio import PolicyComputeEngine, IPList, IPRange
>>> pce = PolicyComputeEngine('my.pce.com')
>>> pce.set_credentials('api_key_username', 'api_key_secret')
>>> ip_list = IPList(
...     name='IPL-INTERNAL',
...     ip_ranges=IPRange(
...         from_ip='192.168.0.0/16'
...     )
... )
>>> ip_list = pce.ip_lists.create(ip_list)
>>> ip_list
IPList(
    href='/orgs/1/sec_policy/draft/ip_lists/22',
    name='IPL-INTERNAL',
    ip_ranges=IPRange(
        from_ip='192.168.0.0/16'
    ),
    ...
)

Labels

class illumio.policyobjects.Label

Represents a label in the PCE.

Labels help to configure the reach of policy rules in a dynamic way, without relying on precise identifiers like IP addresses.

When fetching Labels from the PCE, a breakdown of the labels’ usage can be optionally included.

See https://docs.illumio.com/core/21.5/Content/Guides/security-policy/security-policy-objects/labels-and-label-groups.htm

Usage:

>>> import illumio
>>> pce = illumio.PolicyComputeEngine('pce.company.com', port=443, org_id=1)
>>> pce.set_credentials('api_key', 'api_secret')
>>> label = illumio.Label(key='role', value='R-DB')
>>> label = pce.labels.create(label)
>>> label
Label(
    href='/orgs/1/labels/18',
    key='role',
    value='R-DB',
    ...
)

class illumio.policyobjects.LabelGroup

Represents a label group in the PCE.

Label groups can contain labels and other sub-groups to define broader categories that are often grouped when writing rules or otherwise referencing multiple labels.

See https://docs.illumio.com/core/21.5/Content/Guides/security-policy/security-policy-objects/labels-and-label-groups.htm

Usage:

>>> import illumio
>>> pce = illumio.PolicyComputeEngine('pce.company.com', port=443, org_id=1)
>>> pce.set_credentials('api_key', 'api_secret')
>>> dev_label = pce.labels.create({'key': 'env', 'value': 'E-Dev'})
>>> stage_label = pce.labels.create({'key': 'env', 'value': 'E-Stage'})
>>> label_group = illumio.LabelGroup(
...     key='role',
...     name='LG-E-PreProd',
...     labels=[dev_label, stage_label]
... )
>>> label_group = pce.label_groups.create(label_group)
>>> label_group
LabelGroup(
    href='/orgs/1/sec_policy/draft/label_groups/5704a6f4-e051-4f88-9149-713ee22b5d41',
    key='role',
    value='R-DB',
    ...
)

class illumio.policyobjects.LabelSet

Represents a set of labels with distinct keys.

Used to define rule set scopes.

Parameters:

labels (List[Reference], optional) – list of label and label group references in the set.

Label Dimensions

class illumio.policyobjects.LabelDimension

Represents a label dimension (label type) in the PCE.

Label dimensions define the types of labels available in the PCE. The default dimensions are Role, Application, Environment, and Location, but custom dimensions can be created (e.g., ‘Business Unit’, ‘Tenant’).

Available since PCE v24.5.

See https://docs.illumio.com/core/24.5/Content/Guides/security-policy/security-policy-objects/labels-and-label-groups.htm

Usage:

>>> import illumio
>>> pce = illumio.PolicyComputeEngine('pce.company.com', port=443, org_id=1)
>>> pce.set_credentials('api_key', 'api_secret')
>>> # List all label dimensions
>>> dimensions = pce.label_dimensions.get()
>>> for dim in dimensions:
...     print(f"{dim.key}: {dim.display_name}")
role: Role
app: Application
env: Environment
loc: Location
>>> # Create a custom label dimension
>>> dimension = illumio.LabelDimension(
...     key='bu',
...     display_name='Business Unit',
...     display_info=illumio.LabelDimensionDisplayInfo(
...         icon='group',
...         initial='BU',
...         background_color='#ebbb0f',
...         foreground_color='#000000',
...         display_name_plural='Business Units'
...     )
... )
>>> dimension = pce.label_dimensions.create(dimension)
>>> dimension
LabelDimension(
    href='/orgs/1/label_dimensions/...',
    key='bu',
    display_name='Business Unit',
    ...
)

Services

class illumio.policyobjects.Service

Represents a service in the PCE.

A service can be port-based or process-based (Windows services).

Each service contains one or more objects defining the port, protocol, and/or process name used by an application running on a workload.

Service objects are used to write rules or enforcement boundaries to allow or deny traffic on its defined ports and processes for workloads in the network.

See https://docs.illumio.com/core/21.5/Content/Guides/security-policy/security-policy-objects/services.htm

Usage:

>>> import illumio
>>> pce = illumio.PolicyComputeEngine('pce.company.com', port=443, org_id=1)
>>> pce.set_credentials('api_key', 'api_secret')
>>> service = illumio.Service(
...     name='S-HTTP',
...     service_ports=[
...         illumio.ServicePort(port=80, proto='tcp'),
...         illumio.ServicePort(port=443, proto='tcp')
...     ]
... )
>>> service = pce.services.create(service)
>>> service
Service(
    href='/orgs/1/sec_policy/draft/services/15',
    name='S-HTTP',
    service_ports=[
        ServicePort(
            port=80,
            proto=6,
            ...
        ),
        ...
    ],
    ...
)

Virtual Services

class illumio.policyobjects.VirtualService

Represents a virtual service object in the PCE.

Virtual services provide an abstraction for a service that can be bound to one or more workloads. This can be useful when a workload is running multiple services, or multiple instances of the same service for different apps.

See https://docs.illumio.com/core/21.5/Content/Guides/security-policy/security-policy-objects/virtual-services.htm

Usage:

>>> import illumio
>>> pce = illumio.PolicyComputeEngine('pce.company.com', port=443, org_id=1)
>>> pce.set_credentials('api_key', 'api_secret')
>>> role_label = pce.labels.create({'key': 'role', 'value': 'R-Tomcat'})
>>> app_label = pce.labels.create({'key': 'app', 'value': 'A-App'})
>>> env_label = pce.labels.create({'key': 'env', 'value': 'E-Dev'})
>>> loc_label = pce.labels.create({'key': 'loc', 'value': 'L-NYC'})
>>> tomcat_svc = pce.services.create(illumio.Service(
...     name='S-Tomcat',
...     service_ports=[
...         {
...             'port': 80,
...             'proto': illumio.convert_protocol('tcp')
...         },
...         {
...             'port': 443,
...             'proto': illumio.convert_protocol('tcp')
...         }
...     ]
... )
>>> virtual_service = illumio.VirtualService(
...     name='VS-Tomcat',
...     apply_to=illumio.ApplyTo.HOST_ONLY,
...     service=tomcat_svc,
...     labels=[role_label, app_label, env_label, loc_label]
... )
>>> virtual_service = pce.virtual_services.create(virtual_service)
>>> virtual_service
VirtualService(
{
    "href": "/orgs/1/sec_policy/draft/virtual_services/14d7ff69-2fa4-458b-a299-e3f11ffa9b01",
    "created_at": "2021-10-05T12:34:56.789Z",
    "updated_at": "2021-10-05T12:34:56.789Z",
    "deleted_at": null,
    "created_by": {
        "href": "/users/1"
    },
    "updated_by": {
        "href": "/users/1"
    },
    "deleted_by": null,
    "update_type": "create",
    "name": "VS-INTERNAL",
    "description": null,
    "pce_fqdn": null,
    "service_ports": [
        {
            "port": 1234,
            "proto": 6
        },
        {
            "port": 80,
            "proto": 17,
            "to_port": 443
        }
    ],
    "service_addresses": [
        {
            "ip": "1.1.1.1",
            "port": 101
        },
        {
            "description": "test description",
            "fqdn": "*.illumio.com"
        }
    ],
    "labels": [
        {
            "href": "/orgs/1/labels/1",
            "key": "role",
            "value": "R-WEB"
        },
        {
            "href": "/orgs/1/labels/2",
            "key": "app",
            "value": "A-HRM"
        },
        {
            "href": "/orgs/1/labels/3",
            "key": "env",
            "value": "E-STAGE"
        },
        {
            "href": "/orgs/1/labels/4",
            "key": "loc",
            "value": "L-TOR"
        }
    ],
    "ip_overrides": [
        "1.2.3.4"
    ],
    "apply_to": "host_only",
    "caps": [
        "write",
        "provision",
        "delete"
    ]
}
)

Raises:

IllumioException – if an invalid apply_to value is provided.

class illumio.policyobjects.ServiceBinding

Represents a service binding between a virtual service and a workload.

The /service_bindings POST method accepts a list of bindings and returns a list containing either the binding HREF (if the workload was successfully bound to the virtual service) or an error token and message.

NOTE: Service bindings can only be created using an active virtual service.

See https://docs.illumio.com/core/21.5/Content/Guides/security-policy/security-policy-objects/virtual-services.htm#BindaVirtualServicetoaWorkload

Usage:

>>> import illumio
>>> workload = pce.workloads.create(illumio.Workload(
...     name='haproxy0.company.com',
...     hostname='haproxy0.company.com',
...     public_ip='10.0.14.201'
... ))
>>> virtual_service = pce.virtual_services.create(illumio.VirtualService(
...     name='VS-HAProxy',
...     apply_to=illumio.ApplyTo.HOST_ONLY,
...     service_ports=[{'port': 443, 'proto': convert_protocol('tcp')}]
... ))
>>> policy_version = pce.provision_policy_changes(
...     change_description="Create HAProxy virtual service",
...     hrefs=[virtual_service.href]
... )
>>> virtual_service.href = convert_draft_href_to_active(virtual_service.href)
>>> service_binding = illumio.ServiceBinding(
...     virtual_service=virtual_service,
...     workload=workload,
...     port_overrides=[illumio.PortOverride(port=443, new_port=8443, proto='tcp')]
... )
>>> bindings = pce.service_bindings.create([service_binding])
{
    'service_bindings': [
        ServiceBinding(href='/orgs/1/service_bindings/bc98cf25-8f24-4989-853c-578fa14108cf')
    ],
    'errors': []
}

Virtual Servers

class illumio.policyobjects.VirtualServer

Represents a virtual server object in the PCE.

Virtual servers are used to model load-balanced services. They exist under the security policy and require provisioning.

class illumio.policyobjects.DVSVirtualServer

Represents a discovered virtual server entry within a VirtualServer.