The workspace (“application”) JSON object is returned as a single object or an array of objects depending on the API endpoint. The object’s attributes are described below:

This endpoint will return an array of workspaces (“applications”).

GET /openapi/v1/applications

Response object: Returns an array of workspace objects.

Sample python code

restclient.get('/applications')

This endpoint will return the requested workspace (“application”) as a single JSON object.

GET /openapi/v1/applications/{application_id}

Parameters: The request URL contains the following parameters

Response object: Returns the workspace object for the specified ID.

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  restclient.get('/applications/%s' % application_id)

This endpoint creates a workspace (“application”). It is possible to define policies by posting a JSON body containing the cluster and policy definitions.

Note	If a primary workspace exists for the same scope and new policies are provided, the policies will be added as a new version to the existing workspace.

POST /openapi/v1/applications

Parameters: The JSON query body contains the following keys

Extra optional parameters may be included describing policies to be created within the workspace.

Note	The scheme corresponds to that returned during export from the UI and the Details endpoint.

Cluster object attributes:

Node object attributes:

Inventory Filter object attributes:

Policy object attributes:

L4Params object attributes:

Response object: Returns the newly created workspace object.

Sample python code

  name = 'test'
  scope_id = '5ce480cc497d4f1b4b9a9e8d'
  filter_id = '5ce480cd497d4f1b4b9a9ea4'
  application = {
      'app_scope_id': scope_id,
      'name': name,
      'absolute_policies': [
          {
	      # consumer/provider filter IDs can be ID of a cluster identified during automatic policy discovery (formerly known as ADM),
	      # user inventory filter or app scope.
              'provider_filter_id': filter_id,
              'consumer_filter_id': filter_id,
              'action': 'ALLOW',
	      # ALLOW policy for TCP on port 80.
              'l4_params': [
                  {
                      'proto': 6, # TCP
                      'port': [80, 80],  # port range
                  }
              ],
          }
      ],
      'catch_all_action': 'ALLOW'
  }
  restclient.post('/applications', json_body=json.dumps(application))

Imports policies and creates a new v* version for the workspace (“application”).

POST /openapi/v1/applications/{application_id}/import

The parameters are the same as the create workspace endpoint.

Response object: Returns the workspace object.

Validates a set of policies without creating a new version.

POST /openapi/v1/applications/validate_policies

An app_scope_id is required. The rest of the parameters are the same as the create workspace endpoint.

Response object:

Removes a workspace (“application”).

DELETE /openapi/v1/applications/{application_id}

Enforcement must be disabled on the workspace before it can be deleted.

If the workspace, or its clusters, are used on by other Applications (via a Provided Service relationship) this endpoint will return 422 Unprocessable Entity. The returned Error object will contain a details attribute with the count of dependent objects along with the ids of the first 10 of each type. This information can be used to locate and remove the blocking dependencies.

Parameters: The request URL contains the following parameters

Response object: None

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  restclient.delete('/applications/%s' % application_id)

This end point updates an existing workspace (“application”).

PUT /openapi/v1/applications/{application_id}

Parameters: The request URL contains the following parameters

The JSON query body contains the following keys

Response object: The updated workspace object for the specified ID.

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  req_payload = {
        'name': 'Updated Name',
        'description': 'Updated Description',
        'primary': 'true'
  }
  resp = restclient.put('/applications/%s' % application_id,
                        json_body=json.dumps(req_payload))

This endpoint returns a full export JSON file for the workspace. This will include policy and cluster definitions.

GET /openapi/v1/applications/{application_id}/details

Parameters: The request URL contains the following parameters

Response object: Returns the clusters and policies for the given workspace version.

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  # For v* version v10 and for p* version p10
  version = 'v10'
  resp = restclient.get('/applications/%s/details?version=%s' % (application_id, version))

This endpoint will return a list of all the versions for a given workspace.

GET /openapi/v1/applications/{application_id}/versions

Parameters: The request URL contains the following parameters

Response object: An array of objects with the following attributes:

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  created_before = 1612325705
  limit = 10
  resp = restclient.get('/applications/%s/versions?created_before=%s&limit=%s' %
                        (application_id, created_before, limit))

This endpoint will remove the given version including clusters and policies. Enforced or Analyzed versions can not be deleted. If members are referenced by another workspace, through an external policy, the response will return error with a list of the references.

DELETE /openapi/v1/applications/{application_id}/versions/{version}

Parameters: The request URL contains the following parameters

Response object: None

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  version = 'v10'
  resp = restclient.delete('/applications/%s/versions/%s' %
                           (application_id, version))

This endpoint computes the difference between the provided workspace versions. It will return the added, removed and optionally the unchanged policies. Cluster changes are included if the cluster is present in both versions, defined by a matching consistent_uuid, and the query has changed.

GET /openapi/v1/applications/{application_id}/version_diff

Parameters: The request URL contains the following parameters

Response object: Returns an object with the following attributes:

Enable analysis on the latest set of policies in the workspace.

POST /openapi/v1/applications/{application_id}/enable_analysis

Parameters: The request URL contains the following parameters

Parameters: The optional JSON query body contains the following keys

Response object: Returns an object with the following attributes:

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  req_payload = {
    'action_note': 'Policy analysis',
    'name': 'Test run 1',
    'description': 'New workloads added.'
  }
  resp = restclient.post('/applications/%s/enable_analysis' % application_id,
                         json_body=json.dumps(req_payload))

