Rulesets

This Public Stable API gets, creates, updates, and deletes 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.	`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 the Illumio Core policy model, and consist of the following elements:

Scopes: Sets of labels (application, environment, and location) that define the boundaries of the rules in a ruleset. If the workloads specified in the rules share the same labels in a ruleset scope, then those workloads and their communications are governed by the rules of the ruleset.
A scope can contain zero or more application, environment, and location labels. A scope can also contain one or more label groups.
If the scope is an empty array ([]), then the scope includes all applications, environments, and locations.
If one of the label types is not specified, then all instances of that type are permitted. For example, if application labels are omitted but environment and location labels are present, then all applications are within the scope.
A label type cannot be used in a rule unless the scope for the label type is “All.” For example, to use a location label, the scope would have to be an empty array ([]), or if there is an application label and an environment label in the scope, the location label cannot be defined in the scope.
A ruleset is not limited to a single scope. A rule can contain multiple scopes depending on the needs of the security policy.
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 consisting one or more providers (provides a service over a port and protocol), one or more consumers (consumes the service offered by the provider), and one or more services. A provider or consumer can be an individual workload, a role label that represents multiple workloads, IP lists, and so on.

Example Ruleset Scope

Each label in a scope is identified by its HREF. For example, 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. This method gets those rulesets that are in the “draft” policy state, which means the current state of rulesets that have not been provisioned.

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

Note

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

URI to Get a Collection of Rulesets

pversion: Contains provisionable objects, which exist 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]

Query Parameters

You can use the following query parameters to restrict the results of the query to get a collection of rulesets.

Parameter	Description	Type	Required
`org_id`	Organization	Integer	Yes
`pversion`	Security Policy Version	String	Yes
`rule_set_id`		Integer	Yes
`name`	Name of the rulesets to filter, which must be unique. This parameter supports partial matches.	String	No
`description`	Description of Rule Set(s) to return. Supports partial matches	String	No
`external_data_set`	The data source from which the resource originates. For example, if ruleset information is stored in an external database.	String, Null	No
`external_data_reference`	A unique identifier within the external data source. For example, if ruleset information is stored in an external database.	String, Null	No
`enabled`	Enabled flag	Boolean	No
`update_type`	Type of update	String	No
`scopes`	Rule set scopes `label`: label URI `label_group`: label group URI	Array String	No
`rules`	Array of rules in this rule set Required properties: `enabled`: Enabled flag `description` `external_data_set` `external_data_reference` `ingress_service`	Object	No

Properties

Property	Description	Type	Required
`enabled`	Enabled flag	Boolean	Yes
`name`	Name of the rulesets to filter. This parameter supports partial matches.	String	Yes
`scopes`	Reference to `common/rule_set_scopes_get.schema.json`		Yes
`rules`	Array of rules in this rule set Reference to `sec_policy_rule_sets_sec_rules_get.schema.json`		Yes
`created_at`	Timestamp when this rule set was first created	String	Yes
`updated_at`	Timestamp when this rule set was last updated	String	Yes
`deleted_at`	Timestamp when this rule set was deleted	String, Null	Yes
`created_by`	User who originally created this rule set	Object	No
`updated_by`	User who last updated this rule set	Object	No
`deleted_by`	User who deleted this rule set	Object, Null	No
`update_type`	Type of update Reference to `common/sec_policy_update_type.schema.json`		No
`external_data_set`	The data source from which the resource originates. For example, if ruleset information is stored in an external database.	String	No
`external_data_reference`	A unique identifier within the external data source. For example, if ruleset information is stored in an external database.	String	No
`ip_tables_rules`	Array of iptables rules in this rule set. Reference to `common/ip_tables_rules_get.schema.jso`n		No

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 the Illumio Core REST API (rulesets with more than 500 rules are not fully displayed in the PCE web console).

URI to Create a Ruleset

POST [api_version][ruleset_href]

Properties for POST

Property	Description	Type	Required
`name`	Name of the new ruleset, which must be unique.	String	Yes
`scopes`	Reference to `common/rule_set_scopes_put.schema.json`		Yes
`rules`	Reference to `sec_policy_rule_sets_sec_rules_post.schema. json`		No
`ip_tables_ rules`	Array of custom iptables rules in this rule set. Reference to `common/ip_tables_rules_post.schema.json`		No
`external_data_set`	External data set identifier	String, Null	No
`external_data_reference`	External data reference identifier.	String, Null	No
`enabled`	Enabled flag	Boolean	Yes
`scopes`	Reference to `common/rule_set_scopes_put.schema.json`		Yes
`rules`	Array of rules in this rule set Reference to `sec_policy_rule_sets_sec_rules_post.schema.json`		Yes

Update a Ruleset

To update an individual ruleset, you need the HREF of the ruleset you want to update, which can be obtained when you get 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.

Properties for PUT

Property	Description	Type	Required
`name`	Name of the ruleset to update, must be unique	String	No
`external_data_set`	External data set identifier	String, Null	No
`external_data_reference`	External data reference identifier.	String, Null	No
`enabled`	Enabled flag	Boolean	Yes
`update_type`	Type of update Reference to `common/sec_policy_update_type.schema.json`		No
`scopes`	Reference to `common/rule_set_scopes_put.schema.json`		No
`rules`	Array of rules in this rule set Required properties: "href" "enabled", "providers", "consumers", "ingress_services", "resolve_labels_as"	Object	No
`consumers`	Reference to `sec_policy_rule_sets_sec_rules_consumers_put.schema.json`
`consuming_security_principals`	Reference to `common/ consuming_security_principals_put.schema.json`
`network_type`	Reference to `common/ rule_network_type.schema.json`
`use_workload_subnets`	Reference to `sec_ rule_use_workload_subnets.schema.json`

Delete a Ruleset

To delete an individual ruleset, you need the HREF of the ruleset you want to delete, which can be obtained when you get a collection of rulesets.

URI to Delete an Individual Ruleset

DELETE [api_version][ruleset_href]

Examples

Get a Ruleset

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

Response

[
	{
		"href": "/orgs/1/sec_policy/draft/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,
		"update_type": null,
		"name": "Default",
		"description": null,
		"enabled": true,
		"scopes": [
		[]
		],
		"rules": [
		{
			"href": "/orgs/1/sec_policy/draft/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,
			"update_type": null,
			"description": "Allow outbound connections",
			"enabled": true,
			"providers": [
				{
				"ip_list": {
				"href": "/orgs/1/sec_policy/draft/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/draft/services/1"
			}
			],
			"egress_services": [],
			"resolve_labels_as": {
			"providers": [
			"workloads"
			],
			"consumers": [
			"workloads"
			]
			}
			}
			],
		"ip_tables_rules": [],
			"caps": [
			"write",
			"provision"
			]
			},
		{
			"href": "/orgs/1/sec_policy/draft/rule_sets/3",
			"created_at": "2023-04-05T23:50:05.591Z",
			"updated_at": "2023-04-06T19:03:49.947Z",
			"deleted_at": null,
			"created_by": {
				"href": "/users/1"
			},
			"updated_by": {
				"href": "/users/1"
			},
			"deleted_by": null,
			"update_type": null,
			"name": "ruleset1"
"		"description": "",
		"enabled": true,
		"scopes": [
		[]
		],
	"rules": [
		{
		"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": null,
		"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"																				
		]
		}
	}
		],
		"ip_tables_rules": [],
		"caps": [
		"write",
		"provision"
		]
	}
]

Create a Ruleset

$curl -u api_1c2618a67847c94b8:98c76f7a4563f29cd78b3392684cd5ec09534bafe5197fe8e901d95561bdd8f5-X POST -H 'Content-Type: application/json' -d ' {"name":"ruleset3","description":"","scopes":[[{"exclusion":false,"label":{"href":"/orgs/1/labels/14"}}]]}'https://2x2testvc168.ilabs.io:8443/api/v2/orgs/1/sec_policy/draft/rule_sets | jq

Response

{
	"href": "/orgs/1/sec_policy/draft/rule_sets/16",
	"created_at": "2023-04-06T18:46:34.718Z",
	"updated_at": "2023-04-06T18:46:34.727Z",
	"deleted_at": null, "created_by": {
		"href": "/users/1"
		},
	"updated_by": {
		"href": "/users/1"
		},
	"deleted_by": null,
	"update_type": "create",
	"name": "ruleset3",
	"description": "",
	"enabled": true, "scopes": [
		[
		{
		"label": {
			"href": "/orgs/1/labels/14"
		},
		"exclusion": false
		}
		]
	],
	"rules": [],
		"ip_tables_rules": [], "caps": [
		"write",
		"provision"
	]
}

Update a Ruleset

$curl -w "%{http_code}" -u api_1c2618a67847c94b8:98c76f7a4563f29cd78b3392684cd5ec09534bafe5197fe8e901d95561bdd8f5 -X PUT -H 'Content-Type: application/json' -d '{"scopes":[[{"label": {"href":"/orgs/1/labels/14"}},{"label":{"href":"/orgs/1/labels/15"}}]]}' https://2x2testvc168.ilabs.io:8443/api/v2/orgs/1/sec_policy/draft/rule_sets/14 | jq

Response

The ruleset was successfully updated:

REST APIs for 23.5

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

Examples

Search results