Skip to main content

REST APIs 25.3

Rule-Based Label Mapping

New APIs for managing the new feature, Rule-based label mapping, are the following:

Label Mapping API Methods

Functionality

HTTP

URI

Returns the collection of label mapping rules.

GET

/orgs/:xorg_id/label_mapping_rules

Creates a new label-mapping rule.

POST

/orgs/:xorg_id/label_mapping_rules

Deletes multiple label mapping rules

PUT

/orgs/{org_id}/label_mapping_rules/delete

Gets the instance of a single label-mapping rule.

GET

/orgs/:xorg_id/label_mapping_rules/:label_mapping_rule_id

Updates the instance of a single rule.

PUT

/orgs/:xorg_id/label_mapping_rules/:label_mapping_rule_id

Deletes the specified label-mapping rule.

DELETE

/orgs/:xorg_id/label_mapping_rules/:label_mapping_rule_id

Reorders label-mapping rules.

PUT

/orgs/{org_id}/label_mapping_rules/{label_mapping_rule_id}/reorder

This asynchronous API runs a set of label-mapping rules on a set of workloads.

POST

/orgs/:xorg_id/label_mapping_rules/run

Gets the status of the async job to run the rules.

GET

/orgs/:xorg_id/label_mapping_rules/run/:job_uuid

Downloads the results of the run rules job.

GET

/orgs/:xorg_id/label_mapping_rules/run/:job_uuid/download

Assign labels from the results of the label-mapping rules run the job.

PUT

/:xorg_id/label_mapping_rules/run/:job_uuid/assign_labels

Bulk label update

PUT

[api_version][label_href]label_mapping_rules_update

Bulk label update

If an organization has 500 rules defined, the UI must make up to 500 individual calls in an enable/disable rules operation.

This issue is resolved using the "bulk update" endpoint, which was chosen instead of a "bulk enable/disable" API because it provides additional flexibility to support future use cases.

label_mapping_rule_label_assignments.schema.json

The property label_assignment was deleted and replaced with a reference to label_mapping_rule_label_assignments.schema.json for the following APIs:

  • label_mapping_rules_post

  • label_mapping_rules_get

  • label_mapping_rules_put

Rule-Based Label Mapping Reference

This topic covers examples and schemas for rule-based label mapping.

Label Mapping Rule Expression Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "anyOf": [
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "property",
        "operator",
        "values"
      ],
      "properties": {
        "property": {
          "description": "The workload property to compare. (hostname, ip_address etc.)",
          "type": "string",
          "enum": [
            "hostname",
            "ip_address",
            "os",
            "process",
            "port"
          ]
        },
        "operator": {
          "description": "operator for the condition (starts_with, contains, equals, ends_with, is_in, regex)",
          "type": "string",
          "enum": [
            "starts_with",
            "ends_with",
            "contains",
            "equals",
            "is_in",
            "regex"
          ]
        },
        "values": {
          "description": "Value to use in comparison",
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "properties": {
                  "port": {
                    "description": "Port Number (integer 0-65535). Also the starting port when specifying a range.",
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 65535
                  },
                  "to_port": {
                    "description": "High end of port range inclusive if specifying a range. If not specifying a range then don't include this.",
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 65535
                  },
                  "proto": {
                    "description": "protocol number",
                    "type": "integer"
                  }
                }
              }
            ]
          }
        }
      }
    },
    {
      "type": "object",
      "required": [
        "logical_operator",
        "child_expressions"
      ],
      "properties": {
        "logical_operator": {
          "description": "logical operator for the child expressions",
          "type": "string",
          "enum": [
            "and",
            "or",
            "not"
          ]
        },
        "child_expressions": {
          "type": "array",
          "items": {
            "$ref": "#"
          }
        }
      }
    }
  ]
}

In release 25.3, this schema has a new operator: regex. It was added to the existing list of supported operators in APIs (request and response) .

For Hostname, OS, and Process, these are the 'regex' operator examples:

Hostname regex '^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.illumio\\.com$'  
#will match any hostname under the illumio.com domain

Hostname regex '/^(?=.*?(pc|fileserver|notebook))(?=.*?\d)[a-z\d-]+$/'          
#will match something like fileserver-win2019 

OS regex '*win*'                                                                
#will match with anything that has win in it

OS regex '/\b(lin|centos|ubuntu|redhat)\b/i'                                    
#will match Linux, linux, Centos-3.7.0 , ubuntu-x86_64-xenial 

Process regex '^/.*/chshell$'                                                   
#will match /user/bin/chshell. regex uses the ^ and $ anchors to match the beginning and end of the string

Process regex ''

For IP Address 'regex'

IP Address regex '^(192\.168)\.([01]?[0-9]?[0-9]|2([0-4][0-9]|5[0-5]))\.
([01]?[0-9]?[0-9]|2([0-4][0-9]|5[0-5]))$' 
#will match IP addresses in the range of 192.168.0.0 - 192.168.255.255: 

IP Address regex '^(\\d{1,3}\\.){3}\\d{1,3}$' 
will match any IP address in the format xxx.xxx.xxx.xxx

To learn more about using regex, see Add Labeling Rule in Security Policy Guide.

