Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation
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

    Modified: 2017-01-10