Disable policy analysis on the workspace.

POST /openapi/v1/applications/{application_id}/disable_analysis

Parameters: The request URL contains the following parameters

Response object: Returns an object with the following attributes:

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  resp = restclient.post('/applications/%s/disable_analysis' % application_id)

Enable enforcement on the latest set of policies in the workspace.

POST /openapi/v1/applications/{application_id}/enable_enforce

Warning

New host firewall rules will be inserted and any existing rules will be deleted on the relevant hosts.

Parameters: The request URL contains the following parameters

If a version is not provided the latest policies of the workspace will be enforced. versions is preferred to be of the form ‘p*’, if just an integer is provided the corresponding ‘p*’ version will be enforced.

Response object: Returns an object with the following attributes:

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  req_payload = {
    'version': 'p10'
  }
  resp = restclient.post('/applications/%s/enable_enforce' % application_id,
                         json_body=json.dumps(req_payload))

Disable enforcement on the workspace.

POST /openapi/v1/applications/{application_id}/disable_enforce

Warning

New host firewall rules will be inserted and any existing rules will be deleted on the relevant hosts.

Parameters: The request URL contains the following parameters

Response object: Returns an object with the following attributes:

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  resp = restclient.post('/applications/%s/disable_enforce' %
                         application_id)

Automatically discover policies for the workspace. (Formerly known as “submitting an ADM run”).

POST /openapi/v1/applications/{application_id}/submit_run

Parameters: The request URL contains the following parameters

Parameters: The JSON query body contains the following keys

Note	Unspecified optional parameter default values will be taken from the previous automatic policy discovery run config if automatic policy discovery was performed earlier in the workspace or else the default values will be taken from the Default Policy Discovery Config.

Response object: Returns an object with the following attributes:

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  req_payload = {
        'start_time': '2020-09-17T10:00:00-0700',
        'end_time': '2020-09-17T11:00:00-0700',
        # Optional Parameters.
        'clustering_granularity': 'FINE',
        'port_generalization': 'AGGRESSIVE',
        'policy_compression': 'AGGRESSIVE',
        'auto_accept_policy_connectors': False,
        'enable_exclusion_filter': True,
        'enable_default_exclusion_filter': True,
        'enable_service_discovery': True,
        'carry_over_policies': True,
        'skip_clustering': False,
        'deep_policy_generation': True,
        'use_default_config': False
  }
  resp = restclient.post('/applications/%s/submit_run' % application_id,
                         json_body=json.dumps(req_payload))

Query the status of an automatic policy discovery run in the workspace.

GET /openapi/v1/applications/{application_id}/adm_run_status

Parameters: The request URL contains the following parameters

Response object: Returns an object with the following attributes:

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  resp = restclient.get('/applications/%s/adm_run_status' % application_id)

The policy object attributes are described below:

L4Params object attributes:

This endpoint returns a list of policies in a particular workspace. This API is available to API keys with app_policy_management capability.

GET /openapi/v1/applications/{application_id}/policies

Parameters: The request URL contains the following parameters

Policy IDs can change from version to version. To obtain the list of policies from a published version, the version number should be prefixed with a 'p'. For example, to fetch all the policies in published version 3 we can perform a request such as:

GET /openapi/v1/applications/{application_id}/policies?version=p3

Returns an object of all policies in this particular workspace as shown below

    {
      absolute_policies: [ ... ],
      default_policies: [ ... ],
      catch_all_action:
    }

Sample Python code

  application_id = '5f88c996755f023f3bafe163'
  restclient.get('/applications/%s/policies' % application_id, params={'version': '1'})

  application_id = '5f88c996755f023f3bafe163'
  restclient.get('/applications/%s/default_policies' % application_id, params={'version': '1', 'limit': 3, 'offset': 3})

    {
      "results": [
      PolicyObject4,
      PolicyObject5,
      PolicyObject6
      ],
      "offset": 6
    }

  application_id = '5f88c996755f023f3bafe163'
  restclient.get('/applications/%s/absolute_policies' % application_id, params={'version': '1', 'limit': 3})

    {
      "results": [
      PolicyObject1,
      PolicyObject2,
      PolicyObject3
      ],
      "offset": 3
    }

  application_id = '5f88c996755f023f3bafe163'
  restclient.get('/applications/%s/catch_all' % application_id, params={'version': '1'})

This endpoint returns an instance of a policy.

GET /openapi/v1/policies/{policy_id}

Returns the policy object associated with the specified ID.

Sample Python code

  policy_id = '5f88ca1e755f0222f85ce85c'
  restclient.get('/policies/%s' % policy_id)

This endpoint searches for the specified policy using Policy Identifier Parameters as a composite key.

POST /openapi/v1/policies/search

The query body consists of a JSON body with the following schema:

The policy identifier fields are made up using the following schema:

