Navigation
Table of Contents
Guide That Contains This Content
[+] Expand All
[-] Collapse All
Policy Controller API Usage Examples
The following sections provide usage examples for the various APIs defined in the Policy Controller API:
 | Note: For usage examples of the Config API, see Section Policy Controller Configuration and Setup. |
Usage Examples for Site API
The following are usage examples for the Site API:
Usage Example 1
POST <context>/api/v1/controller/sites
Content-Type: application/json
STATUS: 200
"site": {
"name": "sunnyvale",
"domain": "SD domain name",
"description": "location sunnyvale",
"feedSourceId": null,
"devices": [{"name": "dev1", "emsId":"1234", "serialNumber": "ABCD1234",
"ip": "192.0.2.0", "model": "srx1500",
"role": "EDGE_FIREWALL"},
{"name": "dev2", "emsId":"1235", "serialNumber": "ABCD1235",
"ip": "192.0.2.1", "model": "srx550",
"role": "AGGREGATION_FIREWALL"},
{"name": "dev3", "emsId":"1236", "serialNumber": "ABCD1236",
"ip": "192.0.2.1", "model": "srx550",
"role": "EDGE_FIREWALL"},
{"name": "dev4", "emsId":"1237", "serialNumber": "ABCD1237",
"ip": "192.0.2.2", "model": "ex4500",
"role": "CORE_SWITCH"},
{"name": "dev5", "emsId":"1238", "serialNumber": "ABCD1238",
"ip": "192.0.2.3", "model": "ex4300",
"role": "ACCESS_SWITCH"}
]
}
where:
- emsId is the device identifier from Security Director. You can use the Space REST API to obtain the device identifier using Device Management API.
- feedSourceId is the skyATP realm and its value is NULL during the POST operation. When a site is associated to realms, you can update the site with feedSourceId.
- The value of enrollStatus can be ENROLL_SUCCESS, ENROLL_FAILURE, DISENROLL_SUCCESS, or DISENROLL_FAILURE.
Usage Example 2
GET <context>/api/v1/controller/sites/{siteId}
Content-Type: application/json
STATUS: 200
"site": {
"id": "uuid-1234"
"uri":"https://<host>/<context>/api/v1/controller/sites/uuid-1234",
"name": "sunnyvale",
"domain": "SD domain name",
"description": "location sunnyvale",
"feedSourceId": "uuid-1234",
"devices": [{"deviceId": "11111", "name": "dev1", "emsId":"1234",
"serialNumber": "ABCD1234", "ip": "192.0.2.0",
"model": "srx1500", “role": "EDGE_FIREWALL",
"enrollStatus": "ENROLL_SUCCESS"},
{"deviceId": "22222", "name": "dev2", "emsId":"1235",
"serialNumber": "ABCD1234", "ip": "192.0.2.1",
"model": "srx550", role": "AGGREGATION_FIREWALL"},
{"deviceId": "33333", "name": "dev3", "emsId":"1236",
"serialNumber": "ABCD1234", "ip": "192.0.2.1",
"model": "srx550", "role": "EDGE_FIREWALL",
"enrollStatus": "ENROLL_FAILURE",
"statusReason": "failed .."},
{"deviceId": "44444", "name": "dev4", "emsId":"1237",
"serialNumber": "ABCD1234", "ip": "192.0.2.2",
"model": "ex4500", "role": "CORE_SWITCH"},
{"deviceId": "55555", "name": "dev5", "emsId":"1238",
"serialNumber": "ABCD1234", "ip": "192.0.2.3",
"model": "ex4300", "role": "ACCESS_SWITCH"}
]
}
Usage Example 3
PUT <context>/api/v1/controller/sites/{siteId}
Content-Type: application/json
STATUS: 200
"site": {
"name": "sunnyvale",
"domain": "SD domain name",
"description": "location sunnyvale",
"feedSourceId": "uuid-site-1234",
"devices": [{"name": "dev1", "emsId":"1234", "serialNumber": "ABCD1234",
"ip": "192.0.2.0", "model": "srx1500",
"role": "EDGE_FIREWALL"},
{"name": "dev2", "emsId":"1235", "serialNumber": "ABCD1235",
"ip": "192.0.2.1", "model": "srx550",
"role": "AGGREGATION_FIREWALL"},
{"name": "dev3", "emsId":"1236", "serialNumber": "ABCD1236",
"ip": "192.0.2.1", "model": "srx550",
"role": "EDGE_FIREWALL"},
{"name": "dev4", "emsId":"1237", "serialNumber": "ABCD1237",
"ip": "192.0.2.2", "model": "ex4500",
"role": "CORE_SWITCH"},
{"name": "dev5", "emsId":"1238", "serialNumber": "ABCD1238",
"ip": "192.0.2.3", "model": "ex4300",
"role": "ACCESS_SWITCH"}
]
}
Usage Example 4
GET <context>/api/v1/controller/sites
Content-Type: application/json
STATUS: 200
"sites": {
"uri":"https://<host>/<context>/api/v1/controller/sites",
"total": 2,
"site": [
{"id": "uuid-1234",
"uri":"https://<host>/<context>/api/v1/controller/sites/uuid-1234",
"name": "sunnyvale", "domain": "SD domain name",
"description": "location sunnyvale", "feedSourceId": "uuid-1234",
"devices": [{"deviceId": "11111", "name": "dev1", "ip", "192.0.2.0"},
{"deviceId": "22222", "name": "dev2", "ip", "192.0.2.1"}]},
{"id": "uuid-1235",
"uri":"https://<host>/<context>/api/v1/controller/sites/uuid-1235",
"name": "Westford", "domain": "SD domain name",
"description": "location westford", "feedSourceId": "uuid-1234",
"devices": [{"deviceId": "33333", "name": "dev3", "ip", "192.0.2.1"},
{"deviceId": "44444", "name": "dev4", "ip", "192.0.2.2"}]}
]
}
Usage Example 5
DELETE <context>/api/v1/controller/sites/{siteId}
STATUS: 204
Usage Examples for Policy Enforcement Group API
The following are usage examples for the Policy Enforcement Group API:
Usage Example 1
POST <context>/api/v1/controller/policyGroups
Content-Type: application/json
STATUS: 200
"policyGroup": {
"name": "sunnyvale",
"domain": "SD domain name",
"feedSourceId", "uuid-realm-1234"
"description": "sunnyvale user endpoints",
"groupType": "IP",
"sites": [{"siteId": "uuid-111", "name": "bldg-A",
"uri", "/api/v1/controller/Sites/uuid-111"},
{"siteId": "uuid-222", "name": "bldg-B",
"uri", "/api/v1/controller/Sites/uuid-222"},
{"siteId": "uuid-333", "name": "bldg-6",
"uri", "/api/v1/controller/Sites/uuid-333"}
],
"addressGroups": ["192.0.2.0/24", "198.51.100.0-198.51.100.255",
"203.0.113.0"]
}
where:
- locations and addressGroups are mutually exclusive.
- The value of addressGroups can be a single IP, an IP range, or an IP subnet.
- If the value of groupType is IP, addressGroups are populated; if the value is LOCATION, sites are populated.
Usage Example 2
GET <context>/api/v1/controller/policyGroups/{policyGroupId}
Content-Type: application/json
STATUS: 200
"policyGroup": {
"id": "uuid-1234",
"uri":"https://<host>/<context>/api/v1/controller/policyGroups/uuid-1234",
"name": "sunnyvale",
"domain": "SD domain name",
"feedSourceId", "uuid-realm-1234"
"description": "sunnyvale user endpoints",
"sites": [],
"addressGroups": ["192.0.2.0/24", "198.51.100.0-198.51.100.255",
"203.0.113.0"]
}
Usage Example 3
PUT <context>/api/v1/controller/policyGroups/{policyGroupId}
Content-Type: application/json
STATUS: 200
"policyGroup": {
"name": "sunnyvale",
"domain": "SD domain name",
"feedSourceId", "uuid-realm-1234"
"description": "sunnyvale user endpoints",
"sites": [],
"addressGroups": ["192.0.2.0/24", "198.51.100.0-198.51.100.255",
"203.0.113.0"]
}
Usage Example 4
GET <context>/api/v1/controller/policyGroups
Content-Type: application/json
STATUS: 200
"policyGroups": {
"uri":"https://<host>/<context>/api/v1/controller/policyGroups",
"total": 2,
"policyGroup": [
{"id": "uuid-1234",
"uri":"https://<host>/<context>/api/v1/controller/policyGroups/uuid-1234",
"name": "sunnyvale", "domain": "SD domain name",
"description": "sunnyvale user endpoints", "feedSourceId",
"uuid-realm-1234"
"sites": [],
"addressGroups":
["192.0.2.0/24", "198.51.100.0-198.51.100.255", "203.0.113.0"]},
{"id": "uuid-1234",
"uri":"https://<host>/<context>/api/v1/controller/policyGroups/uuid-1234",
"name": "sunnyvale", "domain": "SD domain name",
"description": "sunnyvale user endpoints", "feedSourceId",
"uuid-realm-1235"
"sites": [{"siteId": "uuid-111", "name": "bldg-A", "uri",
"/api/v1/controller/Sites/uuid-111"},
{"siteId": "uuid-222", "name": "bldg-B", "uri",
"/api/v1/controller/Sites/uuid-222"},
{"siteId": "uuid-333", "name": "bldg-6", "uri",
"/api/v1/controller/Sites/uuid-333"}
],
"addressGroups": []},
]
}
Usage Example 5
DELETE <context>/api/v1/controller/policyGroups/{policyGroupId}
STATUS: 204
Usage Examples for Threat Policy API
The following are usage examples for the Threat Policy API:
Usage Example 1
POST <context>/api/v1/controller/threatPolicys
Content-Type: application/json
STATUS: 200
"threatPolicy": {
"name": "simplePolicy",
"domain": "SD domain name",
"description": "with all profiles",
"profiles": [{
"feedType": "CnC",
"actions": [{"threatLevelStart": "0", "threatLevelEnd": "4",
"action": "PERMIT"},
{"threatLevelStart": "5", "threatLevelEnd": "7",
"action": "LOG"},
{"threatLevelStart": "8", "threatLevelEnd": "9",
"action": "BLOCK_CLOSE", "redirectUrl": "",
"customMessage": ""}]
}, {
"feedType": "INFECTED_HOST",
"actions": [{"threatLevelStart": "0", "threatLevelEnd": "4",
"action": "PERMIT"},
{"threatLevelStart": "8", "threatLevelEnd": "9",
"action": "BLOCK_QUARANTINE",
"quarantineVlanId": "911"}]
}, {
"feedType": "MALWARE", "malwareProfileName": "scanAll",
"actions": [{"threatLevelStart": "0", "threatLevelEnd": "6",
"action": "PERMIT"},
{"threatLevelStart": "7", "threatLevelEnd": "9",
"action": "BLOCK_CLOSE", "redirectUrl": "",
"customMessage": "call IT support"}]
}
],
"secondaryActions": ["LOG"],
"policyGroups": [{"policyGroupId": "uu-123", "name": "peg1"},
{"policyGroupId": "uu-456", "name": "peg2"}],
"deployStatus": "DRAFT"
}
where:
- The value of action can be PERMIT, LOG, BLOCK_DROP, BLOCK_CLOSE, or BLOCK_QUARANTINE.
- The value of secondaryAction cab be LOG_ALL, LOG_BLOCKED, or NONE.
- If you specify MALWARE as the feedType, SRX takes a single threat level threshold value, that is, it allows two actions — permit and block.
- If you specify GEO_IP as the feedType, then the SRX Series device has no threshold and allows permit or block.
- For deployStatus, you do not have to specify the values DRAFT, ANALYSIS_PROGRESS, READY_TO_DEPLOY, and DEPLOYED for POST and PUT operations.
Usage Example 2
PUT <context>/api/v1/controller/threatPolicys/uuid-1234/emsData
Content-Type: application/json
STATUS: 200
STATUS: 500 (It can have following errors)
"no PerimeterFirewall found based on PEG, skipping analysis"
"ATP analysis policy: <xyz> has aamw/infected-host profile, no argon capable device, skipping analysis"
"threatPolicy": {
"name": "simplePolicy",
"domain": "SD domain name",
"description": "with all profiles",
"profiles": [],
"secondaryActions": ["LOG"],
"policyGroups": [{"policyGroupId": "uu-123", "name": "peg1"}, {"policyGroupId": "uu-456", "name": "peg2"}],
"deployStatus": "DRAFT",
"emsAnalysisId": "uuid-policy-analysis",
"emsPublishUpdateId": "publish-update-job-id"
}
Usage Example 3
GET <context>/api/v1/controller/threatPolicys/uuid-1234
Content-Type: application/json
STATUS: 200
"threatPolicy": {
"id": "uuid-1234",
"uri":"https://<host>/<context>/api/v1/controller/threatPolicys/uuid-1234",
"name": "simplePolicy",
"domain": "SD domain name",
"description": "with all profiles",
"profiles": [{
"feedType": "CnC",
"actions": [{"threatLevelStart": "0", "threatLevelEnd": "4",
"action": "PERMIT"},
{"threatLevelStart": "5", "threatLevelEnd": "7",
"action": "LOG"},
{"threatLevelStart": "8", "threatLevelEnd": "9",
"action": "BLOCK_CLOSE",
"redirectUrl": "", "customMessage": ""}]
}, {
"feedType": "INFECTED_HOST",
"actions": [{"threatLevelStart": "0", "threatLevelEnd": "4",
"action": "PERMIT"},
{"threatLevelStart": "8", "threatLevelEnd": "9",
"action": "BLOCK_QUARANTINE",
"quarantineVlanName": "911"}]
}, {
"feedType": "MALWARE", "malwareProfileName": "scanAll",
"actions": [{"threatLevelStart": "0", "threatLevelEnd": "6",
"action": "PERMIT"},
{"threatLevelStart": "7", "threatLevelEnd": "9",
"action": "BLOCK_CLOSE",
"redirectUrl": "", "customMessage": "call IT support"}]
}
],
"secondaryActions": ["LOG"],
"policyGroups": [{"policyGroupId": "uu-123", "name": "peg1"},
{"policyGroupId": "uu-456", "name": "peg2"}],
"deployStatus": "DRAFT",
"deployDevices": [{"name": "device1", "deviceId": "uuid1234"}],
"skipDevices": [{"name": "device2", "deviceId": "uuid5678"}]
}Usage Example for DELETE Operation
DELETE <context>/api/v1/controller/threatPolicys/uuid-1234", STATUS: 204
Usage Examples of Custom Feed API
The following are usage examples for the Custom Feed API:
Usage Example 1
POST <context>/api/v1/controller/customFeeds/<feedType>/param/ip/<name>
Content-Type: application/json
Accept: application/json
STATUS: 200
Body:
"customFeed": {
"domain": "SD domain name",
"description": "safe IPs",
"content": ["192.0.2.0/24", "198.51.100.0-198.51.100.255"]
}
Response:
"customFeed": {
"id": "uuid-1234",
"name": "customGoodIPs",
"domain": "SD domain name",
"description": "safe IPs",
"feedType": "Whitelist",
"content": ["192.0.2.0/24", "198.51.100.0-198.51.100.255"]
}
where:
- The value of feedType can be BLACK_LIST, WHITE_LIST, or DYNAMIC_ADDRESS.
- The value of content can be a list of IP addresses, an IP range, or a subnet.
Usage Example 2
GET <context>/api/v1/controller/customFeeds/<feedType>/param/ip/<name>
Content-Type: application/json
STATUS: 200
Response:
"customFeed": {
"id": "uuid-1234",
"name": "customGoodIPs",
"domain": "SD domain name",
"description": "safe IPs",
"feedType": "Whitelist",
"content": ["192.0.2.0/24", "198.51.100.0-198.51.100.255"]
}Usage Example 3
GET <context>/api/v1/controller/customFeeds/param/
Content-Type: application/json
STATUS: 200
Response:
"customFeeds": {
"uri":"/api/v1/controller/customFeeds",
"total": 2,
"customFeed": [
{"id": "uuid-1234", "name": "customGoodIPs",
"domain": "SD domain name", "description": "safe IPs",
"feedType": "Whitelist",
"content": ["192.0.2.0/24", "198.51.100.0-198.51.100.255"]},
{"id": "uuid-3456", "name": "customBadIPs",
"domain": "SD domain name", "description": "bad IPs",
"feedType": "Blacklist", "content": ["192.0.2.0/24", "203.0.113.0"]},
{"id": "uuid-5678", "name": "dynamicIPs",
"domain": "SD domain name", "description": "misc IPs",
"feedType": "Dynamic-Address", "content": ["192.0.2.0/24"]}
]
}
Usage Example 4
PUT <context>/api/v1/controller/customFeeds/<feedType>/param/ip/<name>
Content-Type: application/json
STATUS: 200
Body:
"customFeed": {
"domain": "SD domain name",
"description": "safe IPs",
"content": ["192.0.2.0/24", "198.51.100.0-198.51.100.255"]
}
Response:
"customFeed": {
"id": "uuid-1234",
"name": "customGoodIPs",
"domain": "SD domain name",
"description": "safe IPs",
"feedType": "Whitelist",
"content": ["198.51.100.0-198.51.100.255", "203.0.113.0"]
}Usage Example 5
DELETE <context>/api/v1/controller/customFeeds/<feedType>/param/ip/<name> STATUS: 204
Usage Examples of Geo IP API
The following are usage examples for Geo IP API:
Usage Example 1
POST <context>/api/v1/controller/geoIps
Content-Type: application/json
STATUS: 200
"geoIp": {
"name": "asia",
"domain": "SD domain name",
"description": "all asia countries",
"countrys": [CN, IN],
"action": "BLOCK_INBOUND",
"secondaryAction": "LOG"
}where:
- The value of action can be BLOCK_INBOUND, BLOCK_OUTBOUND, or BLOCK_BOTH.
- The value of secondaryAction can be LOG or NONE.
| Note: The values for action and secondaryAction are only needed for SDSN. |
Usage Example 2
GET <context>/api/v1/controller/geoIps/{geoIpId}
Content-Type: application/json
STATUS: 200
"geoIp": {
"id": "uuid-1234",
"uri":"https://<host>/<context>/api/v1/controller/geoIps/uuid-1234",
"name": "asia",
"domain": "SD domain name",
"description": "all asia countries",
"countrys": [CN, IN],
"action": "INBOUND",
"secondaryAction": "LOG"
}Usage Example 3
GET <context>/api/v1/controller/geoIps
Content-Type: application/json
STATUS: 200
"geoIps": {
"uri":"https://<host>/<context>/api/v1/controller/geoips",
"total": 2,
"geoip": [
{"id": "uuid-1234", "name": "asia", "domain": "SD domain name",
"description": "all asia countries", "countrys": [CN, IN],
"action": "INBOUND", "secondaryAction": "LOG"},
{"id": "uuid-1235", "name": "north korea", "domain": "SD domain name",
"description": "some countries", "countrys": [KP],
"action": "INBOUND", "secondaryAction": "LOG"}
]
}Usage Example 4
DELETE <context>/api/v1/controller/geoIps/{geoIpId}
STATUS: 204