Skip to main content

REST APIs for 23.5

Rules

This Public Stable API creates, updates, and deletes individual rules in rulesets. It also gets a collection of rules from a ruleset.

Providers and Consumers

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.

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

Rules API Methods

Functionality

HTTP

URI

Get rules

GET

sec_policy_rule_sets_sec_rules

Get rules for provides

GET

sec_policy_rule_sets_sec_rules_providers

Get rules for consumers.

GET

sec_policy_rule_sets_sec_rules_consumers

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

Active vs Draft

Rule Types

There are three types of rules:

  • Intra-scope rules: Allow communication between providers and consumers within a specific scope.

  • Extra-scope rules: Rules that go beyond the scope of the ruleset to which they belong. In this rule type, the workloads, labels or IP list in the consumers part of the rule are not constricted by the scope of the ruleset. This type of rule is used when you want specific rules that allow providers to offer a service to other workloads or groups that are not within the boundaries of the ruleset scope.

  • Custom iptables rules: Used to configure custom iptables rules on Linux workloads; for example, to preserve existing native Linux host iptables rules by including them in a ruleset.

Note

The PCE web console can only display up to 500 rules per ruleset. To write more than 500 rules for a particular scope, consider splitting the rules across multiple rulesets, otherwise users won't be able to view them all in the PCE web console.

Rule Type JSON Specification

To define a rule as either intra-scope or extra-scope, specify if the rule is “scoped” or “not scoped” by defining the 'unscoped_consumers' property:

  • When a rule has unscoped_consumers: false, this defines an intra-scope rule, which means both its providers and consumers are bound by the ruleset scope.

  • When a rule has unscoped_consumers: true, this defines an extra-scope rule, which means its providers are bound by the ruleset scope, but the ruleset scope does not bind the consumers.

Intra-Scope Rule Example

Note

The common schema consuming_security_principals has been replaced by two other APIs: consuming_security_principals_get and consuming_security_principals_put

This rule illustrates an intra-scope rule because it has its unscoped_consumers property set to false:

{ 
  "rules": [
    {
      "enabled": true,
      "providers": [ {"label": {"href": "/orgs/1/labels/2"} } ],
      "consumers": [ {"label": {"href": "/orgs/1/labels/1"} } ],
      "consuming_security_principals": [],
      "ingress_services": ["href": "/orgs/1/sec_policy/draft/services/20"],       
      "resolve_labels_as": { 
        "providers": ["workloads"],
        "consumers": ["workloads"]
      },
      "sec_connect": false,
      "unscoped_consumers": false
    }
  ]
}

Stateless Rules

A rule can be configured to have stateless packet filtering ("stateless": true). This means that the VEN instructs the host firewall to not maintain persistent connections for all sessions. This type of rule is typically used for data center “core services” such as DNS and NTP.

A stateless rule can have these consumer types:

  • Any IP list plus all workloads

  • A label (one of a specific type)

  • An individual item (such as an individual workload)

An attempt to add more consumers, or one not supported, will return an error.

A PCE can only have a maximum of 100 stateless rules. If an implementation requires more than 100 stateless rules, contact your Illumio Professional Services Representative for more information.

Note

This property has an API exposure level of

Public Experimental, which means it is not intended

for production use and might change in future releases.

For more information, see API Classification and Version.

Get Rules

This API gets a collection of rules or gets an individual rule from a ruleset.

Before you can get rules from a ruleset with this API, you must obtain the ruleset HREF, which is returned when you Get a Collection of Rulesets.

Query Parameters to 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

Query Parameters to 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

Create Rules

This API allows you to create one or more rules inside a specific ruleset.

URI to Create a Rule

POST [api_version][rule_set_href]/sec_rules

Properties

Property

Description

Type

Required

enabled

Indicates if the rule is enabled or disabled.

Boolean

Yes

providers

Entities that can be used as a provider in a rule.

Reference to sec_policy_rule_sets_sec_rules_providers_put.schema.json

Yes

consumers

Entities that can be used as a consumer 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 data center “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, 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 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 Create 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

Rule Search

This Public Experimental method searches for rules across all rulesets. This method is especially useful when your organization has large numbers of rules organized in rulesets. For example, your organization has 192,000 rules organized across 650 rulesets and you needed to know how many rules 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.

URI to Search for Rules

POST sec_policy_rule_search
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 using the following attributes:

Actor Name

Actor Value Type

Required Keys

Providers

Consumers

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

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
Examples

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

Response

The rule was successfully uodated:

204
See also: