Initial Usage Instructions

Within your favourite Python IDE environment, create an import reference

from pyclearpass import *

Create a object to login into ClearPass. The login object needs to be passed to use any function within the ClearPass API.
Three examples below shows how to create the login object (either one can be used, but not all) Option 3 is preferred.

1. Using client credentials

login = ClearPassAPILogin(server="https://yourserver.network.local:443/api",granttype="client_credentials",
clientsecret="myclientsecretexample", clientid="myclientidexample", verify_ssl=False)

📘

The login object will contain the APIToken once any function has been used. It obtains it once for the session and uses the same token through the execution of the rest of the script. You can extract this token and reuse it for other sessions if required (login.api_token). The token will only be available for reuse until the lifetime expires which was configured when specifying a new API Client within the ClearPass Guest Module.

2. Using an explicitly defined api_token. You can generate an API token by clicking on the API client and then clicking 'Generate Access Token'.

login = ClearPassAPILogin(server="https://yourserver.network.local:443/api",api_token="yoursecretapitoken", verify_ssl=False)

3. Using the api token located in a file. You can generate an API token by clicking on the API client and then clicking 'Generate Access Token'. The Token file is expected in the following format and is expected to exist in the script execution folder. This is the preferred method to avoid having your credentials directly exposed in your script file.

{"access_token":"your_token_here"}

The python file is expected in the following format with teh file name for the token called "token.json".

token = Utils.get_token_from_file("token.json")
login = ClearPassAPILogin(server="https://yourserver.network.local:443/api",api_token=token, verify_ssl=False)

Find an API you want to use, by prefixing Api in your IDE and Intellisense will show the available APIs available. Each of the top level API category names are available as a module. Once you have chosen a specific API module to use, for example ApiPolicyElements, it will show you the available methods if you suffix a . to the command - ApiPolicyElements.

The example below prints a single the roles available within the ClearPass server.

print(ApiPolicyElements.get_role(login)) 

By default, the example above returns the first 25 roles. To view more, the limit needs to be adjusted. Placing your cursor over the .getRole will usually show you help about the method.

print(ApiPolicyElements.get_role(login, limit=100))

Help

