Rules

This Public Stable API creates, updates, and deletes individual rules in rulesets.

It also gets a collection of rules from a ruleset.

Illumio Core allowlist policy model uses rules to define the allowed communications between two or more workloads or between workloads and other entities, such as IP lists, virtual servers, and the internet.

Rules API Methods

The fundamental structure of a rule (except custom iptables rules) consists of a Source, a service that the source makes available over a network port and protocol, and a Destination of that service.

Table 4. API Methods for Rules

Functionality	HTTP	URI
Get rules	`GET`	sec_policy_rule_sets_sec_rules
Get rules for providers.	`GET`	sec_policy_rule_sets_sec_rules_providers
Get rules for destinations.	`GET`	sec_policy_rule_sets_sec_rules_destination
Update rules	`PUT`	sec_policy_rule_sets_sec_rules
Update rules for providers	`PUT`	sec_policy_rule_sets_sec_rules_providers
Update rules for destinations	`PUT`	sec_policy_rule_sets_sec_rules_destinations
Create rules	`POST`	sec_policy_rule_sets_sec_rules
Delete an individual rule.	`DELETE`	sec_rule_href

Rule Types

Illumio's security policy includes three rule types: intra-scope rules, extra-scope rules, and custom iptables rules:

Intra-scope rules allow communication between Sources and Destinations within a specific scope.
Extra-scope rules permit communication between applications. You can write rules so that destinations within or outside a specified scope can access the providers within a scope. For extra-scope rules, the labels used in the scope must match the labels used by the Source.

Custom iptables rules are needed for your applications as part of the rules managed by the PCE. These rules help preserve configured iptables from native Linux host configurations by allowing you to include them with the rules for your policy.

Deny Rules

This API gets, creates, updates, and deletes deny rules. Deny rules deny communication between sources and destinations.

Deny Rules API Methods

Functionality	HTTP	URI
Get a collection of deny rules.	`GET`	`[api_version][org_href]/sec_policy/:pversion/rule_sets/:rule_set_id/deny_rules`
Get a specified deny rule instance.	`GET`	`[api_version][org_href]/sec_policy/:pversion/rule_sets/:rule_set_id/deny_rules/:deny_rule_id`
Create a deny rule.	`POST`	`[api_version][org_href]/sec_policy/:pversion/rule_sets/:rule_set_id/deny_rules`
Update a specified deny rule.	`PUT`	`[api_version][org_href]/sec_policy/:pversion/rule_sets/:rule_set_id/deny_rules/:deny_rule_id`
Delete a specified deny rule.	`DELETE`	`[api_version][org_href]/sec_policy/:pversion/rule_sets/:rule_set_id/deny_rules/:deny_rule_id`

Rule Search

This Public Experimental method searches for rules across all rulesets. This method is especially useful when your organization has many rules organized in rulesets.

For example, your organization has 192,000 rules organized across 650 rulesets, and you need to know how many rules are applied for SNMP (UDP 161). You can’t easily find this information without using this method.

Note

Rule search concurrent requests are now increased to 12 searches on 2x2s and 4x2s.

Rule Search Methods

Table 5. Rule Search Methods

Functionality	HTTP	URI
Create rule search	POST	`/api/v2/orgs/:xorg_id/sec_policy/:pversion/rule_search`

Rule Search exposes deny_rules and override_deny rules in the UI when you search for them in the Rule Search page.

For the changes in the UI, see Security Policy Guide, Policy Check and Rule Search.

Table 6. New Property

Property Name	Type	Description	Required
`rule_types`	Array of enums: `sec_rules` `deny_rules` `override_deny_rules`	Requested rule_types that should be searched for	No

Property Name

Type

Description

Required

rule_types

Array of enums:

sec_rules

deny_rules

override_deny_rules

Requested rule_types that should be searched for

Rules Reference

This topic covers properties, parameters, and examples of rules.

Parameters

Get a collection of security rules from a ruleset

Parameter	Description	Type	Required
`org_id`	Organization	Integer	Yes
`pversion`	Security policy version -- `draft`(not provisioned) or `active` (provisioned)	String	Yes
`rule_set_id`	Ruleset ID	Integer	Yes
`external_data_reference`	A unique identifier within the external data source. For example, if this rule information is stored in an external database.	String	No
`external_data_set`	The data source from which the resource originates. For example, if this rule information is stored in an external database.	String	No
`labels`	List of lists of label URIs, encoded as a JSON string	String	No
`max_results`	Maximum number of Rule Sets to return	Integer	No
`name`	Name of Rule Set(s) to return. Supports partial matches	String	No

Get an Individual Security Rule from a Ruleset

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

pversion

Security policy version -- draft(not provisioned)

or active (provisioned)

