Skip to main content

REST APIs for 24.2.20 and 24.2.10

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

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
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, all instances of that type are permitted. For example, all applications are within the scope if application labels are omitted but environment and location labels are present.

    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 security policy's needs.

    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 of one or more providers (provides a service over a port and protocol), one or more consumers (consumes the service offered by the Source), and one or more services. A Source or Destination can be an individual workload, a role label representing multiple workloads, IP lists, etc.

Example Ruleset Scope

Each label in a scope is identified by its HREF. 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 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]
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]
Update a Ruleset

You need the HREF of the ruleset you want to update to update an individual ruleset, 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.

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]
Rulesets Reference

This topic covers parameters, properties, and examples for rulesets.

Parameters for rulesets

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 for rulesets

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

No

Properties to create a ruleset

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

Properties for updating a ruleset

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

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:

204
See also: