Provisioning (Public Experimental)
This Public Experimental API gets information about un-provisioned 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.
To provision security policy items and get information about one or more provisioned items, see "Provisioning – Public Stable".
Provisioning API Methods
Functionality | HTTP | URI |
|---|---|---|
Get the collection of modified ( |
|
|
Check whether a rule exists between two workloads that allow communication. |
|
|
Get the collection of all policy items that were modified in a specific version of a security policy. |
|
|
Delete all un-provisioned security policy item modifications (all un-provisioned |
|
|
Revert a specified list of pending uncommitted security policy items. This method allows you to select specific items to revert. |
|
|
Determine if a specific set of objects can be provisioned or if they depend on other objects that need to be provisioned. |
|
|
Used to see the policy impact before provisioning. This API is referencing |
|
|
Provisionable Policy Items
The following security policy items require provisioning before they can affect managed workloads (workloads with a VEN installed). 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 items that include 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: By narrowing the scope for segmentation, enforcement boundaries facilitate the implementation of allow lists, enabling users to achieve 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
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
Revert All Items Pending Provisioning
This method reverts (undoes) the current set of non-provisioned security policy modifications (all non-provisioned draft changes).
DELETE [api_version][org_href]/sec_policy/pending
Get Security Policy Dependencies
This public experimental API allows the user to determine a particular policy object's provisioning (or revert) dependencies. An object also buckets the response JSON and has the same schema change.
URI to Get Specific Security Policy Dependencies
POST /sec_policy/draft/dependencies
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.
Check for Rules Between Workloads
GET /api/v2/orgs/{org_id}/sec_policy/{pversion}/allowRevert 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
Get Modified Items in a Provisioned Version
This method collects all modified policy items in a specific security policy version.
Every time the security policy is provisioned, it gets a version in the form of an HREF. You can obtain the HREF by 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
Provisioning (Public Experimental) Reference
This topic covers examples of public experimental APIs for provisioning.
Examples
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 a Specific List of Items Pending Provisioning
curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/pending -u $KEY:$TOKEN
{
"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"}]}}'Security Policy Properties
Parameter | Description |
|---|---|
| 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, For
|
| Determines if there are dependencies for provisioning or reverting the specified objects:
|
Subproperties of | |
| List of label groups in the draft state to check for provisioning dependencies identified by label group HREF. |
| List of services in the draft state to check for provisioning dependencies identified by service HREF. |
| List of rulesets in the draft state to check for provisioning dependencies identified by rule_set HREF. |
| List of IP lists in the draft state to check for provisioning dependencies, identified by IP list HREF. |
| List of virtual services in the draft state to check for provisioning dependencies identified by virtual service HREF. Reference to |
| List of virtual servers in the draft state that you want to check for provisioning dependencies identified by virtual server HREF. Reference to |
| Reference to |
| Reference to |
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.
[]
Curl command example: Get all modified items in a specific provisioned version
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 modified_by and modified_at have been deleted.
Provide query parameters in the URI that specify the source workload IP address or HREF, the service HREF, and the destination workload HREF. You can obtain a workload HREF with a GET call on the Workloads API.
Parameter | Description | Type | Required |
|---|---|---|---|
| Organization | Integer | Yes |
| Security policy version | String | Yes |
OR
| The external IP of the source workload or The URI of the source workload | String | No |
OR
| The external IP of the destination workload OR The URI of the destination workload | String | No |
| The specific service to check | String | No |
| The specific port number to check | Integer | No |
| 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"
}
}
],
"consumers": [
{
"actors": "string",
"label": {
"href": "string"
},
"agent": {
"href": "string"
},
"workload": {
"href": "string"
},
"bound_service": {
"href": "string"
},
"ip_list": {
"href": "string"
}
}
]
}Example for POST /api/v2/orgs/1/sec_policy/impact
Each of the allowed properties such as ip_lists, label_groups, and services can be included in the request body of the POST call and the response schema defines the format and values of this API request for the example in the request body.
sec_policy_impact_post_response.schema.json
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"required": ["num_sets", "num_managed_workloads", "num_container_workloads",
"num_unmanaged_workloads"],
"properties": {
"num_sets": {
"description": "number of affected sets",
"type": "integer"
},
"num_virtual_servers": {
"description": "number of affected virtual servers",
"type": "integer"
},
"num_managed_workloads": {
"description": "number of affected workloads of type Workload",
"type": "integer"
},
"num_container_workloads": {
"description": "number of affected workloads of type ContainerWorkload",
"type": "integer"
},
"num_unmanaged_workloads": {
"description": "number of affected unmanaged workloads",
"type": "integer"
},
"all_workloads_optimization": {
"description": "flag to indicate if all-workloads-optimization has been used",
"type": "boolean"
}
}
}