Skip to main content

REST API Developer Guide 22.5

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

Create a ruleset

POST

[api_version][org_href]/sec_policy/rule_sets

Update a specified ruleset

PUT

[api_version][org_href][ruleset_href]

Delete a ruleset

DELETE

[api_version][org_href][ruleset_href]

Active vs. Draft
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

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

GET [api_version][ruleset_href]

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

Name of the rulesets to filter. This parameter supports partial matches.

String

Yes

description

Description of Rule Set(s) to return. Supports partial matches

String

No

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

labels

List of lists of label URIs, encoded as a JSON string

String

No

max_results

Maximum number of Rule Sets to return.

String

No

name

User who originally created this rule set Name of Rule Set(s) to return. Supports partial matches

Object

No

Properties

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

pversion

Security Policy version

String

Yes

name

Name of the rulesets to filter. This parameter supports partial matches.

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

external_data_set

The data source from which the resource originates. For example, if ruleset 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

Noi

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

pversion

Security Policy version

String

Yes

name

Name of the rulesets to filter. This parameter supports partial matches.

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

external_data_set

The data source from which the resource originates. For example, if ruleset 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

Noi

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

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/v1/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

scopes

Reference to common/rule_set_scopes_put.schema.json

No

rules

Reference to sec_policy_rule_sets_sec_rulesproviders_put.schema

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

No

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 Rule Set

$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 Rule Set

$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 Rule Set

$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 rule set was successfully updated.

204
See also: