Rules

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

It also gets a collection of rules from a ruleset.

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.

Rules API Methods

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

Table 3. 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 consumers.	`GET`	sec_policy_rule_sets_sec_rules_consumer
Update rules	`PUT`	sec_policy_rule_sets_sec_rules
Update rules for providers	`PUT`	sec_policy_rule_sets_sec_rules_providers
Update rules for consumers	`PUT`	sec_policy_rule_sets_sec_rules_consumers
Create rules	`POST`	sec_policy_rule_sets_sec_rules
Delete an individual rule.	`DELETE`	sec_rule_href

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.

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 consumers, you can use the following attributes:

Table 4. Search Attributes

Actor Name	Actor Value Type	Required Keys	Providers (Source)	Consumers (Destination)
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

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_consumers_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_consumers`	Set the scope for rule consumers 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"}}],"consumers": [{"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"
		}
		}
	],
	"consumers": [ {
	"actors": "ams"
		}
		],
	"consuming_security_principals": [],
	"sec_connect": false,
	"stateless": false,
	"machine_auth": false,
	"unscoped_consumers": false,
	"network_type": "brn",
	"use_workload_subnets": [], "ingress_services": [
		{
		"href": "/orgs/1/sec_policy/active/services/1" }
		],
	"egress_services": [],
	"resolve_labels_as": {
	"providers": [
	"workloads"
		],
	"consumers": [
	"workloads"
		]
	}
}
],

Create a Rule

curl -u api_1c2618a67847c94b8:98c76f7a4563f29cd78b3392684cd5ec09534bafe5197fe8e901d95561bdd8f5 -X POST -H 'Content-Type: application/json' -d '{"providers":[{"label": {"href":"/orgs/1/labels/14"}}],"consumers":[{"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_ consumers":false,"description":"","use_workload_subnets":[],"resolve_labels_as": {"consumers":["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
			}
			],
	"consumers": [
		{
		"label": {
			"href": "/orgs/1/labels/15"
		},
		"exclusion": false
		}
	],
	"consuming_security_principals": [],
		"sec_connect": true,
		"stateless": false,
		"machine_auth": false,
		"unscoped_consumers": 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"
		],
	"consumers": [
		"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"}}],"consumers":[{"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_ consumers":false,"description":"","use_workload_subnets":[],"resolve_labels_as":{"providers":["workloads"],"consumers":["workloads"]}}' https://2x2testvc168.ilabs.io:8443/api/v2/orgs/1/sec_policy/draft/rule_sets/3/sec_ rules/3 | jq