String

Yes

rule_set_id

Ruleset ID

Integer

Yes

Properties to create rules

Property	Description	Type	Required
`enabled`	Indicates if the rule is enabled or disabled.	Boolean	Yes
`providers`	Entities that can be used as a Source in a rule. Reference to `sec_policy_rule_sets_sec_rules_providers_put.schema.json`		Yes
`consum`	Entities that can be used as a Destination in a rule. Reference to `sec_policy_rule_sets_sec_rules_destinations_put.schema.json`		Yes
`ingress_services`	Reference to `sec_rule_ingress_services.schema.json`		Yes
`resolve_labels_as`	Reference to `sec_rule_resolve_labels_as.schema.json`		Yes
`sec_connect`	Indicates whether a secure connection is established. If set to true, then the rule will use SecureConnect IPsec encryption for all traffic allowed by the rule.	Boolean	No
`stateless`	Whether packet filtering is stateless for the rule. If set to true, then the rule's packet filtering is stateless. This means that the VEN will instruct the host firewall to not maintain persistent connections for a session. This type of rule is typically used for datacenter “core services” such as DNS and NTP. You can only create a total of 100 stateless rules in your PCE. If you need more than 100 stateless rules in your Illumio policy, contact your Illumio Professional Services Representative for more information.	Boolean	No
`machine_auth`	Whether machine authentication is enabled. If set to true, then machine authentication is used for the rule, meaning that any hosts defined in the rule have been configured for the PKI-based machine authentication. Before using this property, your PCE must already be configured for machine authentication. See the PCE Administration Guide for information on configuring machine authentication for the PCE.	Boolean	No
`consuming_security_principals`	Reference to `common/consuming_security_principals_put.schema.json`
`unscoped_destinations`	Set the scope for rule destinations to All	Boolean
`network_type`	Reference to `common/rule_network_type.schema.json`
`use_workload_subnets`	Reference to `sec_rule_use_workload_subnets.schema.json`

Update Rules

This API updates an individual rule inside a ruleset.

URI to Update Rules

PUT [api_version][sec_rule_href]

The request body and JSON payload is the same as that for creating rules.

Delete a Rule

This API deletes an individual rule inside a ruleset.

URI to Delete a Rule

DELETE [api_version][sec_rule_href]

Curl Command to Delete Rule

The curl command for deleting a rule can be structured as follows:

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/sec_policy/draft/rule_sets/152/sec_rules/124 -H "Accept: application/json" -u $KEY:$TOKEN

Examples for Rule Search

Curl Command Examples for Rule Search

curl -u API_ID:API_SECRET -X POST -H 'Content-Type: application/json' -d '{"providers": [{"label": {"href": "/orgs/1/labels/2"}}],"destinations": [{"label": {"href": "/orgs/1/labels/1"}}]}'https://dev6.ilabs.io:8443/api/v2/orgs/1/sec_policy/draft/rule_search

curl -u API_ID:API_SECRET -X POST -H 'Content-Type: application/json' -d '{"providers": [{"workload": {"href": "/orgs/1/workloads/4ce873d3-2e5d-4f06-82f5-4b1e0ec9ceb2"}}]}'https://dev6.ilabs.io:8443/api/v2/orgs/1/sec_policy/draft/rule_search

curl -u API_ID:API_SECRET -X POST -H 'Content-Type: application/json' -d '{"ingress_services": [{"href": "/orgs/1/sec_policy/draft/services/1"}]}'https://dev6.ilabs.io:8443/api/v2/orgs/1/sec_policy/draft/rule_search

curl -u API_ID:API_SECRET -X POST -H 'Content-Type: application/json' -d '{"ingress_services": [{"port": 11000, "to_port": 12000, "proto": 6}]}'https://dev6.ilabs.io:8443/api/v2/orgs/1/sec_policy/draft/rule_search

Get a Rule

$curl -X GET https://pce.my-company.com:8443/api/v2/orgs/1/sec_policy/active/rule_ sets/ -H "Accept: application/json" -u api_1c2618a67847c94b8:98c76f7a4563f29cd78b3392684cd5ec09534bafe5197fe8e901d95561bdd8f5| jq

Response

