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_referenc`	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

REST APIs for 24.2.20 and 24.2.10