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 source 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 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

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`

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`
`label_dimension`	Providers: This property was added for "rule actors that are all workloads (ams)" with a specific label dimension. destinations: This property was added for "rule actors that are all workloads (ams)" with a specific label dimension. The difference is that for "destinations" APIs, the property `label_dimension` has an additional specified data type or enum app.

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