IP Lists

This PubIic Stable API can get, create, update, and delete IP lists.

IP lists can be used in rules to define sets of trusted IP addresses, IP address ranges, or CIDR blocks allowed into your data center to access workloads in your network.

IP Lists API

Functionality	HTTP	URI
Get a collection of IP lists	`GET`	`[api_version][org_href]/sec_policy/draft/ip_lists`
Get an individual IP list	`GET`	`[api_version][ip_list_href]`
Get a list of IP List attributes.	`GET`	`[api_version][org_href]/ip_list_attributes`
Create an IP list	`POST`	`[api_version][org_href]/sec_policy/draft/ip_lists`
Create a list of IP attributes	`POST`	`[api_version][org_href]/ip_list_attributes`
Update an IP list	`PUT`	`[api_version][ip_list_href]`
Upsert IP lists in bulk via CSVs.	`PUT`	`[api_version][org_href]/sec_policy/ip_lists_bulk_upload`
Delete an IP list	`DELETE`	`[api_version][ip_list_href]`

Active vs Draft

This API operates on provisionable objects, which exist in either a draft (not provisioned) state or an active (provisioned) state.

Provisionable items include label groups, services, rulesets, IP lists, virtual services, firewall settings, enforcement boundaries, and virtual servers. For these objects, the URL of the API call must include the element called :pversion, which can be set to either draft or active.

Depending on the method, the API follows these rules:

For GET operations — :pversion can be draft, active, or the ID of the security policy.
For POST, PUT, DELETE — :pversion can be draft (you cannot operate on active items) or the ID if the security policy.

Get IP Lists

This API allows you to get a collection of IP lists or a single IP list from an organization.

By default, the maximum number returned on a GET collection of IP lists is 500. If you want to get more than 500 IP lists, use Asynchronous GET Collections.

URI to Get Collection of IP Lists

GET [api_version][org_href]/sec_policy/draft/ip_lists

URI to Get an Individual IP List

GET [api_version][ip_list_href]

Create an IP List

This API allows you to create IP lists (allowlists) that can be used to create rules in rulesets. An IP list can contain a single IP address or an IP address range.

Warning

Please be aware of the following:

0.0.0.0/0 means 0-255 . 0-255 . 0-255 . 0-255 or all possible IP addresses.

0.0.0.0 without the trailing "/0", means a single IP (not ANY IP). This is a rare but sometimes needed object, specifically for DHCP Discovery.

0.0.0.0, when used improperly, might trigger an error, prevent the list from being accepted, and consequently block traffic.

Use the correct syntax for the intended purpose.

URI to Create an IP List

POST [api_version][org_href]/sec_policy/draft/ip_lists

Bulk Upload of IP Lists

This API allows customers to upsert IP lists in bulk via CSVs.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "IpList bulk_update",
  "type": "array",
  "maxItems": 1000
}

IP Lists Reference

This topic provides properties, parameters, and examples for IP lists.

Query parameters for IP lists