Once you have written a specific API ApiName.FunctionName(, placing your cursor over the command will show you help for the function and what the required parameters are (example is Visual Studio Code). The first parameter is always login.
You may also read the help for the function by calling help(ApiName.function_name).
Each function contains a help section on how to use it.

Python Package Upgrade Instructions

Once an update is available on the Python PyPi repository, you may upgrade your release by completing the following in a command line terminal -

pip3 install pyclearpass --upgrade
or
pip install pyclearpass --upgrade

To install a specific version, execute the following command with x.x.x being the specific version number you want to install.

pip3 install pyclearpass==x.x.x
or
pip install pyclearpass==x.x.x

Uninstall Package Package

To remove the Python pyclearpass package, type the following command into a command line terminal -
pip3 uninstall pyclearpass
or
pip uninstall pyclearpass

Further Usage Examples

The examples below all exclude importing the module and creating the login variable. This is described directly below. Note, these are just a full examples, there are hundreds of API commands available within the SDK.

Login

Mandatory Login Session Parameters

The login variable only needs to be defined once in the script. Three examples are shown below to achieve this;

1. Using client_credentials

from pyclearpass import *
login = ClearPassAPILogin(server="https://yourserver.network.local:443/api",granttype="client_credentials",
clientsecret="myclientsecretexample", clientid="myclientidexample", verify_ssl=False)

📘

As mentioned earlier, the login object will contain the API Token once any function has been used. It obtains it once for the session and uses the same token through the execution of the rest of the script. You can extract this token and reuse it for other sessions if required (login.api_token). The token will only be available for reuse until the lifetime expires which was configured when specifying a new API Client within the ClearPass Guest Module.

2. Using an explicitly defined api_token. You can generate an API token by clicking on the API client and then clicking 'Generate Access Token'.

from pyclearpass import *
login = ClearPassAPILogin(server="https://yourserver.network.local:443/api",api_token="yoursecretapitoken", verify_ssl=False)

3. Using the api token located in a file. You can generate an API token by clicking on the API client and then clicking 'Generate Access Token'. The Token file is expected in the following format and is expected to exist in the script execution folder. This is the preferred method to avoid having your credentials directly exposed in your script file.

{"access_token":"your_token_here"}

The python file is expected in the following format

token = Utils.get_token_from_file("token.json")
login = ClearPassAPILogin(server="https://yourserver.network.local:443/api",api_token=token, verify_ssl=False)

Optional Login Session Parameters

You can also include a timeout on the within the login object to define how long the web request should try before timing out. An example is provided below of 10 seconds

token = Utils.get_token_from_file("token.json")
login = ClearPassAPILogin(server="https://yourserver.network.local:443/api",api_token=token, verify_ssl=False,timeout=10)

2. Using an explicitly defined api_token. You can generate an API token by clicking on the API client and then clicking 'Generate Access Token'.

from pyclearpass import *
login = ClearPassAPILogin(server="https://yourserver.network.local:443/api",api_token="yoursecretapitoken", verify_ssl=False)

Get Local Server Configuration

import json
LSCGCS = ApiLocalServerConfiguration.get_cluster_server(login)
print(json.dumps(LSCGCS['_embedded']['items'],indent=1))

Get Total End Point Count

IGEP = ApiIdentities.get_endpoint(login, calculate_count='true')
print("Total MACs in Table: "+str(IGEP['count']))

Get Insight Device Details

print(ApiLogs.get_insight_endpoint_ip_by_ip(login,ip="192.168.0.99"))

Get list of Admin Users

AU = ApiGlobalServerConfiguration.get_admin_user(login)
for users in AU['_embedded']['items']:
  print(users)

Add New Endpoint

newEndPoint = {
  "mac_address": "11:22:33:44:55:66",
  "description": "Demo EndPoint 1",
  "status": "Known"
}
print(ApiIdentities.new_endpoint(login,body=newEndPoint))

Add New Role

role={"name": "Test1","description": "Test role made using the API Package in Python"}
print(ApiPolicyElements.new_role(login,body=role))

Delete Role

print(ApiPolicyElements.delete_role_name_by_name(login,name='Demo'))

Get Network Access Device

devices = ApiPolicyElements.get_network_device(login)
for device in devices["_embedded"]["items"]:
    print(device)

Get Network Access Device by Name

print(ApiPolicyElements.get_network_device_name_by_name(login, "Lab-AP-IAP-VC"))

Add New Network Access Device

newNAD = {
    "description": "LAB AP IAP VC",
    "name": "Lab-AP-IAP-VC",
    "ip_address": "192.168.0.100",
    "radius_secret": "example_radius_secret",
    "tacacs_secret": "example_tacacs_secret",
    "vendor_name": "Aruba",
    "coa_capable": True,
    "coa_port": 3799,
    "attributes": {"Device Type": "IAP"},
}
ApiPolicyElements.new_network_device(login, body=newNAD)

Add New Network Access Device via CSV

This example adds new Network Access Devices based on the CSV (comma delimited values) named "network access devices.csv" with headings and content filled rows.

import pandas as pd
df = pd.read_csv("network access devices.csv")

for index, items in df.iterrows():
    newnad = {
        "description": items["description"],  # Description of the network device. Object Type: string
        "name": items["name"],  # Name of the network device. Object Type: string
        "ip_address": items["ip_address"],  # IP or Subnet Address of the network device. Object Type: string
        "tacacs_secret": "testing123",  # TACACS+ Shared Secret of the network device. Object Type: string
        "vendor_name": "Aruba",  # Vendor Name of the network device. Object Type: string
        "attributes": {"Location": items["location"]},
    }
    print(ApiPolicyElements.new_network_device(login, body=newnad))
    print(items["name"], items["ip_address"])

Update Network Access Device via CSV

This example updates Network Access Devices attributes based on the CSV (comma delimited values) named "network access devices updates.csv" with headings and content filled rows.

import pandas as pd
df = pd.read_csv("network access devices updates.csv")
for index, items in df.iterrows():
    nadupdate = {                
        "tacacs_secret": "updatedpassword123",  # TACACS+ Shared Secret of the network device. Object Type: string
        "description": items["description"],  # Description of the network device. Object Type: string
        "attributes": {"Location": items["location"]},
    }
    print(ApiPolicyElements.update_network_device_name_by_name(login,name=items["name"],body=nadupdate))

Update Network Device Group

This example updates an Network Device Group with additional IP Addresses 192.168.0.100 and 192.168.0.99.
These Network Access Devices must of been added before they can be appended to the group.

getcurrentnads = ApiPolicyElements.get_network_device_group_name_by_name(login,name="Example")
newnads={"value" : "192.168.0.100, 192.168.0.98"}
newnads["value"]=getcurrentnads['value']+", "+newnads["value"]
print(ApiPolicyElements.update_network_device_group_name_by_name(login,name="Example",body=newnads))

🚧

Ensure completion of validation checks

Validate the Network Access Device exists and is not already part of the Network Device Group before attempting to append to the group.

Add New Guest Device

This example adds a Guest Device including

1. An expiry date within 24 hours in seconds
2. Associated to the role ID of 3 (Guest in test environment)
3. Statically assigned MPSK password

import time
new_guest_device = {
  "enabled": True,
  "expire_time": int(time.time()) + 86400,
  "mac": "11:22:22:33:33:11",
  "notes": "Created by API Test Script",
  "role_id": 3,
  "sponsor_profile_name": "Super Administrator",
  "visitor_name": "API Test Device",
  "mpsk":"SecretPassword",
  "mpsk_enable":"1"
}
new_device= ApiIdentities.new_device(login,body=new_guest_device)
print(new_device)

Get Guest Device by MAC

import json
get_mac_address = "11-22-33-33-22-11"
view_guest_device = ApiIdentities.get_device_mac_by_macaddr(login,get_mac_address)
print(json.dumps(view_guest_device,indent=2))

Delete an Enforcement Policy

print(ApiPolicyElements.delete_enforcement_policy_by_enforcement_policy_id(login,enforcement_policy_id='3058'))

Filters

The get functions contain filters which can be used to further filter results before returning the object to the terminal. The table below describes the filters which can be used along with some brief examples below.

devices = ApiPolicyElements.get_network_device(login, filter={"ip_address": {"$contains": "10.0.0"}})
print(devices["_embedded"]["items"])

devices = ApiPolicyElements.get_network_device(login, filter={"name": "workswitch"})
print(devices["_embedded"]["items"])