Sample Python code

  application_id = '5f88ca1e755f0222f85ce85c'
  consumer_id = '5f88ca1e755f0222f85ce85d'
  provider_id = '5f88ca1e755f0222f85ce85d'
  rank = 'DEFAULT'
  action = 'ALLOW'
  priority = 100
  protocol = 6
  start_port = 80
  version = 'p3'

  req_body = f'''
  {{
      "application_id": "{application_id}",
      "policy_identifier": {{
          "consumer_consistent_uuid": "{consumer_id}",
          "provider_consistent_uuid": "{provider_id}",
          "rank": "{rank}",
          "action": "{action}",
          "priority": {priority},
          "protocol": "{protocol}",
          "start_port": "{start_port}",
          "version": "{version}"
      }}
  }}'''
  restclient.post('/policies/search', json_body=req_body)

This endpoint is used to create new policies.

POST /openapi/v1/applications/{application_id}/policies

Parameters:

Sample Python code

  req_payload = {
    "version": "v1",
    "rank" : "DEFAULT",
    "policy_action" : "ALLOW",
    "priority" : 100,
    "consumer_filter_id" : "123456789",
    "provider_filter_id" : "987654321",
  }
  resp = restclient.post('/openapi/v1/applications/{application_id}/policies', json_body=json.dumps(req_payload))

This endpoint updates a policy.

PUT /openapi/v1/policies/{policy_id}

Parameters:

Returns the modified policy object associated with specified ID.

This endpoint is used to create service ports for a specific policy.

POST /openapi/v1/policies/{policy_id}/l4_params

Parameters:

This endpoint updates the specified service port of a Policy.

PUT /openapi/v1/policies/{policy_id}/l4_params/{l4_params_id}

Parameters:

This endpoint deletes the specified service port of a policy. (Optional) See Exclusion Filters for more details.

DELETE /openapi/v1/policies/{policy_id}/l4_params/{l4_params_id}

Parameters:

This endpoint deletes the specified Policy. No exclusion filters are created.

DELETE /openapi/v1/policies/{policy_id}

This endpoint deletes the specified policy using Policy Identifier Parameters. No exclusion filters are created.

DELETE /openapi/v1/policies/destroy_with_identifier

The query body consists of a JSON body with the following schema:

The policy identifier fields are made up using the following schema:

Sample Python code

  application_id = '5f88ca1e755f0222f85ce85c'
  consumer_id = '5f88ca1e755f0222f85ce85d'
  provider_id = '5f88ca1e755f0222f85ce85d'
  action = 'ALLOW'
  rank = 'DEFAULT'
  protocol = 6
  start_port = 80
  priority = 100
  version = '5'

  req_body = f'''
  {{
      "application_id": "{application_id}",
      "policy_identifier": {{
          "consumer_consistent_uuid": "{consumer_id}",
          "provider_consistent_uuid": "{provider_id}",
          "rank": "{rank}",
          "priority": {priority},
          "action": "{action}",
          "protocol": "{protocol}",
          "start_port": "{start_port}",
          "version": "{version}"
      }}
  }}'''
  restclient.delete('/policies/destroy_with_identifier', json_body=req_body)

This endpoint can be used to find matching set of policies for any hypothetical flow against the analyzed/enforced polices in a root scope. For more details refer Quick Analysis

This API is only available to users with a minimum read access to root scope and requires app_policy_management capability associated with the API key.

POST /openapi/v1/policies/{rootScopeID}/quick_analysis

The query body consists of a JSON body with the following schema:

Sample request

The body of the request should be a JSON formatted query.

An example of a query body where the flow decision is based on all analyzed polices:

    req_payload = {
        "consumer_ip": "4.4.1.1",
        "provider_ip": "4.4.2.1",
        "provider_port": 9081,
        "protocol": "TCP",
        "analysis_type": "analyzed"
    }
    resp = restclient.post('/openapi/v1/policies/{rootScopeID}/quick_analysis', json_body=json.dumps(req_payload))

An example of a query body where the flow decision is based on the policies from the workspace's ‘v’ version along with the analyzed polices from all other workspaces in the root scope:

    req_payload = {
        "consumer_ip": "4.4.1.1",
        "provider_ip": "4.4.2.1",
        "provider_port": 9081,
        "protocol": "TCP",
        "analysis_type": "analyzed",
        "application_id": "5e7e5f56497d4f0bc26c7bb3",
        "version": 1
    }
    resp = restclient.post('/openapi/v1/policies/{rootScopeID}/quick_analysis', json_body=json.dumps(req_payload))

Sample response

The response is a JSON object in the body with the following properties:

    {
        "policy_decision": "ALLOW",
        "outbound_policy": {
            "policy_rank": "DEFAULT",
            "start_port": 9082,
            "l4_detail_id": "5e7e600f497d4f7341f4f6d0",
            "src_filter_id": "5e7e600e497d4f7341f4f459",
            "end_port": 9082,
            "cluster_edge_id": "5e7e600f497d4f7341f4f6d1",
            "dst_filter_id": "5e7d0efc497d4f44b6b09351",
            "action": "ALLOW",
            "protocol": "TCP",
            "app_scope_id": "5e7e5f3a497d4f0bc26c7bb0"
        },
        "inbound_policy": {
            "policy_rank": "DEFAULT",
            "start_port": 9082,
            "l4_detail_id": "5e7e600f497d4f7341f4f6d0",
            "src_filter_id": "5e7e600e497d4f7341f4f459",
            "end_port": 9082,
            "cluster_edge_id": "5e7e600f497d4f7341f4f6d1",
            "dst_filter_id": "5e7d0efc497d4f44b6b09351",
            "action": "ALLOW",
            "protocol": "TCP",
            "app_scope_id": "5e7e5f3a497d4f0bc26c7bb0"
        }
    }

