Provisioning (Public Experimental)

This Public Experimental API gets information about unprovisioned changes to security policy items (rulesets, IP lists, security settings, labels and label groups, services, virtual services, and user groups). You can also find provisioning dependencies, delete unprovisioned security policy items, revert the last provisioned items, and check whether a security rule exists that allows communications between two workloads.

Provisioning API Methods

Functionality	HTTP	URI
Get the collection of modified (`draft`) security policy items pending provisioning.	`GET`	`[api_version][org_href]/sec_policy/pending`
Check whether a rule exists between two workloads that allows communication.	`GET`	`[api_version][sec_policy_version_href]/allow`
Get the collection of all policy items that were modified in a specific version of a security policy.	`GET`	`[api_version][sec_policy_version_href]/modified_objects`
Delete all unprovisioned security policy item modifications (all unprovisioned `draft` changes) pending provisioning.	`DELETE`	`[api_version][org_href]/sec_policy/pending`
Revert a specified list of pending uncommitted security policy items. This method allows you to select specific items to revert.	`PUT`	`[api_version][org_href]/sec_policy/delete`
Determine if a specific set of objects can be provisioned, or if they are dependent on other objects that need to be provisioned as well.	`POST`	`[api_version]/sec_policy/draft/dependencies`

Provisionable Policy Items

The following security policy items all require provisioning before they can take effect on managed workloads (workloads with a VEN installed on them). The total sum of these policy items constitutes the security policy.

IP Lists: IP addresses, IP ranges, and CIDR blocks allowed to access managed workloads.
Label Groups: Labels can be managed in label groups.
Rulesets: Policy item that includes labels and rules to define permitted communication between workloads and between groups.
Pairing Profiles: A Pairing Profile applies certain properties to workloads as they pair with the PCE, such as labels and workload policy states.
Security Settings: General network security settings, such as ICMP echo reply, allow or disable IPv6, and connectivity settings.
Services: Definitions or discovery of existing services on your workloads.
Virtual Servers: Allows rules that allow communication with workloads managed by a load balancer.
Virtual Services: A virtual service is a single service (a port/protocol set) that can be used directly in a rule as a single entity. labels that represent multiple virtual services can also be used to write rules.
Enforcement Boundaries: Facilitate the implementation of allow-lists by narrowing the scope for segmentation so that users can reach a high level of system maintainability using a simple policy mode.

When the security policy is provisioned, the PCE recalculates any changes made to policy configurations and then transmits those changes to the VENs installed on the workloads.

Policy Provisioning States

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.

Get All Items Pending Provisioning

This method gets a list of all modified policy items pending provisioning.

URI to Get All Policy Items Pending Provisioning

This API allows the user to view a list of all policy objects pending provisioning bucketed by type. The UI uses this to generate the "draft changes" page.

GET [api_version][org_href]/sec_policy/pending

Get Items Pending Provisioning

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

Response

---------
	],
	"virtual_services": [
		{
			"name": "string",
			"href": "string",
			"updated_by": null,
			"updated_at": "2021-05-03T00:24:56Z",
			"update_type": "create",
			"caps": [
			"write"
			]
		}
	],
	"enforcement_boundaries": [
		{
			"name": "string",
			"href": "string",
			"updated_by": null,
			"updated_at": "2021-05-03T00:24:56Z",
			"update_type": "create",
			"caps": [
			"write"
			]
		}
	]
}

The field selective_enforcement_rules was replaced with enforcement_boundaries.

Revert All Items Pending Provisioning

This method reverts (undoes) the current set of unprovisioned security policy modifications (all unprovisioned draft changes).

DELETE [api_version][org_href]/sec_policy/pending

Revert all items pending provisioning

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/pending -u $KEY:$TOKEN

Revert a List of Items Pending Provisioning

This API allows the user to revert a subset of policy objects via the change_subset field. via the change_subset field.

The field selective_enforcement_rules was replaced with enforcement_boundaries.

Revert a Specific List of Items Pending Provisioning

PUT [api_version][org_href]/sec_policy/delete

{
	"change_subset": {
	"label_groups": [
		{
			"href": "string"
		}
	],
	"services": [
		{
			"href": "string"
		}
	],
	"rule_sets": [
		{
			"href": "string"
		}
	],
	"ip_lists": [
		{
			"href": "string"
		}
	],
	"virtual_services": [
		{
			"href": "string"
		}
	],
	"firewall_settings": [
		{
			"href": "string"
		}
	],
	"secure_connect_gateways": [
		{
			"href": "string"
		}
	],
	"virtual_servers": [
		{
			"href": "string"
		}
	],
	"enforcement_boundaries": [
		{
			"href": "string"
		}
	]
   }
}

If an empty request body is given,

{}

then all objects will be reverted.

Curl Command to Revert a Pending Rule

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/1/sec_policy/delete -H "Accept: application/json" -H "Content-Type: application/json" -u api_1fc24761346777702:'26c55be6892762b65f27aacc795076767f16ffcd7e9fde323a307e5fd286eb8d' -d '{"change_subset":{"rule_sets":[{"href":"/orgs/1/sec_policy/draft/rule_sets/3"}]}}'

Get Provisioning Dependencies

This public experimental API allows the user to determining the provisioning (or revert) dependencies for a particular policy object. The response JSON is also bucketed by object, and has the same schema change.

URI to Get Specific Provisioning Dependencies

POST /sec_policy/draft/dependencies

Parameters

