REST APIs for 23.5

This schema section shows how the property risk_details was added to define the categorization of services based on the ransomware threat:

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "object",
	"additionalProperties": false,
	"required": [
		"name"
		],
	"properties": {
		"name": {
		"description": "Name (does not need to be unique)",
			"type": "string"
		},
		"description": {
			"description": "Description",
			"type": "string"
		},
		"risk_details": {
		"type": "object",
		"properties": {
			"ransomware": {
			"type": "object",
			"properties": {
			"category": {
				"description": "Categorization based on Admin or Legacy port used in the service",
				"type": "string",
				"enum": [
				"admin",
				"legacy"
			]
		},
		"severity": {
			"description": "Severity of this service",
			"type": "string",
			"enum": [
				"low",
				"medium",
				"high",
				"critical"
			]
		},
		"os_platforms": {
			"description": "Operating system for this ransomware service",
			"type": "array",
			"minItems": 1,
			"items": {
			"type": "string",
			"enum": [
				"windows",
				"linux"
				]
			}
		    }
	      }    
         }
     ============================================================================

This API gets all the services in your organization that are in the “draft” policy state (not yet provisioned).

By default, the maximum number returned on a GET collection of services is 500. To get more than 500 services, use an Asynchronous GET Collection.

URI to Get a Collection of Services

GET [api_version][org_href]/sec_policy/draft/services

URI to Get an Individual Service

GET [api_version][service_href]

Curl Command to Get All Services

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

Curl Example to Get a Service

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

Response

Each individual service returned is identified by a service HREF. To GET, PUT, or DELETE an individual service, identify the service using its HREF in the API call.

{
    "href": "/orgs/7/sec_policy/active/services/878",
    "created_at": "2017-02-10T18:10:50.324Z",
    "updated_at": "2017-02-10T18:10:50.324Z",
    "deleted_at": null,
    "updated_by": null,
    "deleted_by": null,
    "name": "ICMP ECHO",
    "description": null,
    "description_url": null,
    "process_name": null,
    "service_ports": [
      {
        "icmp_type": 8,
        "icmp_code": null,
        "proto": 1
      },
      {
        "icmp_type": 128,
        "icmp_code": null,
        "proto": 58
      }
    ]
  }

This method creates an individual service. Once a service is created, it can be used to write rules for a security policy.

URI to Create a Service

POST [api_version][org_href]/sec_policy/draft/services

Example Payload

{
  "name": "RDP",
  "description": "Windows Remote Desktop",
  "service_ports": [
    {
      "port": 3389,
      "proto": 6
    }
  ]
}

Curl Command to Create Windows Service

This example shows creating a Windows Remote Desktop (RDP) service.

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/active/services -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"name":"RDP", "description":"Windows Remote Desktop","service_ports":[{"port":3389,"proto":6}]}' 

In order to update (PUT) an individual service, you need to know the HREF of the service you want to update. A service's HREF is returned when you get a collection of services from the PCE.

URI to Update an Individual Service

PUT [api_version][service_href]

Request Body

This example illustrates the request body you can pass to update a service, for example, to change the port used by the Nginx service from its current port number to 8080:

{
   "name": "nginx",
   "service_ports": [
     {
       "port": 8080,
       "proto": 6
     }
   ]
 }

Curl Command to Update Service

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/active/services/79 -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"name":"nginx","service_ports":[{"port":8080,"proto":6}]}' 

To delete an individual service, use the HREF of the service you want to delete, which is returned when you get a collection of services.

URI to Delete an Individual Service

DELETE [api_version][service_href]

Curl Command to Delete Service

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