ON THIS PAGE
Using the Policy Enforcer Connector API
The following sections provide usage examples for the various APIs defined in the Plug-in/Adaptor Schema for External System Integration with PE API:
Get Connector Type Details
Use this request to obtain information about the type of connector implemented by Policy Enforcer.
URI |
/api/v2/connector |
HTTP method |
GET |
Content-Type |
application/json |
Status |
200 Returns the following information:
|
Usage Example
Body: None.
Response:
{
"additionalSettings": [
{
"description": "Infected Host Security Group",
"name": "SECURITY_GROUP_NAME",
"required": true,
"type": "string"
},
{
"description": "SRX Identifier Tag",
"name": "SRX_ID_TAG",
"required": true,
"type": "string"
},
{
"description": "SRX Username",
"name": "SRX_USERNAME",
"required": true,
"type": "string"
},
{
"description": "SRX Authentication Key",
"name": "PRIVATE_KEY_FILE",
"required": true,
"type": "file"
}
],
"capabilities": [
{
"name": "INFECTED_HOST_BLOCK"
},
{
"name": "INFECTED_HOST_QUARANTINE"
},
{
"name": "ENFORCEMENT_SUBNET_INFO"
},
{
"name": "ENDPOINT_TAGGING_INFO"
},
{
"name": "ENFORCEMENT_POINT_INFO"
}
],
"controllerContexts": true,
"type": "Amazon Web Services"
}
Modify Connector Server’s Environment
Use this request to update information about the environment of connector server.
URI |
/api/v2/connector/env |
HTTP method |
PUT |
Content-Type |
application/json |
Status |
200—Indicates the connector environment information is successfully received. |
Usage Example
Request:
{
"proxyServers": [
{
"type": "http",
"ipAddress": "192.168.10.1",
"port": 8080,
"username": "proxyuser",
"password": "juniper123"
},
{
"type": "https",
"ipAddress": "192.168.10.1",
"port": 8443,
"username": "proxyuser",
"password": "juniper123"
}
]
}
Response:
{
"proxyServers": [
{
"type": "http",
"ipAddress": "192.168.10.1",
"port": 8080,
"username": "proxyuser",
"password": "juniper123"
},
{
"type": "https",
"ipAddress": "192.168.10.1",
"port": 8443,
"username": "proxyuser",
"password": "juniper123"
}
]
}
Get Connector Configuration Details
Use this request to obtain the configuration information of all connectors.
URI |
/api/v2/connector/instances |
HTTP method |
GET |
Content-Type |
application/json |
Status |
200—Returns a list of connector configurations. |
Usage Example
Body: None.
Response:
{
"connectors": [
{
"additionalSettings": {
"settings": [
{
"name": "SRX_USERNAME",
"value": "root"
},
{
"name": "SRX_ID_TAG",
"value": "VSRX"
},
{
"name": "PRIVATE_KEY_FILE",
"value": "https://127.0.0.1:8080/api/v2/controller/files/852af83b-0a6d-40c9-b397-4964de59ccc3"
},
{
"name": "SECURITY_GROUP_NAME",
"value": "aws_sg_block"
}
],
"total": 4
},
"controllerClientId": "AKIYXUTNS4UIQ5824BMQ",
"controllerContext": "US West (N. California)",
"controllerEndpointAddressSpace": {
"name": "vpc-90e3f1f4_VPC_SDSN",
"type": "Vpc"
},
"controllerIp": "aws.amazon.com",
"controllerPort": 443,
"controllerSecret": "1ggYYha0OCF0kG9qaJMG0Pgjacd3rStvAeHgHmVc",
"id": 1,
"name": "aws_31",
"uri": "http://127.0.0.1:8084/api/v2/connector/instances/1"
},
{
"additionalSettings": {
"settings": [
{
"name": "SRX_USERNAME",
"value": "root"
},
{
"name": "SRX_ID_TAG",
"value": "vSRX"
},
{
"name": "PRIVATE_KEY_FILE",
"value": "https://127.0.0.1:8080/api/v2/controller/files/fc6aca5e-f3a7-4d9e-9bac-bf5fbfab4be3"
},
{
"name": "SECURITY_GROUP_NAME",
"value": "aws_sg_block"
}
],
"total": 4
},
"controllerClientId": "AKIYXUTNS4UIQ5824BMQ",
"controllerContext": "US West (Oregon)",
"controllerEndpointAddressSpace": {
"name": "vpc-4bf15832_un-ore-vpc01",
"type": "Vpc"
},
"controllerIp": "aws.amazon.com",
"controllerPort": 443,
"controllerSecret": "1ggYYha0OCF0kG9qaJMG0Pgjacd3rStvAeHgHmVc",
"id": 2,
"name": "aws_31",
"uri": "http://127.0.0.1:8084/api/v2/connector/instances/2"
}
],
"total": 2
}
Instantiate a Connector
Use this request to instantiate a connector with the specified configuration.
URI |
/api/v2/connector/instances |
HTTP method |
POST |
Content-Type |
application/json |
Status |
|
Usage Example
Body:
{
"name": "aws_31",
"controllerIp": "aws.amazon.com",
"controllerPort": 443,
"controllerClientId": "AKIYXUTNS4UIQ5824BMQ",
"controllerSecret": "1ggYYha0OCF0kG9qaJMG0Pgjacd3rStvAeHgHmVc",
"controllerContext": "US West (N. California)",
"controllerEndpointAddressSpace": {
"name": "vpc-90e3f1f4_VPC_SDSN",
"type": "Vpc"
},
"additionalSettings": {
"total": 4
"settings": [
{
"name": "SRX_USERNAME",
"value": "root"
},
{
"name": "SRX_ID_TAG",
"value": "VSRX"
},
{
"name": "PRIVATE_KEY_FILE",
"value": "https://127.0.0.1:8080/api/v2/controller/files/852af83b-0a6d-40c9-b397-4964de59ccc3"
},
{
"name": "SECURITY_GROUP_NAME",
"value": "aws_sg_block"
}
]
}
}
Response:
{
"id": "1",
"uri": "http://127.0.0.1:8084/api/v2/connector/instances/1",
"name": "aws_31",
"controllerIp": "aws.amazon.com",
"controllerPort": 443,
"controllerClientId": "AKIYXUTNS4UIQ5824BMQ",
"controllerSecret": "1ggYYha0OCF0kG9qaJMG0Pgjacd3rStvAeHgHmVc",
"controllerContext": "US West (N. California)",
"controllerEndpointAddressSpace": {
"name": "vpc-90e3f1f4_VPC_SDSN",
"type": "Vpc"
},
"additionalSettings": {
"total": 4,
"settings": [
{
"name": "SRX_USERNAME",
"value": "root"
},
{
"name": "SRX_ID_TAG",
"value": "VSRX"
},
{
"name": "PRIVATE_KEY_FILE",
"value": "https://127.0.0.1:8080/api/v2/controller/files/852af83b-0a6d-40c9-b397-4964de59ccc3"
},
{
"name": "SECURITY_GROUP_NAME",
"value": "aws_sg_block"
}
]
}
}
Get Connector Instance Details by ID
Use this request to obtain configuration information for the specified connector instance.
URI |
/api/v2/connector/instances/{connectorId} |
HTTP method |
GET |
Content-Type |
application/json |
Status |
|
Usage Example
Body: None.
Response:
{
"id": "1",
"uri": "http://127.0.0.1:8084/api/v2/connector/instances/1",
"name": "aws_31",
"controllerIp": "aws.amazon.com",
"controllerPort": 443,
"controllerClientId": "AKIYXUTNS4UIQ5824BMQ",
"controllerSecret": "1ggYYha0OCF0kG9qaJMG0Pgjacd3rStvAeHgHmVc",
"controllerContext": "US West (N. California)",
"controllerEndpointAddressSpace": {
"name": "vpc-90e3f1f4_VPC_SDSN",
"type": "Vpc"
},
"additionalSettings": {
"total": 4,
"settings": [
{
"name": "SRX_USERNAME",
"value": "root"
},
{
"name": "SRX_ID_TAG",
"value": "VSRX"
},
{
"name": "PRIVATE_KEY_FILE",
"value": "https://127.0.0.1:8080/api/v2/controller/files/852af83b-0a6d-40c9-b397-4964de59ccc3"
},
{
"name": "SECURITY_GROUP_NAME",
"value": "aws_sg_block"
}
]
}
}
Modify Connector Instance
Use this request to update the configuration for the specified connector instance.
URI |
/api/v2/connector/instances/{connectorId} |
HTTP method |
PUT |
Content-Type |
application/json |
Status |
|
Usage Example
Request:
{
"id": "1",
"name": "aws_31",
"controllerIp": "aws.amazon.com",
"controllerPort": 443,
"controllerClientId": "AKIYXUTNS4UIQ5824BMQ",
"controllerSecret": "1ggYYha0OCF0kG9qaJMG0Pgjacd3rStvAeHgHmVc",
"controllerContext": "US West (N. California)",
"controllerEndpointAddressSpace": {
"name": "vpc-90e3f1f4_VPC_SDSN",
"type": "Vpc"
},
"additionalSettings": {
"total": 4
"settings": [
{
"name": "SRX_USERNAME",
"value": "root"
},
{
"name": "SRX_ID_TAG",
"value": "VSRX"
},
{
"name": "PRIVATE_KEY_FILE",
"value": "https://127.0.0.1:8080/api/v2/controller/files/852af83b-0a6d-40c9-b397-4964de59ccc3"
},
{
"name": "SECURITY_GROUP_NAME",
"value": "aws_sg_block"
}
]
}
}
Response:
{
"id": "1",
"uri": "http://127.0.0.1:8084/api/v2/connector/instances/1",
"name": "aws_31",
"controllerIp": "aws.amazon.com",
"controllerPort": 443,
"controllerClientId": "AKIYXUTNS4UIQ5824BMQ",
"controllerSecret": "1ggYYha0OCF0kG9qaJMG0Pgjacd3rStvAeHgHmVc",
"controllerContext": "US West (N. California)",
"controllerEndpointAddressSpace": {
"name": "vpc-90e3f1f4_VPC_SDSN",
"type": "Vpc"
},
"additionalSettings": {
"total": 4,
"settings": [
{
"name": "SRX_USERNAME",
"value": "root"
},
{
"name": "SRX_ID_TAG",
"value": "VSRX"
},
{
"name": "PRIVATE_KEY_FILE",
"value": "https://127.0.0.1:8080/api/v2/controller/files/852af83b-0a6d-40c9-b397-4964de59ccc3"
},
{
"name": "SECURITY_GROUP_NAME",
"value": "aws_sg_block"
}
]
}
}
Delete a Connector Instance
Use this request to delete a connector instance.
URI |
/api/v2/connector/instances/{connectorId} |
HTTP method |
DELETE |
Content-Type |
None |
Status |
|
Get the Connector and its Controller Status
Use this request to check reachability of the connector and the status of its underlying controller.
URI |
/api/v2/connector/instances/{connectorId}/heartbeat |
HTTP method |
GET |
Content-Type |
None |
Status |
|
Get All Enforcement Point Devices
Use this request to obtain information on the physical or virtual network devices such as firewall, switches, and routers performing the enforcement-related operations. These operations are either currently managed or to be managed by the associated EMS of Policy Enforcer.
You can perform this request only if the connector supports the ENFORCEMENT_POINT_INFO capability.
URI |
/api/v2/connector/instances/{connectorId}/enforcement-points |
HTTP method |
GET |
Content-Type |
application/json |
Status |
|
Usage Example
Response:
{
"device": [
{
"authSecretType": "PRIVATE_KEY_FILE",
"ip": "35.163.47.86",
"name": "un-ore-vsrx02",
"privateKeyFile": "https://127.0.0.1:8080/api/v2/controller/files/fc6aca5e-f3a7-4d9e-9bac-bf5fbfab4be3",
"roles": "FIREWALL",
"tags": [
{
"key": "Name",
"value": "un-ore-vsrx02"
},
{
"key": "vSRX",
"value": "un-ore-vsrx02"
}
],
"username": "root"
}
],
"total": 1
}
Get All Enforcement Subnets
Use this request to obtain information on the subnets containing endpoints that the connector can perform enforcement actions.
This is only available if the connector supports the ENFORCEMENT_SUBNET_INFO capability.
URI |
/api/v2/connector/instances/{connectorId}/enforcement-subnets |
HTTP method |
GET |
Content-Type |
application/json |
Status |
|
Usage Example
Response:
{
"subnet": [
"10.0.30.0/24",
"10.0.10.0/24",
"10.0.43.0/24",
"10.0.42.0/24",
"10.0.41.0/24",
"10.0.50.0/24",
"10.0.20.0/24"
],
"total": 7
}
Retrieve Connector Log Files
Use this request to retrieve a zip file containing the log files of a connector server.
URI |
/api/v2/connector/logs |
HTTP method |
GET |
Content-Type |
application/json |
Status |
|
Block the Infected Host Threat
Use this request to instruct the connector to perform a remediation action against an infected host threat.
This is available only if the connector supports the INFECTED_HOST_BLOCK and INFECTED_HOST_QUARANTINE capabilities.
URI |
/api/v2/connector/instances/{connectorId}/threats/infected-hosts |
HTTP method |
POST |
Content-Type |
application/json |
Status |
|
Usage Example
Request:
{
"endpoint": {
"ip": "10.0.30.8",
},
"action": "block"
}
Response:
{
"action": "block",
"actionStatus": "SUCCEEDED",
"endpoint": {
"additionalInfo": [],
"ip": "10.0.30.8",
"macAddress": "00:0C:29:24:8A:F4",
"nasName": "ex4300-01",
"nasPort": "ge-0/0/1"
}
}
Get All Infected Host Threats
Use this request to Obtain the status of all the current infected host threats.
URI |
/api/v2/connector/instances/{connectorId}/threats/infected-hosts |
HTTP method |
GET |
Content-Type |
application/json |
Status |
|
Usage Example
Response:
{
"total": 1,
"threats": [
{
"action": "block",
"actionStatus": "SUCCEEDED",
"endpoint": {
"additionalInfo": [],
"ip": "10.0.30.8",
"macAddress": "00:0C:29:24:8A:F4",
"nasName": "ex4300-01",
"nasPort": "ge-0/0/1"
}
}
]
}
Block the DDoS Attack Threat
Use this request to instruct the connector to perform a remediation action against a Distributed Denial of Service (DDoS) attack threat.
This is available only if the connector supports the DDOS_BLOCK capability.
URI |
/api/v2/connector/instances/{connectorId}/threats/ddos |
HTTP method |
POST |
Content-Type |
application/json |
Status |
|
Usage Example
Request:
{
"sourceIps": [
"1.1.1.1",
"2.2.2.2"
],
"enforcementPointIp": "192.168.10.2"
}
Response:
{
"sourceIps": [
"1.1.1.1",
"2.2.2.2"
],
"enforcementPointIp": "192.168.10.2",
"actionStatus": "SUCCEEDED"
}
Get a List of DDoS Threats
Use this request to obtain the status of all the current DDoS threats.
URI |
/api/v2/connector/instances/{connectorId}/threats/ddos |
HTTP method |
GET |
Content-Type |
application/json |
Status |
|
Usage Example
Response:
{
"total": 1,
"threats": [
{
"sourceIps": [
"1.1.1.1",
"2.2.2.2"
],
"enforcementPointIp": "192.168.10.2",
"actionStatus": "SUCCEEDED"
}
]
}
Get IP Addresses of the Endpoints
Use this request to query the IP addresses of the endpoints tagged with a specified value.
This is available only if the connector supports the ENDPOINT_TAGGING_INFO capability.
URI |
/api/v2/connector/instances/{connectorId}/endpoints?tagValue=Web&tagName=Application Note:
You can use asterisk (*) for the tag value field to query all endpoints associated with the specified tag name. |
HTTP method |
GET |
Content-Type |
application/json |
Status |
|
Usage Example
Response:
{
"endpoints": [
{
"ip": "10.0.30.64",
"tag": {
"key": "Application",
"value": "Web"
}
},
{
"ip": "10.0.43.153",
"tag": {
"key": "Application",
"value": "Web"
}
},
{
"ip": "10.0.41.85",
"tag": {
"key": "Application",
"value": "Web"
}
}
],
"total": 3
}
Get All Tag Names and Their Values
Use this request to obtain information on all tag names that are currently referenced by the endpoints of a connector and for each endpoint, its unique set of values.
This is available only if the connector supports the ENDPOINT_TAGGING_INFO capability.
URI |
/api/v2/connector/instances/{connectorId}/endpoint-tags |
HTTP method |
GET |
Content-Type |
application/json |
Status |
|
Usage Example
Response:
{
"total": 2,
"tags": [
{
"tagName": "Application",
"tagValues": [
"Web",
"DB"
]
},
{
"tagName": "Deployment",
"tagValues": [
"Production",
"Test"
]
}
]
}
Register a Listener
Use this request to register a listener to notify any updates from the group of endpoints tagged with a particular value. When changes occur, a POST call is invoked against postNotificationUrl using postNotificationAuthToken.
URI |
/api/v2/connector/instances/{connectorId}/endpoint-tags/group-membership-listeners |
HTTP method |
POST |
Content-Type |
application/json |
Status |
|
Usage Example
Request:
{
"tagName": "Application",
"tagValue": "Web",
"postNotificationUrl": "https://127.0.0.1:8080/api/v2/connector/endpoint-tag-listener/f3843d51-b80d-4eaf-a381-d86a38c44fc4",
"postNotificationAuthToken": "4esO0z9bl8Q0U6WCue9gwKSYeFPpyaZP"
}
Response:
{
"id": "3",
"uri": "http://127.0.0.1:8084/api/v2/connector/instances/2/endpoint-tags/group-membership-listeners/3",
"tagName": "Application",
"tagValue": "Web",
"postNotificationUrl": "https://127.0.0.1:8080/api/v2/connector/endpoint-tag-listener/f3843d51-b80d-4eaf-a381-d86a38c44fc4",
"postNotificationAuthToken": "4esO0z9bl8Q0U6WCue9gwKSYeFPpyaZP"
}
Get All Registered Listeners
Use this request to obtain the list of all currently registered endpoint tag listeners. Only available if the connector supports the ENDPOINT_TAGGING_INFO capability.
URI |
/api/v2/connector/instances/{connectorId}/endpoint-tags/group-membership-listeners |
HTTP method |
GET |
Content-Type |
application/json |
Status |
|
Usage Example
Response:
{
"total": 1,
"listeners": [
{
"id": "3",
"uri": "http://127.0.0.1:8084/api/v2/connector/instances/2/endpoint-tags/group-membership-listeners/3",
"tagName": "Application",
"tagValue": "Web",
"postNotificationUrl": "https://127.0.0.1:8080/api/v2/connector/endpoint-tag-listener/f3843d51-b80d-4eaf-a381-d86a38c44fc4",
"postNotificationAuthToken": "4esO0z9bl8Q0U6WCue9gwKSYeFPpyaZP"
}
]
}
Get Details of a Listener by ID
Use this request to obtain information about the specified endpoint tag listener. Only available if the connector supports the ENDPOINT_TAGGING_INFO capability.
URI |
/api/v2/connector/instances/{connectorId}/endpoint-tags/group-membership-listeners/{listenerId} |
HTTP method |
GET |
Content-Type |
application/json |
Status |
|
Usage Example
Response:
{
"id": "3",
"uri": "http://127.0.0.1:8084/api/v2/connector/instances/2/endpoint-tags/group-membership-listeners/3",
"tagName": "Application",
"tagValue": "Web",
"postNotificationUrl": "https://127.0.0.1:8080/api/v2/connector/endpoint-tag-listener/f3843d51-b80d-4eaf-a381-d86a38c44fc4",
"postNotificationAuthToken": "4esO0z9bl8Q0U6WCue9gwKSYeFPpyaZP"
}
Deregister a Listener by ID
Use this request to deregister an endpoint tag listener. This is available only if the connector supports the ENDPOINT_TAGGING_INFO capability.
URI |
/api/v2/connector/instances/{connectorId}/endpoint-tags/group-membership-listeners/{listenerId} |
HTTP method |
DELETE |
Content-Type |
None |
Status |
|
Get a List of Controller Contexts
Use this request to query the specified controller for its list of contexts. This API is supported only for servers that require a controller context value to be specified when creating a connector instance.
URI |
/api/v2/connector/controller-contexts |
HTTP method |
GET |
Content-Type |
application/json |
Status |
|
Usage Example
GET /api/v2/connector/controller-contexts?controllerClientSecret= 1ggYYha0OCF0kG9qaJMG0Pgjacd3rStvAeHgHmVc&controllerPort=443&controllerClient Id=AKIYXUTNS4UIQ5824BMQ&controllerIp=aws.amazon.com
Response:
[
{
"name": "Asia Pacific (Mumbai)",
"type": "Region"
},
{
"name": "eu-west-3",
"type": "Region"
},
{
"name": "EU (London)",
"type": "Region"
},
{
"name": "EU (Ireland)",
"type": "Region"
},
{
"name": "Asia Pacific (Seoul)",
"type": "Region"
},
{
"name": "Asia Pacific (Tokyo)",
"type": "Region"
},
{
"name": "South America (S\u00e3o Paulo)",
"type": "Region"
},
{
"name": "Canada (Central)",
"type": "Region"
},
{
"name": "Asia Pacific (Singapore)",
"type": "Region"
},
{
"name": "Asia Pacific (Sydney)",
"type": "Region"
},
{
"name": "EU (Frankfurt)",
"type": "Region"
},
{
"name": "US East (N. Virginia)",
"type": "Region"
},
{
"name": "US East (Ohio)",
"type": "Region"
},
{
"name": "US West (N. California)",
"type": "Region"
},
{
"name": "US West (Oregon)",
"type": "Region"
}
]
Get More Information About a Controller
Use this request to query the specified controller for information, such as its set of entities implementing unique address spaces for endpoints.
URI |
/api/v2/connector/controller-info |
HTTP method |
GET |
Content-Type |
application/json |
Status |
|
Usage Example
GET /api/v2/connector/controller-info?controllerContext=Asia+Pacific+%28Mumbai%29& controllerClientSecret=1ggYYha0OCF0kG9qaJMG0Pgjacd3rStvAeHgHmVc& controllerPort=443&controllerClientId=AKIYXUTNS4UIQ5824BMQ& controllerIp=aws.amazon.com
Response:
{
"endpointAddressSpaces": [
{
"details": {
"childAddressSpaces": [
{
"name": "ap-south-1a",
"subnets": [
"10.0.3.0/24",
"10.0.254.0/24",
"10.0.2.0/24",
"10.0.5.0/24",
"10.0.1.0/24"
],
"type": "AvailabilityZone"
}
],
"endpointTags": {
"total": 1
"tags": [
{
"tagName": "Application",
"tagValues": [
"Web",
"DB"
]
}
},
"subnet": "10.0.0.0/16"
},
"endpointAddressSpace": {
"name": "vpc-5ff20937_manasahg-vpc",
"type": "Vpc"
}
},
{
"details": {
"childAddressSpaces": [
{
"name": "ap-south-1a",
"subnets": [
"10.0.2.0/24",
"10.0.1.0/24",
"10.0.4.0/24",
"10.0.8.0/24",
"10.0.254.0/24",
"10.0.3.0/24",
"10.0.7.0/24",
"10.0.6.0/24",
"10.0.5.0/24"
],
"type": "AvailabilityZone"
}
],
"endpointTags": {
"total": 1
{
"tagName": "Application",
"tagValues": [
"Web",
"DB"
]
}
},
"subnet": "10.0.0.0/16"
},
"endpointAddressSpace": {
"name": "vpc-b7530fde_abdulh-vpc",
"type": "Vpc"
}
}
]
}