Rules

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

Rules API Methods

Functionality	HTTP	URI
Get a collection of rules from a ruleset	`GET`	`[api_version][rule_set_href]/sec_rules`
Get an individual rule from a ruleset	`GET`	`[api_version][sec_rule_href]`
Create rules	`POST`	`[api_version][rule_set_href]/sec_rules`
Update an individual rule	`PUT`	`[api_version][sec_rule_href]`
Delete an individual rule	`DELETE`	`[api_version][sec_rule_href]`

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.

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 consumers are not bound by the ruleset scope.

Intra-Scope Rule Example

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
    }
  ]
}

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.

A simple rule that allows two workloads to communicate with each other might look like this:

Providers	Service	Consumers
Database	HTTPS	Web

This example shows the rule providers, consumers, and services:

{   
  "enabled": true,
  "providers": [ {"label": {"href": "/orgs/1/labels/10"} } ],
  "consumers": [ {"label": {"href": "/orgs/1/labels/67"} } ],
  "consuming_security_principals": [], 
  "ingress_services": ["href": "/orgs/1/sec_policy/draft/services/32"],     
  "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 datacenter “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 need to obtain the ruleset HREF, which is returned when you Get a Collection of Rulesets.

Example Ruleset HREF

/orgs/2/sec_policy/draft/rule_sets

URI to Get a Collection of Rules from a Ruleset

GET [api_version][rule_set_href]/sec_rules

URI to Get an Individual Security Rule from a Ruleset

GET [api_version][sec_rule_href]

Query Parameters to Get a Collection of Security Rules from a Ruleset

Parameter	Description	Type
`pversion`	Security policy version -- `draft`(not provisioned) or `active` (provisioned) Note This is a path parameter.	String
`description`	Description of rulesets to return. Supports partial matches.	String
`external_data_reference`	A unique identifier within the external data source. For example, if this rule information is stored in an external database.	String
`external_data_set`	The data source from which the resource originates. For example, if this rule information is stored in an external database.	String
`labels`	List of lists of label URIs encoded as a JSON string.	String
`max_results`	Maximum number of rule sets to return.	Integer
`name`	Name of rulesets to return.	String

Query Parameters to Get an Individual Security Rule from a Ruleset

Parameter	Description	Type
`:pversion`	Security policy version -- `draft` (not provisioned) or `active` (provisioned). This is a path parameter.	String
`rule_set_id`	The ruleset ID. This is a path parameter.	Integer
`representation`	Representation details for this resource on the response object.	String

Parameter

Description

Type

:pversion

Security policy version -- draft (not provisioned) or active (provisioned).

This is a path parameter.

String

rule_set_id

The ruleset ID.

This is a path parameter.

Integer

representation

Representation details for this resource on the response object.

String

Curl Command to Get Rules from Ruleset

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/draft/rule_sets/97/sec_rules -H "Accept: application/json" -u $KEY:$TOKEN

Response Body

In the response, each returned rule is identified by its HREF, such as: "/orgs/1/sec_policy/draft/rule_sets/152/sec_rules/124".

For example:

{
  "href": "/orgs/1/sec_policy/draft/rule_sets/152/sec_rules/124",
  "created_at": "2016-07-18T23:41:06.092Z",
  "updated_at": "2016-07-18T23:41:06.092Z",
  "deleted_at": null,
  "created_by": {"href": "/users/8"},
  "updated_by": {"href": "/users/8"},
  "deleted_by": null,
  "description": null,
  "enabled": true,
  "providers":[ 
    {"virtual_server": {"href": "/orgs/1/sec_policy/draft/
	virtual_servers/f97fc590-2761-422f-a8b2-8227db37e2c1"} } 
  ],
  "consumers": [
    {"label": {"href": "/orgs/1/labels/1"}}
  ],
  "consuming_security_principals": [],
  "ingress_services": [],       
  "resolve_labels_as": {
      "providers": ["virtual_services"],
      "consumers": ["workloads"]
  },
  "sec_connect": false,
  "unscoped_consumers": false
  },
{
...............................................
}

Curl Command to Get a Rule

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/1/sec_policy/draft/rule_sets/152/sec_rules/128 -H "Accept: application/json" -u $KEY:$TOKEN

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

Request 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, each of which is defined in JSON by its HREF: `label` `label group` `workload` `virtual_server` `ip_list`	String	Yes, at least one
`consumers`	Entities that can be used as a consumer in a rule, each of which is defined in JSON by its HREF: `label` `label group` `workload` `ip_list`	String	Yes, at least one
`ingress_services`	The rule allows connections to the services specified in `ingress_services`, subject to the value of `resolve_labels_as`. These parameters work together as follows: If the providers side of `resolve_labels_as` is set to `["workloads"]`, then `ingress_services` contains an array of service HREFs. For example: `"ingress_services": [\{"href": "/orgs/1/sec_policy/draft/services/20"}]` If the providers side of `resolve_labels_as` is set to `["virtual_services"]`, then `ingress_services` must contain an empty array. Connections are allowed to the services defined by the matching virtual services. For example: `"ingress_services": []` Finally, if the providers side of `resolve_labels_as` is set to `["workloads", "virtual_services"]`, then `ingress_services` contains an array of service HREFs. When matching a workload, the specified services are allowed by the rule. When matching a virtual service, the services specified in `ingress_services` are ignored, and the services defined by the virtual service is allowed by the rule.	[String]	Yes
`resolve_labels_as`	This is a hash with two keys: providers and consumers. The value of each key is an array of strings. Valid strings are "workloads" and "virtual_services", and the array can contain one or both of these. For each side, if the value is `["workloads"]`, the rule applies only to workloads that match the rule. If the value is `["virtual_services"]`, the rule applies only to matching virtual services. If the value is `["workloads", "virtual_services"]` then the rule applies to matching objects of either type. On the providers side, see `ingress_services` for specific requirements related to the use of either "workloads" or "virtual_services".	[String]	Yes
`sec_connect`	If set to `true`, then the rule will use SecureConnect IPsec encryption for all traffic allowed by the rule.	Boolean	No
`stateless`	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. 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`	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. 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`	This property is for internal purposes only to enable the PCE to provide Adaptive User Segmentation (AUS) rules. You can ignore and not set this property.	N/A	N/A
`unscoped_consumers`	Determines if the rule type is intra-scope or extra scope: 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 consumer is not bound by the ruleset scope.	Boolean	No

Example Payload

This example shows how to construct both intra-scope rules (listed in the JSON as "unscoped_consumers": false), and extra-scope rules (listed as "unscoped_consumers": true), as well as different types of rule providers and consumers. For information on custom iptables rules, see Custom iptables Rules.

{	
"href": "/orgs/1/sec_policy/draft/rule_sets/152/sec_rules/124",	

  /* These first two rules are intra-scope rules, *
  /* which consist of basic label to label 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": true,
  "unscoped_consumers": false
},  /* This rule illustrates using multiple labels for the providers field, 
       and an IP List for the consumer field. */		
{
  "enabled": true,
  "providers": [
    {"label": {"href": "/orgs/1/labels/3"}},
    {"label": {"href": "/orgs/1/labels/1"}}
  ],
  "consumers": [
    {"ip_list": {"href": "/orgs/1/sec_policy/draft/ip_lists/1"}}
  ],
  "consuming_security_principals": [],	
  "ingress_services": ["href": "/orgs/1/sec_policy/draft/services/28"],       
  "resolve_labels_as": {
    "providers": ["workloads"],
    "consumers": ["workloads"]
  },	
  "sec_connect": false,		
  "unscoped_consumers": false
},	   
 /* This rule shows and example of using "all workloads" in a rule.Since this is an intra-scope rule ("unscoped_consumers": false),  "all workloads" fall under the current ruleset scopes.*/
{
  "enabled": true,		
  "providers": [
    {"ip_list": {"href": "/orgs/1/sec_policy/draft/ip_lists/1"}}		
  ],	
  "consumers": [
    {"actors": "ams"}	
  ],	
  "consuming_security_principals": [],
  "ingress_services": [{"href": "/orgs/1/sec_policy/draft/services/32"}],       
  "resolve_labels_as": {
    "providers": ["workloads"],
    "consumers": ["workloads"]
  }, 
  "sec_connect": false,
  "unscoped_consumers": false
},

   /* The next two rules are extra-scope rules. Notice how in both rules, "unscoped_consumers": true.
    Note too how both intra- and extra-scope rules are placed in the "rules" array (the only distinction 
    is the "unscoped_consumers" field) */
   /* This is an example of an extra scope rule between labels. Because
    the consumers are unscoped, we can fully specify the label set we want, which in this case is one
    each of the Role, Application, Environment, and Location labels */

{	
  "enabled": true,
  "providers": [
    {"label": { "href": "/orgs/1/labels/2" }}
  ],	
  "consumers": [
    {"label": { "href": "/orgs/1/labels/1" }},
    {"label": { "href": "/orgs/1/labels/24" }},
    {"label": { "href": "/orgs/1/labels/27" }},
  ],
  "consuming_security_principals": [],
  "ingress_services": [{"href": "/orgs/1/sec_policy/draft/services/30"}],       
  "resolve_labels_as": {
    "providers": ["workloads"],
    "consumers": ["workloads"]
  },
  "sec_connect": false,
  "unscoped_consumers": true
}
			
   /* This example illustrates an extra-scope rule with an IP list and "all workloads". In this case, 
   because we have unscoped consumers, the "all workloads" in consumers actually means ALL workloads, 
   not just the ones bound by the ruleset scope as with the intra-scope rules.*/

....................................
}

Curl Command to Create Rule

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/3/sec_policy/draft/rule_sets/152/sec_rules -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"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},{"enabled":true,"providers":[{"label":{"href":"/orgs/1/labels/3"}},{"label":{"href":"/orgs/1/labels/1"}}],"consumers":[{"ip_list":{"href":"/orgs/1/sec_policy/draft/ip_lists/1"}}],"consuming_security_principals":[],"ingress_services":[{"href":"/orgs/1/sec_policy/draft/services/28"}],"resolve_labels_as":{"providers":["workloads"],"consumers":["workloads"]},"sec_connect":false,"unscoped_consumers":false},{"enabled":true,"providers":[{"ip_list":{"href":"/orgs/1/sec_policy/draft/ip_lists/1"}}],"consumers":[{"actors":"ams"}],"consuming_security_principals":[],"ingress_services":[{"href":"/orgs/1/sec_policy/draft/services/32"}],"resolve_labels_as":{"providers":["workloads"],"consumers":["workloads"]},"sec_connect":false,"unscoped_consumers":false},{"enabled":true,"providers":[{"label":{"href":"/orgs/1/labels/2"}}],"consumers":[{"label":{"href":"/orgs/1/labels/1"}},{"label":{"href":"/orgs/1/labels/24"}},{"label":{"href":"/orgs/1/labels/27"}},{"label":{"href":"/orgs/1/labels/21"}}],"consuming_security_principals":[],"ingress_services":[{"href":"/orgs/1/sec_policy/draft/services/30"}],"resolve_labels_as":{"providers":["workloads"],"consumers":["workloads"]},"sec_connect":false,"unscoped_consumers":true},{"enabled":true,"providers":[{"ip_list":{"href":"/orgs/1/sec_policy/draft/ip_lists/1"}}],"consumers":[{"actors":"ams"}],"consuming_security_principals":[],"ingress_services":[{"href":"/orgs/1/sec_policy/draft/services/1"}],"resolve_labels_as":{"providers":["workloads"],"consumers":["workloads"]},"sec_connect":false,"unscoped_consumers":true}]}'

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 api/[api_version]/orgs/:xorg_id/sec_policy/draft/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

Request Properties

Property	Description	Type
`enabled`	Whether the rule is enabled or disabled. Returns all the rules that are enabled.	Boolean
`description`	Description of the rule; can search based on a partial text match. Returns all the rules with a string in their description field (case insensitive partial match).	String
`ingress_services`	Whether the rule allows connections to services specified in `ingress_services`. When searching by `ingress_services`: Matches rules that contain all the services that are referenced in the query. Matches rules that contain either services that match the ports/port ranges in the query or uses those ports/port ranges directly. Windows services can be searched for implicitly by specifying a `service_name` or `process_name` field as one of the objects in the `ingress_services`. Can be one of two values: HREF JSON object containing one or more of `port`, `to_port`, `protocol`, `service_name`, and `process_name`	Object or null
`sec_connect`	Whether a secure connection is established in the rule.	Boolean
`machine_auth`	Whether machine authentication is enabled in the rule.	Boolean
`stateless`	Whether statelessness is enabled in the rule.	Boolean
`unscoped_consumers`	Whether the rule type is intra-scope or extra-scope: `false`: An intra-scope rule `true`: An extra-scope rule	Boolean
`update_type`	Type of update for the rule. Returns rules with a specific update flag. The string for `update_type` can include: `create` `update` `delete`	String
`providers`	Search for rule actors present in providers. Entities that can be used as a provider in a rule, each of which is defined in JSON by its HREF: actors: `ams` (All workloads) label label group workload Virtual service virtual server IP list	String
`consumers`	Search for rule actors present in consumers. Entities that can be used as a consumer in a rule, each of which is defined in JSON by its HREF: actors: `ams` (All workloads) label label group workload Virtual service IP list	String

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

REST API Developer Guide 22.2

Rules

Rules API Methods

Active vs Draft

Rule Types

Note

Rule Type JSON Specification

Intra-Scope Rule Example

Providers and Consumers

Stateless Rules

Note

Get Rules

Note

Create Rules

Update Rules

Delete a Rule

Rule Search

Note

Attributes for Rule Search

Curl Command Examples for Rule Search

Search results