Skip to main content

REST APIs 25.3

Services

This Public Stable API gets, creates, updates, or deletes services. To write services, they must be in the “draft” state, which means they have not been provisioned. To provision changes made to services, use the Security Policy API.

Services API Methods

Functionality

HTTP

URI

Get a collection of services.

GET

[api_version][org_href]/sec_policy/{pversion}/services

Get an individual service.

GET

[api_version][org_href]/sec_policy/{pversion}/services/service_id

Create a new service.

POST

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

Update an individual service.

PUT

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

Delete an individual service.

DELETE

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

Active vs. Draft
Get Services

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.

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]
Create a Service

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
Update a Service

To update (PUT) an individual service, you need to know its HREF. The HREF of a service is returned when you get a collection of services from the PCE.

URI to Update an Individual Service

PUT [api_version][service_href]
Delete a Service

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]
Services Reference

This topic provides properties, parameters, and examples for service APIs.

Request Parameters for Services

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

name

Name of service on which to filter. This parameter supports partial matches.

String

GET: No

POST: Yes

description

Description of the service on which to filter.

This parameter supports partial matches.

String

No

pversion

Security Policy Version

String

Yes

external_data_set

The data source from which the resource originates.

For example, if service information is stored in an external database.

String

No

external_data_referenc

A unique identifier within the external data source.

For example, if service information is stored in an external database.

String

No

is_ransomware

Services associated with ransomware.

Boolean

No

max_results

The maximum number of results to return using GET.

The maximum limit for returned services is 500.

Note: If this parameter is not specified, or a value greater than 500 is specified, a maximum of 500 results are returned.

Integer

No

name

Name of service on which to filter. This parameter supports partial matches.

String

GET: No

POST: Yes

port

Specify port or port range to filter results. The range is from -1 to 65535 (0 is not supported).

String

No

proto

Protocol to filter on

Integer

GET: No

PUT, POST: Yes

Properties for Services

Properties

Description

Type

href

URI of the service

String

name

Name of service (does not need to be unique)

String

description

Description of the service

String

risk_details

This property contains the object ransomware, which is required to define the Ransomware Dashboard.

It contains the following properties:

  • category: Categorization based on Admin or Legacy port used in the service (required)

  • severity: Severity of this service (required)

  • os_platforms: Operating system for this ransomware service, an array with "minItems": 1. (required)

Object, NULL

description_url

Description URL Read-only to prevent XSS attacks

String

process_name

Name of the process.

String

service_ports

Reference to service_ports.schema.json

windows_services

Reference to windows_services.schema.json

external_data_set

External data set identifier.

String

NULL

external_data_reference

External data reference identifier.

String

NULL

sec_policy_post

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

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
      }
    ]
  }
Example payload to create a service
{
  "name": "RDP",
  "description": "Windows Remote Desktop",
  "service_ports": [
    {
      "port": 3389,
      "proto": 6
    }
  ]
}

Curl Command to Create Windows Service

This example shows how to create 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}]}' 
Request body to create a service

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

Curl Command to Delete a Service

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