[
	{
	"href": "/orgs/1/sec_policy/active/rule_sets/1",
	"created_at": "2023-04-05T23:08:32.578Z",
	"updated_at": "2023-04-05T23:08:32.632Z",
	"deleted_at": null, "created_by": {
		"href": "/users/0"
		},
	"updated_by": {
		"href": "/users/0"
		},
	"deleted_by": null,
	"name": "Default",
	"description": null,
	"enabled": true, "scopes": [ []
		],
	"rules": [
		{
		"href": "/orgs/1/sec_policy/active/rule_sets/1/sec_rules/1",
	"created_at": "2023-04-05T23:08:32.599Z",
	"updated_at": "2023-04-05T23:08:32.632Z",
	"deleted_at": null, "created_by": {
		"href": "/users/0"
		},
	"updated_by": {
		"href": "/users/0"
		},
	"deleted_by": null,
	"description": "Allow outbound connections",
	"enabled": true,
	"providers": [ {
	"ip_list": {
		"href": "/orgs/1/sec_policy/active/ip_lists/1"
		}
		}
	],
	"destinations": [ {
	"actors": "ams"
		}
		],
	"consuming_security_principals": [],
	"sec_connect": false,
	"stateless": false,
	"machine_auth": false,
	"unscoped_destinations": false,
	"network_type": "brn",
	"use_workload_subnets": [], "ingress_services": [
		{
		"href": "/orgs/1/sec_policy/active/services/1" }
		],
	"egress_services": [],
	"resolve_labels_as": {
	"providers": [
	"workloads"
		],
	"destinations": [
	"workloads"
		]
	}
}
],

Create a Rule

curl -u api_1c2618a67847c94b8:98c76f7a4563f29cd78b3392684cd5ec09534bafe5197fe8e901d95561bdd8f5 -X POST -H 'Content-Type: application/json' -d '{"providers":[{"label": {"href":"/orgs/1/labels/14"}}],"destinations":[{"label":{"href":"/orgs/1/labels/15"}}],"enabled":true,"ingress_services":[{"href":"/orgs/1/sec_policy/draft/services/9"},{"proto":6,"port":23000}],"network_type":"brn","consuming_security_principals":[],"sec_connect":true,"machine_auth":false,"stateless":false,"unscoped_ destinations":false,"description":"","use_workload_subnets":[],"resolve_labels_as": {"destinations":["workloads"],"providers":["workloads"]}}' https://2x2testvc168.ilabs.io:8443/api/v2/orgs/1/sec_policy/draft/rule_sets/3/sec_ rules | jq

{
	"href": "/orgs/1/sec_policy/draft/rule_sets/3/sec_rules/9",
	"created_at": "2023-04-06T00:58:55.061Z",
	"updated_at": "2023-04-06T00:58:55.088Z",
	"deleted_at": null, "created_by": {
		"href": "/users/1"
		},
	"updated_by": {
		"href": "/users/1"
		},
	"deleted_by": null,
	"update_type": "create",
	"description": "",
	"enabled": true, "providers": [
		{
		"label": {
			"href": "/orgs/1/labels/14"
		},
		"exclusion": false
			}
			],
	"destinations": [
		{
		"label": {
			"href": "/orgs/1/labels/15"
		},
		"exclusion": false
		}
	],
	"consuming_security_principals": [],
		"sec_connect": true,
		"stateless": false,
		"machine_auth": false,
		"unscoped_destinations": false,
		"network_type": "brn",
	"use_workload_subnets": [], "ingress_services": [
		{
		"href": "/orgs/1/sec_policy/draft/services/9"
		}, {
			"port": 23000,
			"proto": 6
			}
			],
	"egress_services": [], 
	"resolve_labels_as": {
	"providers": [
		"workloads"
		],
	"destinations": [
		"workloads"
		]
	}
}

Update a Rule

curl -w "%{http_code}" -u api_1c2618a67847c94b8:98c76f7a4563f29cd78b3392684cd5ec09534bafe5197fe8e901d95561bdd8f5 -X PUT -H 'Content-Type: application/json' -d '{"providers":[{"exclusion":false,"label":{"href":"/orgs/1/labels/14"}}],"destinations":[{"exclusion":false,"label":{"href":"/orgs/1/labels/15"}}],"enabled":true,"ingress_services":[{"href":"/orgs/1/sec_policy/draft/services/9"},{"proto":6,"port":25000}],"network_type":"brn","consuming_security_principals": [],"sec_connect":true,"machine_auth":false,"stateless":false,"unscoped_ destinations":false,"description":"","use_workload_subnets":[],"resolve_labels_as":{"providers":["workloads"],"destinations":["workloads"]}}' https://2x2testvc168.ilabs.io:8443/api/v2/orgs/1/sec_policy/draft/rule_sets/3/sec_ rules/3 | jq

Response

The rule was successfully updated:

Rulesets

This Public Stable API lets you get, create, update, and delete rulesets. Rulesets contain rules and scopes, which define where the rules apply.

Ruleset API Methods

Functionality	HTTP	URI
Get a collection of rulesets.	`GET`	`[api_version][org_href]/sec_policy/rule_sets`
Get a specified ruleset instance.	`GET`	`[api_version[org_href]/sec_policy/rule_sets/rule_set_id]`
Create a ruleset.	`POST`	`[api_version][org_href]/sec_policy/rule_sets`
Update a specified ruleset.	`PUT`	`[api_version][org_href]/sec_policy/rule_sets/rule_set_id]`
Delete a specified ruleset.	`DELETE`	`[api_version][org_href]/sec_policy/rule_sets/rule_set_id]`

Active vs. Draft

This API operates on provisionable objects, which exist in either a draft (not provisioned) state or an active (provisioned) state.

Provisionable items include label groups, services, rulesets, IP lists, virtual services, firewall settings, enforcement boundaries, and virtual servers. For these objects, the URL of the API call must include the element called :pversion, which can be set to either draft or active.

Depending on the method, the API follows these rules:

For GET operations — :pversion can be draft, active, or the ID of the security policy.
For POST, PUT, DELETE — :pversion can be draft (you cannot operate on active items) or the ID if the security policy.

Ruleset Components

Rulesets are the core of Illumio Core policy model and consist of the following elements:

Scopes
Scopes, encompassing sets of labels like application, environment, and location, delineate the boundaries of rules within a ruleset. Workloads sharing common labels within a ruleset scope are bound by the rules specified in the ruleset. A scope can comprise zero or more application, environment, and location labels and may include label groups.
An empty array scope ([]) signifies inclusion of all applications, environments, and locations. If a label type is omitted, all instances of that type are permitted unless other labels are present. However, using a label type in a rule necessitates that the scope for that label type is set to "All." Rulesets can efficiently incorporate multiple scopes to address a given policy's specific security requirements.
A ruleset is not limited to a single scope. A rule can contain multiple scopes depending on the security policy's needs.
Important
Role labels are not used in scopes but can be used in rules. Never use a role label in a scope.
Rules
A security rule comprises multiple providers offering services over specific ports and protocols, destinations utilizing the services provided by the source, and various specified services. Sources and destinations within these rules can represent individual workloads, role labels denoting multiple workloads, IP lists, among other possibilities.

Example Ruleset Scope

Each label in a scope is identified by its HREF. This is the JSON representation of a single ruleset scope with three labels.

Each label must have a different key (role, app, loc, or env). Duplicate label keys are allowed in a scope only if they are in a label group.

{
  "scopes": [
    [
      {"label": {"href": "/orgs/7/labels/105"}},
      {"label": {"href": "/orgs/7/labels/88"}},
      {"label": {"href": "/orgs/7/labels/98"}}
    ]
  ]
}

Ruleset Rules

Note

The common schema consuming_security_principals has been replaced by two other APIs: consuming_security_principals_get and consuming_security_principals_put

Ruleset rules define the allowed communication between workloads or between workloads and IP lists.

For information, see Rules.

Get Rulesets

This method gets all of the rulesets in your organization, including those in the “draft” policy state, which means the current state of rulesets that have not been provisioned.

By default, the maximum number of rulesets returned in a GET collection is 500.

Note

To return more than 500 rulesets, use Asynchronous GET Collection.

URI to Get a Collection of Rulesets

pversion: Contains provisionable objects in either a draft (not provisioned) or active (provisioned) state.

GET [api_version][org_href]/sec_policy/:pversion/rule_sets

URI to Get an Individual Ruleset

[api_version[org_href]/sec_policy/rule_sets/rule_set_id]

Create a Ruleset

This method creates an individual ruleset. The PCE web console supports up to 500 rules per ruleset.

Note

To write more than 500 rules for a particular ruleset, create additional rulesets, or use REST API. More than 500 rules are not fully displayed in the PCE web console.

URI to Create a Ruleset

POST [api_version][ruleset_href]

Update a Ruleset

To update an individual ruleset, you need its HREF, which you can obtain when you retrieve a collection or an individual ruleset.

If you want to add a single rule to an existing ruleset, use

PUT /api/v2/orgs/1/sec_policy/draft/rule_sets/123/sec_rules.

Delete a Ruleset

To delete an individual ruleset, you need its HREF, which you can obtain when you get a collection of rulesets.

URI to Delete an Individual Ruleset

DELETE [api_version][ruleset_href]

Illumio REST APIs 25.4

Rules

Rules API Methods

Rule Types

Deny Rules

Deny Rules API Methods

Rule Search

Note

Rule Search Methods

Rules Reference

Parameters

Properties to create rules

Update Rules

Delete a Rule

Examples for Rule Search

Rulesets

Ruleset API Methods

Active vs. Draft

Ruleset Components

Important

Example Ruleset Scope

Ruleset Rules

Note

Get Rulesets

Note

Create a Ruleset

Note

Update a Ruleset

Delete a Ruleset

Search results