Rules

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

Providers and destinations

The 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.

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.

Rules API Methods

Functionality	HTTP	URI
Get rules	`GET`	`sec_policy_rule_sets_sec_rules`
Get rules for provides	`GET`	`sec_policy_rule_sets_sec_rules_providers`
Get rules for destinations	`GET`	`sec_policy_rule_sets_sec_rules_destinations`
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 rule	`POST`	`sec_policy_rule_sets_sec_rules`
Delete an individual rule	`DELETE`	`sec_rule_href`

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.

Rule Types

There are three types of rules:

Intra-scope rules: Allow communication between providers and destinations within the same security scope.
Extra-scope rules: Rules that go beyond the scope of the ruleset to which they belong. In this rule type, the workloads, labels or IP list in the destinations part of the rule are not constricted by the scope of the ruleset. This type of rule is used when you want specific rules that allow providers to offer a service to other workloads or groups that are not within the boundaries of the ruleset scope.
Custom iptables rules: Used to configure custom iptables rules on Linux workloads; for example, to preserve existing native Linux host iptables rules by including them in a ruleset.

Note

The PCE web console can only display up to 500 rules per ruleset. To write more than 500 rules for a particular scope, consider splitting the rules across multiple rulesets, otherwise users won't be able to view them all in the PCE web console.

Rule Type JSON Specification

To define a rule as either intra-scope or extra-scope, specify if the rule is “scoped” or “not scoped” by defining the 'unscoped_destinations' property:

When a rule has unscoped_destinations: false, this defines an intra-scope rule, which means both its providers and destinations are bound by the ruleset scope.
When a rule has unscoped_destinations: true, this defines an extra-scope rule, which means its providers are bound by the ruleset scope, but the destinations are not bound by the ruleset scope.

Intra-Scope Rule Example

This rule illustrates an intra-scope rule because it has its unscoped_destinations property set to false:

{ 
  "rules": [
    {
      "enabled": true,
      "providers": [ {"label": {"href": "/orgs/1/labels/2"} } ],
      "destinations": [ {"label": {"href": "/orgs/1/labels/1"} } ],
      "consuming_security_principals": [],
      "ingress_services": ["href": "/orgs/1/sec_policy/draft/services/20"],       
      "resolve_labels_as": { 
        "providers": ["workloads"],
        "destinations": ["workloads"]
      },
      "sec_connect": false,
      "unscoped_destinations": false
    }
  ]
}

Stateless Rules

A rule can be configured to have stateless packet filtering ("stateless": true). This means that the VEN instructs the host firewall to not maintain persistent connections for all sessions. This type of rule is typically used for datacenter “core services” such as DNS and NTP.

A stateless rule can have these destination types:

Any IP list plus all workloads
A label (one of a specific type)
An individual item (such as an individual workload)

An attempt to add more destinations, or one not supported, will return an error.

A PCE can only have a maximum of 100 stateless rules. If an implementation requires more than 100 stateless rules, contact your Illumio Professional Services Representative for more information.

Note

This property has an API exposure level of Public Experimental.

For more information, see API Classification and Version.

Get Rules

This API gets a collection of rules or gets an individual rule from a ruleset.

Before you can get rules from a ruleset with this API, you need to obtain the ruleset HREF, which is returned when you Get a Collection of Rulesets.

Query Parameters to Get a Collection of Security Rules from a Ruleset

Parameter	Description	Type	Required
`org_id`	Organization	Integer	Yes
`pversion`	Security Policy Version	String	Yes
`rule_set_id`	Rule set ID	String	Yes
`external_data_reference`	A unique identifier within the external data source	String	No
`external_data_set`	The data source from which a resource originates	String	No

Query Parameters to 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). This is a path parameter.	String	Yes
`rule_set_id`	Rule set ID This is a path parameter.	Integer	Yes
`sec_rule_id`	Rule ID This is a path parameter.	Integer	Yes

Create Rules

This API allows you to create one or more rules inside a specific ruleset.

URI to Create a Rule

POST [sec_policy_rule_sets_sec_rules

Properties

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
`destinations`	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
`providers`	Reference to `sec_policy_rule_sets_sec_rules_providers_put.schema.json`
`destinations`	Reference to `sec_policy_rule_sets_sec_rules_destinations_put.schema.json`
`consuming_security_principals`	Reference to `common/consuming_security_principals_put.schema.json`		No
`unscoped_destinations`	Determines if the rule type is intra-scope or extra scope: When a rule has `unscoped_destinations:false`, this defines an intra-scope rule, which means both its providers and destinations are bound by the ruleset scope. When a rule has `unscoped_destinations:true`, this defines an extra-scope rule, which means its providers are bound by the ruleset scope, but the destination is not bound by the ruleset scope.	Boolean	No
`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]

Delete a Rule

This API deletes an individual rule inside a ruleset.

URI to Delete a Rule

DELETE [api_version][sec_rule_href]

Rule Search

This Public Experimental method searches for rules across all rulesets. This method is especially useful when your organization has large numbers of rules organized in rulesets. For example, your organization has 192,000 rules organized across 650 rulesets and you needed to know how many rules 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.

URI to Search for Rules

POST sec_policy_rule_search

Attributes for Rule Search

You can search for Workloads and IP lists by href. The ingress_services field accepts either an HREF or an object containing port/protocol/process name/service name, but not service_ports or windows_services sub-resource.

To search by providers and destinations, you can using the following attributes:

Actor Name	Actor Value Type	Required Keys	Providers	destinations
`actors`	String	N/A	True	True
`labels`	JSON Object	HREF	True	True
`label_group`	JSON Object	HREF	True	True
`workload`	JSON Object	HREF	True	True
`virtual_service`	JSON Object	HREF	True	True
`virtual_server`	JSON Object	HREF	True	False
`ip_list`	JSON Object	HREF	True	True

Properties

Property	Description	Type
`href`	URI of object	String
`enabled`	Whether the rule is enabled or disabled. Returns all the rules that are enabled.	Boolean
`description`	Description of the rule; can search based on a partial text match. Returns all the rules with a string in their description field (case insensitive partial match). "minLength": 1, "maxLength": 65535	String
`ingress_services`	Whether the rule allows connections to services specified in `ingress_services`. Reference to `sec_policy_rule_search_service.schema.json`
`sec_connect`	Whether a secure connection is established in the rule.	Boolean
`machine_auth`	Whether machine authentication is enabled in the rule.	Boolean
`stateless`	Whether statelessness is enabled in the rule.	Boolean
`providers`	Search for rule actors present in providers. Reference to `sec_policy_rule_search_providers.schema.json`
`destinations`	Search for rule actors present in destinations. Reference to `sec_policy_rule_search_destinations.schema.json`
`consuming_security_principals`	Reference to `common/consuming_security_principals_put.schema.json`
`unscoped_destinations`	Whether the rule type is intra-scope or extra-scope: `false`: An intra-scope rule `true`: An extra-scope rule	Boolean
`update_type`	Type of update for the rule. Returns rules with a specific update flag. The string for `update_type` can include: `create` `update` `delete`	String

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

Examples

Get a Rule

You can use this CURL command to see the active rule sets and their properties.

$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

Response

{
	"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.

REST APIs for 22.5

Rules

Providers and destinations

Rules API Methods

Active vs Draft

Rule Types

Note

Rule Type JSON Specification

Intra-Scope Rule Example

Stateless Rules

Note

Get Rules

Create Rules

Update Rules

Delete a Rule

Rule Search

Note

Attributes for Rule Search

Curl Command Examples for Rule Search

Examples

Search results