Parameter	Description	Type	Req
`change_subset`	Defines a hash of provisionable or revertible objects identified by their HREFs. Includes label groups, services, rulesets, IP lists, virtual services, and virtual servers. Each individual object of a specific type (for example, `rule_sets`) is represented in the request body as an array of HREFs for those object types.	Object	Yes
`operation`	Determines if there are dependencies for provisioning or reverting the specified objects: `commit`: Specify this value to check for dependencies before provisioning an object. `revert`: Specify this value to check for dependencies before reverting an object that is in a `draft` state.	String	Yes
Sub properties of `change_subset` that represent provisionable objects		Array	No
`label_groups`	List of label groups in the draft state to check for provisioning dependencies identified by label group HREF.	String	No
`services`	List of services in the draft state to check for provisioning dependencies identified by service HREF.	String	No
`rule_sets`	List of rulesets in the draft state to check for provisioning dependencies identified by rule_set HREF.	String	No
`ip_lists`	List of IP lists in the draft state to check for provisioning dependencies, identified by IP list HREF.	String	No
`virtual_services`	List of virtual services in the draft state to check for provisioning dependencies identified by virtual service HREF.	String	No
`virtual_servers`	List of virtual servers in the draft state that you want to check for provisioning dependencies identified by virtual server HREF.	String	No
`firewall_settings`	List of security settings (`firewall_settings`) in the draft state to check for provisioning dependencies identified by the security settings HREF for your PCE. Currently, the only security setting that can be modified with the REST API is the policy update mode.	String	No
`enforcement_boundaries`		Array	No

Request Body

{
	"operation": "commit",
	"change_subset": {
		"enforcement_boundaries": [
		{
		"href": "/orgs/2/sec_policy/draft/enforcement_boundaries/51"
		}
	    ]
	}
}

Check for Provisioning Dependencies

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/7/sec_policy/draft/dependencies -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"operation":"commit", "change_subset": {"rule_sets":[{"href":"/orgs/1/sec_policy/draft/rule_sets/9"}, {"href":"/orgs/1/sec_policy/draft/rule_sets/3"}], "virtual_services": [{"href":"/orgs/1/sec_policy/draft/virtual_services/xxxxxxxx-adeb-4895-8ff2-60c5b9833d9e"}, {"href":"/orgs/1/sec_policy/draft/virtual_services/xxxxxxxx-12bc-4cfa-99ef-330c399bc78c"}]}'

Response

The response indicates that the field selective_enforcement was replaced with enforcement_boudaries following the change in the request.

	"$ref": "../common/href_object.schema.json"
	}
},
-        "selective_enforcement_rules": {
+        "enforcement_boundaries": {
		"type": "array",
		"items": {
		"$ref": "../common/href_object.schema.json"

If there are no dependencies for either commit or revert, the response returns an empty array.

[]

Get Modified Items in a Provisioned Version

This method gets a collection of all modified policy items in a specific version of the security policy.

Every time the security policy is provisioned, it gets a version, which takes the form of an HREF. The HREF can be obtained when getting all provisioned versions of your security policy. You can use that provision version HREF when calling this method.

URI to Get All Modified Items in a Specific Provisioned Version

GET [api_version][sec_policy_version_href]/modified_objects

Curl Command Example

curl -X GET /orgs/{org_id}/sec_policy/{pversion}/modified_objects -u $KEY:$TOKEN -H 'Accept: application/json'

Response (similar to the following)

{
	"update_type": null,
	"object_type": null,
	"href": null,
	"name": "string",
	"updated_at": "2021-05-03T00:24:56Z",
	"updated_by": null,
}

Required properties updated_at and updated_by have been added and the properties modified_by and modified_at have been deleted.

Get Rules Allowing Communication

This method gets a list of all rules that allow communication between two workloads (and other entities) for a specific version of a provisioned security policy.

By default, the maximum number returned on a GET collection with this API is 500. If you want to get more than 500 results, use an Asynchronous GET Collection.

Check for Rules Between Workloads

GET /api/v2/orgs/{org_id}/sec_policy/{pversion}/allow

Query Parameters

Provide query parameters in the URI that specify the source workload IP address or HREF, the service HREF, and the destination workload HREF.

Parameter	Description	Type	Required
`org_id`	Organization	Integer	Yes
`pversion`	Security policy version	String	Yes
`src_external_ip` OR `src_workload`	The external IP of the source workload or The URI of the source workload	String	No
`dst_external_ip` OR `dst_workload`	The external IP of the destination workload OR The URI of the destination workload	String	No
`service`	The specific service to check	String	No
`port`	The specific port number to check	Integer	No
`protocol`	The specific protocol number to check	Integer	No

Curl Command to Get Rules Between Workloads

The workloads and the service are identified by their HREFs:

curl -X GET /orgs/{org_id}/sec_policy/{pversion}/allow -u $KEY:$TOKEN -H 'Accept: application/json'

Response

[
	{
	"href": "string",
	"enabled": true,
	"description": "string",
	"service": {
		"href": "string"
	},
	"ub_service": null,
	"sec_connect": true,
	"providers": [
	{
		"actors": "string",
		"label": {
		"href": "string"
		},
		"agent": {
			"href": "string"
		},
		"workload": {
			"href": "string"
		},
		"bound_service": {
			"href": "string"
		},
		"virtual_server": {
			"href": "string"
		},
		"ip_list": {
			"href": "string"
		}
	}
	],
	"destinations": [
		{
		"actors": "string",
		"label": {
			"href": "string"
		},
		"agent": {
			"href": "string"
		},
		"workload": {
			"href": "string"
		},
		"bound_service": {
			"href": "string"
		},
		"ip_list": {
			"href": "string"
		}
	}
]
}

REST APIs for 22.2

Provisioning (Public Experimental)

Provisioning API Methods

Provisionable Policy Items

Policy Provisioning States

Get All Items Pending Provisioning

Revert All Items Pending Provisioning

Revert a List of Items Pending Provisioning

Get Provisioning Dependencies

Parameters

Get Modified Items in a Provisioned Version

Get Rules Allowing Communication

Query Parameters

Search results