This endpoint returns the number of packets, bytes and conversations observed for a policy over a time interval. A conversation can be broadly described as a flow observation matching a policy that is aggregated with a granularity of one hour. The number of conversations measured for a given policy within one hour represents the number of distinct pairs of consumer and provider inventory items that have communicated over the network during that one hour.

Although this endpoint accepts Policy Identifier Parameters as input, it is strongly recommended to use policy and L4 parameter IDs from an published version of the workspace.

Note	After a new version of the application workspace is published, it can take up to 6 hours before results become available. All the timestamp resolutions will also have a minimum granularity of 6 hours.

To get the policy statistics for a policy across enforced versions of an application workspace the URL path is:

POST /openapi/v1/policies/stats/enforced

To get the policy statistics for a policy across analyzed versions of an application workspace the URL path is:

POST /openapi/v1/policies/stats/analyzed

The query body consists of a JSON body with the following schema:

The policy identifier fields are made up using the following schema:

Sample Python code

  application_id = '5f88ca1e755f0222f85ce85c'
  consumer_id = '5f88ca1e755f0222f85ce85d'
  provider_id = '5f88ca1e755f0222f85ce85d'
  action = 'ALLOW'
  rank = 'DEFAULT'
  protocol = 6
  start_port = 80
  priority = 100

  req_body = f'''
  {{
      "application_id": "{application_id}",
      "t0":"2022-07-06T00:00:00Z",
      "t1":"2022-07-28T19:00:00Z",
      "policy_identifier": {{
          "consumer_consistent_uuid": "{consumer_id}",
          "provider_consistent_uuid": "{provider_id}",
          "rank": "{rank}",
          "priority": {priority},
          "action": "{action}",
          "protocol": "{protocol}",
          "start_port": "{start_port}"
      }}
  }}'''
  restclient.post('/policies/stats/analyzed', json_body=req_body)

  # For CATCH_ALL policies:
  root_app_scope_id = '6f88ca1e755f0222f85ce85e'
  rank = 'CATCH_ALL'
  action = 'DENY'
  req_body = f'''
  {{
      "application_id": "{application_id}",
      "t0":"2022-07-06T00:00:00Z",
      "t1":"2022-07-28T19:00:00Z",
      "policy_identifier": {{
          "consumer_consistent_uuid": "{root_app_scope_id}",
          "provider_consistent_uuid": "{root_app_scope_id}",
          "rank": "{rank}",
          "action": "{action}"
      }}
  }}'''

  restclient.post('/policies/stats/analyzed', json_body=req_body)

Sample response

The response is a JSON object in the body with the following properties.

    {
      "conversation_count": 72,
      "packet_count": 800,
      "byte_count": 1960,
      "first_seen_at": "2022-09-09T11:00:00.000Z",
      "last_seen_at": "2022-09-09T11:00:00.000Z",
      "agg_start_version": 4,
      "agg_start_time": "2022-08-10T23:00:00.000Z"
    }

This endpoint returns the policy identifiers in an published workspace for which no conversations are observed over a specified time interval.

Policy Identifier

All policies and ADM-generated clusters can change their IDs across application workspace versions even if the underlying filter queries or policy port and protocol do not change. In order to keep track of flow hit counts for a particular policy across workspace versions we use consistent UUIDs for the filters that do not change across versions and a composite key called the policy identifier comprising the provider and consumer consistent UUIDs along with rank, action, priority, port and protocol.

Thus, policy identifiers serve as a composite key that can both identify and describe the important aspects of a policy across application workspace versions, whereas policy IDs (such as those used in the regular CRUD endpoints) can change across versions of the workspace.

Note	Provider/Consumer consistent UUIDs and policy identifiers do not uniquely identify a filter or policy as they are shared across different application workspace versions.

To perform CRUD operations on a particular cluster or policy it is recommended to resolve the identifier to a concrete policy for a specific application workspace version the search endpoint.

Regular CRUD operations can be performed using policy IDs whereas only Policy Statistics and Destroy With Identifier accept the policy identifier as input. This is mainly for convenience to avoid the intermediate call to search, and instead directly validate and destroy all unused policies in a workspace.

It is strongly recommended that policy and filter IDs are used wherever possible and to not manually generate policy identifiers for the Policy Statistics or Destroy With Identifier API endpoints. However, the following example illustrates one way of generating policy identifiers from the policy object:

    resp = restclient.get(f'/policies/631b0590497d4f09b537b973')
    policy = resp.json() # policy object
    policy_identifer = {
        'consumer_consistent_uuid': policy['consumer_filter']['consistent_uuid'],
        'provider_consistent_uuid': policy['provider_filter']['consistent_uuid'],
        'rank': policy['rank'],
        'action': policy['action'],
        'priority': policy['priority'],
        'protocol': policy['l4_params'][0]['proto'],
        'start_port': policy['l4_params'][0]['port'][0],
        'end_port': policy['l4_params'][0]['port'][1]
    }

Note	After a new version of the application workspace is published it can take up to 6 hours before results become available. All the timestamp resolutions will also have a minimum granularity of 6 hours.

To get the unused policies across enforced versions of an application workspace the URL path is:

POST /openapi/v1/unused_policies/{application_id}/enforced

