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 an individual service. |
|
|
Create a new service. |
|
|
Update an individual service. |
|
|
Delete an individual service. |
|
|
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 |
---|---|---|---|
| Organization | Integer | Yes |
| Name of service on which to filter. This parameter supports partial matches. | String | GET: No POST: Yes |
| Description of the service on which to filter. This parameter supports partial matches. | String | No |
| Security Policy Version | String | Yes |
| The data source from which the resource originates. For example, if service information is stored in an external database. | String | No |
| A unique identifier within the external data source. For example, if service information is stored in an external database. | String | No |
| Services associated with ransomware. | Boolean | No |
| 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 of service on which to filter. This parameter supports partial matches. | String | GET: No POST: Yes |
| Specify port or port range to filter results. The range is from -1 to 65535 (0 is not supported). | String | No |
| Protocol to filter on | Integer | GET: No PUT, POST: Yes |
Properties for Services
Properties | Description | Type |
---|---|---|
| URI of the service | String |
| Name of service (does not need to be unique) | String |
| Description of the service | String |
risk_details | This property contains the object It contains the following properties:
| Object, NULL |
| Description URL Read-only to prevent XSS attacks | String |
| Name of the process. | String |
| Reference to | |
| Reference to | |
| External data set identifier. | String NULL |
| 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