Parameter	Description	Type	Required
`org_id`	Organization	Integer	Yes
`pversion`	Security Policy Version	String	Yes
`description`	Description of IP list(s) to return. Supports partial matches	String	No
`external_data_set`	The data source from which the resource originates. For example, if this workload information is stored in an external database.	String	No
`external_data_reference`	A unique identifier within the external data source. For example, if this workload information is stored in an external database.	String	No
`ip_address`	IP address matching the IP lists to return. Supports partial matches.	String	No
`fqdn`	IP lists matching FQDN. Supports partial matches	String	No
`max_results`	The maximum number of results you want to return when using the GET method. The maximum limit for returned IP lists is 500.	Integer	No
`name`	Name of IP list(s) to return. Supports partial matches	String	No
`ip_list_id`	IP list ID (for `[api_version][ip_list_href]`	String	Yes

Properties for IP lists

Property	Description	Type	Required
`href`	URI of the ip list	String	Yes
`name`	The name of the IP lists to return has to be unique.	String	Yes
`description`	Description of IP list(s) to return. Supports partial matches	String	No
`external_data_set`	The data source from which the resource originates. For example, if this workload information is stored in an external database.	String, Null	No
`external_data_reference`	A unique identifier within the external data source. For example, if this workload information is stored in an external database.	String, Null	No
`fqdns`	Collection of FQDNs.	Array. Required: `fqdn`	No
`ip_list_id`	IP list ID (for `[api_version][ip_list_href]`	String	Yes
`ip_list_attribute`	"$ref": "ip_list_attributes_get.schema.json" `ip_list_attribute` with `sec_policy_ip_lists_get` allows filtering IP Lists with an attribute assigned. `ip_list_attribute` with `sec_policy_ip_lists_post` specifies which attribute should be linked to an IP List. `ip_list_attribute` with `sec_policy_ip_lists_put` specifies which attribute should be linked to an IP List.

Curl Command to Get a Collection of IP Lists

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/3/sec_policy/draft/ip_lists -H "Accept: application/json" -u $KEY:$TOKEN

Response Body

{
     {
        href: "/orgs/2/sec_policy/draft/ip_lists/309"
        id: 309
        created_at: "2020-04-17T21:59:44Z"
        updated_at: "2020-04-17T21:59:44Z"
        deleted_at: null
        created_by: {
            href: "/users/76"
     }
        updated_by: {
            href: "/users/76"
     }
        deleted_by: null
        name: "Good IPs 2"
        description: null
        ip_ranges: [
            {
               description: "My good IPs for web app"
               from_ip: "192.0.2.0"
               to_ip: null
            }
         ]
}

Curl Command to Get an IP List

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/3/sec_policy/draft/ip_lists/312 -H "Accept: application/json" -u $KEY:$TOKEN

Request Properties to create IP lists

Example JSON request body for a single IP list:

{
     "name": "Good IPs",
     "ip_ranges": [
           {
               "description": "Good IPs allowed to access app server",
               "from_ip": "192.0.2.0"
           }
     ]
}

Curl Command to Create IP List

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/3/sec_policy/draft/ip_lists -H "Accept: application/json" -u $KEY:$TOKEN -d '{"name": "Good IPs", "ip_ranges":[{"description": "Good IPs allowed to access app server", "from_ip": "192.0.2.0"}]}'

Response Body

{
     href: "/orgs/2/sec_policy/draft/ip_lists/316"
     created_at: "2020-04-18T00:19:55Z"
     updated_at: "2020-04-18T00:19:55Z"
     deleted_at: null
     created_by: {
          href: "/users/11"
     }
     updated_by: {
          href: "/users/11"
     }
     deleted_by: null
     name: "Good  IPs"
     description: null
     ip_ranges: [
         {
             description: "Good IPs"
             from_ip: "192.0.2.0"
             to_ip: null
         }
     ]
}

Update an IP List

This API updates a specific IP list identified by its HREF. Get a collection of IP lists to find IP list HREFs .

Example IP list HREF:

/orgs/2/sec_policy/draft/ip_lists/316

URI to Update an IP List

PUT [api_version][ip_list_href]

Example Request Body to Update an IP List

{
     "name": "Better IPs",
     "list_type": "allow",
     "ip_ranges": [
         {
             "description": "More allowed IPs for web app",
             "from_ip" : "192.0.2.0"
             "to_ip" : "24"
         }
     ]
}

Curl Command to Update IP List

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/3/sec_policy/draft/ip_lists/312 -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{ "name": "Better IPs", "list_type": "allow", "ip_ranges": [{"description": "Better IPs for web app", "from_ip": "192.0.2.0", "to_ip": "24"}]}'

Delete an IP List

This API removes an IP list from an organization:

URI to Delete an API List

DELETE [api_version][ip_list_href]

Curl Command to Delete IP List

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/draft/ip_lists/316 -u $KEY:$TOKEN

REST APIs 25.3