To get the unused policies across analyzed versions of an application workspace the URL path is:

POST /openapi/v1/unused_policies/{application_id}/analyzed

The query body consists of a JSON body with the following schema:

    application_id = '62e1915e755f026f2bcdd805'
    resp = restclient.post(f'/unused_policies/{application_id}/analyzed', json_body=f'''
    {{
        "t0":"2022-07-06T00:00:00Z",
        "t1":"2022-07-28T19:00:00Z"
    }}''')'

Sample response

The response is a JSON object in the body with the following properties.

To generate the next page of results, take the object received by the response in offset and pass it as the value for the offset of the next query.

    {
      "application_id": "63054a97497d4f2dc113a9c4",
      "policy_identifiers": [
        {
          "consumer_consistent_uuid": "62fff45c497d4f5064973c4d",
          "provider_consistent_uuid": "62fff45c497d4f5064973c4d",
          "version": "p1",
          "rank": "DEFAULT",
          "policy_action": "ALLOW",
          "priority": 10,
          "proto": 6,
          "start_port": 10000,
          "end_port": 10000,
          "agg_start_version": 1,
          "agg_start_time": "2022-08-10T23:00:00.000Z"
        },
        {
          "consumer_consistent_uuid": "62fff45c497d4f5064973c4d",
          "provider_consistent_uuid": "62fff45c497d4f5064973c4d",
          "version": "p1",
          "rank": "DEFAULT",
          "policy_action": "ALLOW",
          "priority": 10,
          "protocol": 6,
          "start_port": 10001,
          "end_port": 10001,
          "agg_start_version": 1,
          "agg_start_time": "2022-08-10T23:00:00.000Z"
        }
      ],
      "offset": "eyJvZmZzZXQiOjZ9"
    }

This endpoint returns a list of policy templates for a particular root scope. This API is available to API keys with app_policy_management capability.

GET /openapi/v1/application_templates?root_app_scope_id={root_app_scope_id}

Parameters: The request URL contains the following parameters

Response object: Returns a list of policy template objects for the specified root scope.

Sample python code

  root_app_scope_id = '<root-app-scope-id>'
  restclient.get('/application_templates?root_app_scope_id=%s' % root_app_scope_id)

This endpoint returns an instance of policy templates.

GET /openapi/v1/application_templates/{template_id}

Parameters: The request URL contains the following parameters

Response object: Returns the policy template object with the specified ID.

Sample python code

  template_id = '<template-id>'
  restclient.get('/application_templates/%s' % template_id)

This endpoint is used to create a new policy template.

POST /openapi/v1/application_templates

The JSON request body contains the following keys

Response object: Returns the created policy template object.

Sample python code

  root_app_scope_id = '<root-app-scope-id>'
  payload = {'root_app_scope_id': root_app_scope_id,
             'name': "policy_name",
             'default_policies': [
                {
                  'action': 'ALLOW',
                  'priority': 100,
                  'l4_params': [
                    {
                      'proto': 17,
                      'port': [80, 90]
                    }
                  ]
                }
              ]
            }
  restclient.post('/application_templates',
                  json_body=json.dumps(payload))

This endpoint updates a policy template.

PUT /openapi/v1/application_templates/{template_id}

Parameters: The request URL contains the following parameters

The JSON request body contains the following keys

Response object: Returns the modified policy template object with the specified ID.

Sample python code

  new_name = <new-name>
  payload = {'name': new_name}
  template_id = '<template-id>'
  restclient.post('/application_templates/%s' % template_id,
                  json_body=json.dumps(payload))

This endpoint deletes the specified policy template.

DELETE /openapi/v1/application_templates/{template_id}

Parameters: The request URL contains the following parameters

Response object: None

Sample python code

  template_id = '<template-id>'
  restclient.delete('/application_templates/%s' % template_id)

This endpoint downloads a policy template.

GET /openapi/v1/application_templates/{template_id}/download

Parameters: The request URL contains the following parameters

Response object: Returns the full policy template definition with the specified ID.

Sample python code

  template_id = '<template-id>'
  restclient.get('/application_templates/%s/download' % template_id)

The cluster object attributes are described below:

This endpoint returns a list of clusters for a particular workspace (“application”). This API is available to API keys with app_policy_management capability.

GET /openapi/v1/applications/{application_id}/clusters

Parameters: The request URL contains the following parameters

Response object: Returns an array of all clusters for this particular workspace and version.

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  restclient.get('/applications/%s/clusters' % application_id)

This endpoint returns an instance of a cluster.

GET /openapi/v1/clusters/{cluster_id}

Parameters: The request URL contains the following parameters

Response object: Returns the cluster object associated for the specified ID.

Sample python code

  cluster_id = '5d02d021497d4f0949ba74e4'
  restclient.get('/clusters/%s' % cluster_id)

This endpoint is used to create a new cluster.

POST /openapi/v1/applications/{application_id}/clusters

Parameters: The request URL contains the following parameters

The JSON query body contains the following keys

Nodes object attributes:

Note	The nodes will be used to create a query unless a query is provided and the workspace is in Dynamic Mode.

Response object: Returns the newly created cluster object.