Examples
Example response for GET /api/v2/orgs/:xorg_id/label_mapping_rules
[
    {
	"href": "/orgs/1/label_mapping_rules/48ed8903-878e-4010-859a-63d19be797c3",
	"enabled": true,
	"position": 40,
	"created_at": "2024-04-24T06:54:00.530Z",
	"updated_at": "2024-04-24T06:54:00.535Z",
	"expression": {
	    "property": "hostname",
	    "values": [
		"this"
	    ],
	    "operator": "starts_with"
	},
	"created_by": {
		"href": "/users/2"
	},
	"updated_by": {
		"href": "/users/2"
	},
	"label_assignments": [
	    {
		"label": {
		    "href": "/orgs/1/labels/24"
		}
	    },
	   {
		"label": {
		    "href": "/orgs/1/labels/11"
		}
	    },
	    {
		"label": {
		    "href": "/orgs/1/labels/20"
		}
	    }
	]
    },
    {
	"href": "/orgs/1/label_mapping_rules/d1479032-f7cb-479f-87bd-1bc7bd816a74",
	"enabled": true,
	"position": 41,
	"created_at": "2024-04-26T18:18:10.238Z",
	"updated_at": "2024-04-26T18:18:10.256Z",
	"expression": {
	    "property": "hostname",
	    "values": [
		"perf-workload-1"
	    ],
		"operator": "equals"
	 },
	"created_by": {
		"href": "/users/1"
	},
	"updated_by": {
		"href": "/users/1"
	},
	"label_assignments": [
		{
		    "label": {
			"href": "/orgs/1/labels/9"
		    }
		}
	    ]
    },
    {
	"href": "/orgs/1/label_mapping_rules/d4ddb653-56e9-4150-a93e-8a734c510c03",
	"enabled": true,
	"position": 43,
	"created_at": "2024-04-28T00:05:38.146Z",
	"updated_at": "2024-04-28T00:05:38.150Z",
	"expression": {
	    "property": "hostname",
	    "values": [
		"perf-workload-2"
	    ],
	    "operator": "equals"
	},
	"created_by": {
		"href": "/users/2"
	},
	"updated_by": {
		"href": "/users/2"
		},
	"label_assignments": [
		{
		"label": {
		    "href": "/orgs/1/labels/7"
		}
	    }
	]
    }
]
Example Request for POST /api/v2/orgs/:xorg_id/label_mapping_rules
{
    "expression": {
	"logical_operator": "and",
	"child_expressions": [
		{
		"property": "os",
		"operator": "equals",
		"values": ["linux"]
	},
	{
		"property": "process",
		"operator": "contains",
		"values": ["mysql"]
	}
    ]
	},
	"label_assignments": [
	    {
		"label": {
		    "key": 'os',
		    "value": 'Linux'
		}
	},
	{
		"label": {
		    "key": 'role',
		    "value": 'Database'
		}
	    }
	]
    }
}
Example Response for POST /api/v2/orgs/:xorg_id/label_mapping_rules
{
	"href": "/orgs/1/label_mapping_rules/4512e359-bda3-49d1-8f9e-b9a03357e4ee",
	"enabled": true,
	"position": 2,
	"created_at": "2024-04-18T23:45:49.237Z",
	"updated_at": "2024-04-18T23:45:49.290Z",
	"expression": {
	    "property": "os",
	    "operator": "contains",
	    "values": [
		"windows"
	    ]
	},
	"created_by": {
	    "href": "/users/1"
	},
	"updated_by": {
	    "href": "/users/1"
	},
	"label_assignments": [
	    {
		"label": {
		    "key": "os",
		    "value": "Windows"
		}
	    }
	]
}
Example Request to Enable Multiple Rules
[  
    {    
        "href": "/orgs/1/label_mapping_rules/84e19944-2ae1-4985-9ace-ca2e109da80e",    
        "enabled": true  
    },  
    {    
        "href": "/orgs/1/label_mapping_rules/15c3711c-3821-4719-8c10-a3e89966b66e",    
        "enabled": true  
    }
]
Example Request to Disable Multiple Rules
[  
    {    
        "href": "/orgs/1/label_mapping_rules/84e19944-2ae1-4985-9ace-ca2e109da80e",    
        "enabled": false  
    },  
    {    
        "href": "/orgs/1/label_mapping_rules/15c3711c-3821-4719-8c10-a3e89966b66e",    
        "enabled": false  
    }
]    
Example Request to Update Multiple Rules
[  
    {    
        "href": "/orgs/1/label_mapping_rules/84e19944-2ae1-4985-9ace-ca2e109da80e",    
        "expression": {      
            "property": "hostname",      
            "operator": "equals",      
            "values": [        
                "foo"      
            ]    
        },    
         "label_assignments": [      
            {        
                "label": {          
                    "href": "/orgs/1/labels/46"        
                }      
            }    
        ]  
    },  
    {    
        "href": "/orgs/1/label_mapping_rules/15c3711c-3821-4719-8c10-a3e89966b66e",    
        "expression": {      
            "logical_operator": "and",      
            "child_expressions": [        
            {          
                "values": [            
                "/usr/bin/node"          
                ],          
                "operator": "equals",          
                "property": "process"        
            },        
            {          
                "values": [            
                    {              
                        "port": 3000,              
                        "proto": 6            
                    }          
                ],          
                "operator": "equals",          
                "property": "port"        
                }      
            ]    
        },    
        "label_assignments": [      
            {        
                "label": {          
                    "href": "/orgs/1/labels/44"        
                }      
            }    
        ]  
    }
]