Sample python code

  application_id = '5d02b493755f0237a3d6e078'
  payload = {
    'name': 'test_cluster',
    'version': 'v2',
    'description': 'basic granularity',
    'approved': False,
    'query': {
        'type': 'eq',
        'field': 'host_name',
        'value': 'centos6001'
    }
  }
  restclient.post('/applications/%s/clusters' % application_id)

This endpoint updates a cluster.

PUT /openapi/v1/clusters/{cluster_id}

Parameters: The request URL contains the following parameters

The JSON query body contains the following keys

Response object: Returns the modified cluster object associated with specified ID.

Sample python code

  cluster_id = '5d02d2a4497d4f5194f104ef'
  payload = {
    'name': 'new_test_cluster',
  }
  restclient.put('/clusters/%s' % cluster_id, json_body=json.dumps(payload))

This endpoint deletes the specified Cluster. If the cluster is used by any policies the cluster will not be deleted and a list of dependents will be returned.

DELETE /openapi/v1/clusters/{cluster_id}

Parameters: The request URL contains the following parameters

Response object: None

Sample python code

  cluster_id = '5d02d2a4497d4f5194f104ef'
  restclient.delete('/clusters/%s' % cluster_id)

This end point enables you to search the conversations in an automatic policy discovery run for a given workspace. You can also specify a subset of supported dimensions and metrics which you may want to see as part of the downloaded conversations. Optionally, you can query for a subset of conversations using filters on supported dimensions and metrics.

POST /openapi/v1/conversations/{application_id}

The query consists of a JSON body with the following keys.

The body of the request should be a JSON formatted query. An example of a query body is shown below.

    {
        "version": 1,
        "filter": {
            "type": "and",
            "filters":[
                {
                    "type": "eq",
                    "field": "excluded",
                    "value": False
                },
                {
                    "type": "eq",
                    "field": "protocol",
                    "value": "TCP"
                },
            ]
        },
        "dimensions": ["src_ip", "dst_ip", "port"],
        "metrics": ["byte_count", "packet_count"],
        "limit" : 2,
        "offset": <offset-object>
    }

   req_payload = {"version": 1,
                  "limit": 10,
                  "filter": {"type": "and",
                      "filters": [
                          {"type": "eq", "field": "excluded", "value": False},
                          {"type": "eq", "field": "protocol", "value": "TCP"}
                       ]
                  }
    }

    resp = restclient.post('/conversations/{application_id}', json_body=json.dumps(req_payload))
    print resp.status_code
    if resp.status_code == 200:
        parsed_resp = json.loads(resp.content)
        print json.dumps(parsed_resp, indent=4, sort_keys=True)

This end point enables you to search the top conversations for an automatic policy discovery run for a given workspace based on a metric and grouped by a dimension. The current supported metrics are here and the current supported group by dimensions are here you can query for a subset of conversations using filters on supported dimensions and metrics. For example, you can search for the source IP address with the most byte traffic conversations using a query with the src_ip dimension with the byte_count metric.

POST /openapi/v1/conversations/{application_id}/topn

The query consists of a JSON body with the following keys.

The body of the request should be a JSON formatted query. An example of a query body is shown below.

    {
        "version": 1,
        "dimension": "src_ip",
        "metric": "byte_count",
        "filter": {
            "type": "and",
            "filters":[
                {
                    "type": "eq",
                    "field": "excluded",
                    "value": False
                },
                {
                    "type": "eq",
                    "field": "protocol",
                    "value": "TCP"
                },
            ]
        },
        "threshold" : 10
    }

  [ {"result": [
    {
      "byte_count": 1795195565,
      "src_ip": "192.168.1.6"
    },
    {
      "byte_count": 1781002379,
      "src_ip": "192.168.1.28"
    },
    ...
  ] } ]

    req_payload = {"version": 1, "dimension": "src_ip", "metric": "byte_count",
      "filter": {"type": "and",
        "filters": [
          {"type": "eq", "field": "excluded", "value": False},
          {"type": "eq", "field": "protocol", "value": "TCP"},
          {"type": "eq", "field": "consumer_filter_id", "value": "16b12a5614c5af5b68afa7ce"},
          {"type": "subnet", "field": "src_ip", "value": "192.168.1.0/24"}
        ]
      },
      "threshold" : 10
    }

    resp = restclient.post('/conversations/{application_id}/topn', json_body=json.dumps(req_payload))
    print resp.status_code
    if resp.status_code == 200:
        parsed_resp = json.loads(resp.content)
        print json.dumps(parsed_resp, indent=4, sort_keys=True)

The exclusion filter object attributes are described below:

This endpoint returns a list of exclusion filters for a particular workspace. This API is available to API keys with app_policy_management capability.

GET /openapi/v1/applications/{application_id}/exclusion_filters

Parameters: The request URL contains the following parameters

Response object: Returns a list of exclusion filter objects for the specified workspace and version.

Sample python code

  application_id = '<application-id>'
  params = {'version': 'v10'}
  restclient.get('/applications/%s/exclusion_filters' % application_id,
                 params=params)

This endpoint returns an instance of an exclusion filters.

GET /openapi/v1/exclusion_filters/{exclusion_filter_id}

Parameters: The request URL contains the following parameters

Response object: Returns the exclusion filter object with the specified ID.

Sample python code

  exclusion_filter_id = '<exclusion-filter-id>'
  restclient.get('/exclusion_filters/%s' % exclusion_filter_id)

This endpoint is used to create a new exclusion filter.

POST /openapi/v1/applications/{application_id}/exclusion_filters

Parameters: The request URL contains the following parameters

The JSON request body contains the following keys

Missing optional parameters will be considered as wildcards (match any).

Response object: Returns the created exclusion filter object.

Sample python code

  provider_filter_id = '<provider-filter-id>'
  consumer_filter_id = '<consumer-filter-id>'
  payload = {'version': 'v0',
             'consumer_filter_id': consumer_filter_id,
             'provider_filter_id': provider_filter_id,
             'proto': 6,
             'start_port': 800,
             'end_port': 1000}
  application_id = '<application-id>'
  restclient.post('/applications/%s/exclusion_filters' % application_id,
                  json_body=json.dumps(payload))

This endpoint updates an exclusion filter.

PUT /openapi/v1/exclusion_filters/{exclusion_filter_id}

Parameters: The request URL contains the following parameters

The JSON request body contains the following keys

Response object: Returns the modified exclusion filter object with the specified ID.

Sample python code

  payload = {'proto': 17}
  exclusion_filter_id = '<exclusion-filter-id>'
  restclient.post('/exclusion_filters/%s' % exclusion_filter_id,
                  json_body=json.dumps(payload))

This endpoint deletes the specified exclusion filter.

DELETE /openapi/v1/exclusion_filters/{exclusion_filter_id}

Parameters: The request URL contains the following parameters

Response object: None

Sample python code

  exclusion_filter_id = '<exclusion-filter-id>'
  restclient.delete('/exclusion_filters/%s' % exclusion_filter_id)

The exclusion filter object attributes are described below:

This endpoint returns a list of default exclusion filters. This API is available to API keys with app_policy_management capability.

GET /openapi/v1/default_exclusion_filters?root_app_scope_id={root_app_scope_id}

Parameters: The request URL contains the following parameters

Response object: Returns a list of default exclusion filter objects for the root scope.

Sample python code

 root_app_scope_id = '<root-app-scope-id>'
  restclient.get('/default_exclusion_filters?root_app_scope_id=%s' % root_app_scope_id)

This endpoint returns an instance of a default exclusion filters.

default_exclusion_filter_id = '<default-exclusion-filter-id>'

restclient.get('/default_exclusion_filters/%s' % default_exclusion_filter_id)

Parameters: The request URL contains the following parameters

Response object: Returns the default exclusion filter object with the specified ID.

Sample python code

  default_exclusion_filter_id = '<default-exclusion-filter-id>'
  restclient.get('/default_exclusion_filters/%s' % default_exclusion_filter_id)

This endpoint is used to create a new default exclusion filter.

POST /openapi/v1/default_exclusion_filters?root_app_scope_id={root_app_scope_id}

Parameters: The request URL contains the following parameters

The JSON request body contains the following keys

Response object: Returns the created default exclusion filter object.

Sample python code

  provider_filter_id = '<provider-filter-id>'
  consumer_filter_id = '<consumer-filter-id>'
  payload = {'consumer_filter_id': consumer_filter_id,
             'provider_filter_id': provider_filter_id,
             'proto': 6,
             'start_port': 800,
             'end_port': 1000}
  root_app_scope_id = '<root-app-scope-id>'
  restclient.post('/default_exclusion_filters?root_app_scope_id=%s' % root_app_scope_id,
                  json_body=json.dumps(payload))

This endpoint updates a default exclusion filter.

PUT /openapi/v1/default_exclusion_filters/{default_exclusion_filter_id}

Parameters: The request URL contains the following parameters

The JSON request body contains the following keys

Response object: Returns the modified default exclusion filter object with the specified ID.

Sample python code

  payload = {'proto': 17}
  default_exclusion_filter_id = '<default-exclusion-filter-id>'
  restclient.post('/default_exclusion_filters/%s' % default_exclusion_filter_id,
                  json_body=json.dumps(payload))

This endpoint deletes the specified default exclusion filter.

DELETE /openapi/v1/default_exclusion_filters/{default_exclusion_filter_id}

Parameters: The request URL contains the following parameters

Response object: None

Sample python code

  default_exclusion_filter_id = '<default-exclusion-filter-id>'
  restclient.delete('/default_exclusion_filters/%s' % default_exclusion_filter_id)

This endpoint is useful to know the columns on which search criteria (or filters) can be specified for downloading flows available via Live Analysis. Most common use case would be to download permitted, escaped or rejected flows this can be achieved by passing a search criteria on category dimension to the download API. When used with type: eq the flow’s inbound and outbound category must match. When used with type: contains the flows inbound or outbound category must match

GET /openapi/v1/live_analysis/dimensions

This endpoint returns the list of metrics (e.g. byte count, packet count) associated with live analysis. One use case for this endpoint would be to project a subset of metrics in the download API, i.e. instead of downloading all the metrics, users can specify a small subset of metrics they are interested in.

GET /openapi/v1/live_analysis/metrics

This endpoint returns the list of flows matching the filter criteria. Each flow object in the result has attributes that are a union of live analysis dimensions (returned by the live analysis dimensions API above) as well as the live analysis metrics (returned by the live analysis metrics API above). Optionally, user can also specify a small subset of dimensions or metrics if they are not interested in the full set of available dimensions and metrics – this projection of a smaller subset of dimensions or metrics also have the side effect of making API calls fast.

POST /openapi/v1/live_analysis/{application_id}

The query body consists of a JSON body with the following keys.

The body of the request should be a JSON formatted query. An example of a query body is shown below.

  
    {
        "t0": "2016-06-17T09:00:00-0700",
        "t1": "2016-06-17T17:00:00-0700",
        "filter": {
            "type": "and",
            "filters": [
                {
                    "type": "contains",
                    "field": "category",
                    "value": "escaped"
                },
                {
                    "type": "in",
                    "field": "dst_port",
                    "values": ["80", "443"]
                }
            ]
        },
        "limit": 100,
        "offset": <offset-object>
    }

   req_payload = {"t0": "2016-11-07T09:00:00-0700",
                  "t1": "2016-11-07T19:00:00-0700",
                  "limit": 10,
                  "filter": {"type": "and",
                      "filters": [
                          {"type": "contains", "field": "category", "value": "escaped"},
                          {"type": "regex", "field": "src_hostname", "value": "web*"}
                       ]
                  }
    }

    resp = restclient.post('/live_analysis/{application_id}', json_body=json.dumps(req_payload))
    print resp.status_code
    if resp.status_code == 200:
        parsed_resp = json.loads(resp.content)
        print json.dumps(parsed_resp, indent=4, sort_keys=True)

The filter supports primitive filters and logical filters (“not”, “and”, “or”) comprised of one or more primitive filters. Format of primitive filter is as follows:

    {"type" : "<OPERATOR>", "field": "<COLUMN_NAME>", "value": "<COLUMN_VALUE>"}

For primitive filters, operator can be a comparison operator like eq, ne, lt, lte, gt or gte. Operator could also be in, regex, subnet, contains or range.

Some examples of primitive filters might include:

   {"type": "eq", "field": "src_address", "value": "7.7.7.7"}

   {"type": "regex", "field": "src_hostname", "value": "prod.*"}

   {"type": "subnet", "field": "src_addr", "value": "1.1.11.0/24"}

   # Note, 'in' clause uses 'values' key instead of 'value'
   {"type": "in", "field": "src_port", "values": [80, 443]}

You can also specify complex filters using boolean operations like not, and or or. Following are some examples of these type of filters:

    # "and" and "or" operators need to specify list of "filters"
    {"type": "and",
        "filters": [
            {"type": "in", "field": "src_port", "values": [80, 443]},
            {"type": "regex", "field": "src_hostname", "value": "prod.*"}
        ]
    }

    # "not" operator needs to specify a "filter"
    {"type": "not",
        "filter": {"type": "subnet", "field": "src_addr", "value": "1.1.11.0/24"}
    }

More formally, schema of filter in the flow search request is as follows:

eq, ne—Searches flows for equality or inequality respectively in column specified by "field" with value specified by "value". Supports the following fields: src_hostname, dst_hostname, src_address, dst_address, src_port, dst_port, src_scope_name, dst_scope_name, vrf_name, src_enforcement_epg_name, dst_enforcement_epg_name, proto. These operators also work on user labelled columns.

lt, lte, gt, gte—Searches flows where values of column specified by "field" are less than, less than equal to, greater than or greater than equal to (as applicable) the value specified by "value". Supports the following fields: [src_port, dst_port].

range—Searches flows for values of column specified by "field" between range start and range end specified by "values" list (this list must be of size 2 for “range” filter type – first value is the range start and second is the range end). Supports the following fields: [src_port, dst_port].

in—Searches flows for membership in column specified by "field" with membership list specified by "values". Supports the following fields: src_hostname, dst_hostname, src_address, dst_address, src_port, dst_port, src_scope_name, dst_scope_name, vrf_name, src_enforcement_epg_name, dst_enforcement_epg_name, proto. This operator also works on user labelled columns.

regex, contains—Searches flows for regex matches or containment matches respectively in col- umn specified by "field" with regex specified by "value". Supports the following fields: src_hostname, dst_hostname, src_scope_name, dst_scope_name, vrf_name, src_enforcement_epg_name, dst_enforcement_epg_name. These operators also work on user labelled columns. Filters with regex type must use Java style regex patterns as "value".

subnet—Searches flows for subnet membership specified by "field" as a string in CIDR notation. Supports the following fields: ["src_address", "dst_address"]

• not—Logical "not" filter of object specified by "filter".

• and—Logical "and" filter of list of filter objects specified by "filters".

• or—Logical "or" filter of list of filter objects specified by "filters".

Response object:

To generate the next page of results, take the object received by the response in offset and pass it as the value for the offset of the next query.

Sample python code

   req_payload = {"t0": "2016-11-07T09:00:00-0700",
                  "t1": "2016-11-07T19:00:00-0700",
                  "scopeName": "Default:Prod:Web",
                  "limit": 10,
                  "filter": {"type": "and",
                      "filters": [
                          {"type": "subnet", "field": "src_address", "value": "1.1.11.0/24"},
                          {"type": "regex", "field": "src_hostname", "value": "web*"}
                       ]
                  }
    }

    resp = restclient.post('/flowsearch', json_body=json.dumps(req_payload))
    print resp.status_code
    if resp.status_code == 200:
        parsed_resp = json.loads(resp.content)
        print json.dumps(parsed_resp, indent=4, sort_keys=True)