Endpoint - cisco-pxgrid/pxgrid-rest-ws GitHub Wiki

Service: com.cisco.ise.endpoint

ISE endpoints are client devices [Eg. Workstations, Mobiles, Printers etc.] which are connected to the ISE managed network devices [Eg. Switches, WLC etc.]. ISE service provides access to these ISE endpoints via the object named Endpoints.

Multiple nodes. Use one.

ServiceLookup may return more than one nodes providing this service. Each node is a replica of each other. In other words, connecting to one of these nodes is sufficient.

Go through the list of nodes until one succeed. If none of them work, sleep for retry. Redo ServiceLookup before retry as there maybe service updates.

Sample ServiceLookup response

{
    "services": [
        {
            "name": "com.cisco.ise.endpoint",
            "nodeName": "~nodename",
            "properties": {
                "wsPubsubService": "com.cisco.ise.pubsub",
                "restBaseUrl": "https://[ise-host1]:8910/pxgrid/ise/endpoint",
                "topic": "/topic/com.cisco.ise.endpoint"
            }
        }
    ]
}

Service properties

Name Description ISE version Example values
restBaseUrl The base URL for APIs 3.3 https://[ise-host1]:8910/pxgrid/ise/endpoint/
wsPubsubService The WebSocket Pubsub service name 3.3 com.cisco.ise.pubsub
topic Topic for endpoint events 3.3 /topic/com.cisco.ise.endpoint

HTTP APIs

POST [restBaseUrl]/getEndpoints

It is a REST API which consumes the JSON data and returns the endpoints data in JSON format and provides access to ISE EndPoint Details along with the probe data attributes.

Description of the request attributes.

  • order: [Optional]. Order parameter can be specified to select ascending or descending query of the endpoints. Default operation of ascending will be used if nothing is specified. Example: "ASC" or "DESC". It works on the startCreateTimestamp and startUpdateTimestamp and orders the data based on which timestamp is used in the request. ASC sorting is supported currently, and DESC sorting will be implemented in the coming days.
  • startCreateTimestamp: [Optional] Create time filter on the endpoint, if not specified all the endpoints will be queried from ISE database. Expected Format: ISO8601 Datetime. Example: 2024-07-05T06:57:19.595Z
  • startIndex: [Optional] StartIndex can be used to skip initial records to navigate to the next set of endpoints matching the filter. Default value of 0 will be used if nothing is specified.
  • count: [Optional] Maximum number of records fetched. Default value of 100 will be used if nothing is specified. Number of records which will be present from the start index.
  • startUpdateTimestamp: [Optional] Update time filter on the endpoint, if not specified all the endpoints will be queried from ISE database. Expected Format: ISO8601 Datetime. Example: 2019-07-05T06:57:19.595Z
  • skipConfigCheck: Its an internal attribute that takes either true or false values. This will allow to perform download though "Publish Endpoint Attributes to AI Endpoint Analytics" option is disabled in ISE GUI. Default value is false.

Note: startCreateTimestamp or startUpdateTimestamp is mandatory, i.e. either one of the attributes is required in the request sent to ISE.

Request:

{ 
    "order":"DESC",
    "startCreateTimestamp":"2024-07-20T00:00:00.000+05:30",
    "startIndex":0,
    "count":1000,
    "skipConfigCheck":true 
}

Sample Response:

{
    "endpoints": [
        {
            "macAddress": "00:50:56:B2:FE:BF",
            "attributes": {
                "destinationPort": "1813",
                "policyVersion": "1",
                "oui": "VMware, Inc.",
                "mfcInfoHardwareModel": "VMWare-Device",
                "mfcInfoEndpointType": "Workstation",
                "matchedPolicyID": "3af39770-8c00-11e6-996c-525400b48521",
                "framedIpAddress": "9.133.10.39",
                "totalCertaintyFactor": "10",
                "portalUser": "",
                "timeToProfile": "19",
                "edfCreateTime": "2024-07-19T11:10:08.654Z",
                "identityGroup": "Profiled",
                "lastNmapScanTime": "0",
                "nmapScanCount": "0",
                "firstCollection": "1721387408615",
                "edfUpdateTime": "",
                "nasIpAddress": "9.129.4.78",
                "logicalProfile": "",
                "mfcInfoDeviceType": "Workstation",
                "endPointPolicyID": "3af39770-8c00-11e6-996c-525400b48521",
                "mfcInfoOperatingSystem": "",
                "endpointSource": "RADIUS Probe",
                "nmapSubnetScanID": "0",
                "ip": "9.133.10.39",
                "postureApplicable": "Yes",
                "endPointProfilerServer": "podN-Ise9.sta-lab.com",
                "deviceRegistrationStatus": "NotRegistered",
                "staticGroupAssignment": "false",
                "updateTime": "0",
                "mfcInfoHardwareManufacturer": "VMware, Inc.",
                "deviceIpAddress": "9.129.4.78",
                "matchedPolicy": "VMWare-Device",
                "byodRegistration": "Unknown",
                "identityGroupID": "aa10ae00-8bff-11e6-996c-525400b48521",
                "macAddress": "00:50:56:B2:FE:BF",
                "failureReason": "5436 RADIUS packet already in the process",
                "messageCode": "5436",
                "devicePort": "59323",
                "lastActivity": "1721387408616",
                "staticAssignment": "false",
                "endPointPolicy": "VMWare-Device",
                "destinationIpAddress": "9.132.5.143",
                "callingStationId": "00-50-56-B2-FE-BF"
            },
            "customAttributes": {},
            "timestamp": "2024-07-19T11:10:08.654Z"
        }
    ]
}

WS STOMP messaging

endpointTopic

This topic provides events of Endpoint updates. Events are published only when there is a change in the endpoint attributes apart from timestamps and statistics.

{
  "endpoint": {
    "endpoint object information"
  }, "sequence": "long sequence number for loss detection (From ISE 3.5 onwards)"
}

Important points to remember:

  • Client must keep track of the sequence attribute in the JSON response to verify the receival of all messages.
  • Sequence will get incremented by one for every publish of the endpoints data.
  • Bulk download to be performed when the sequence is 0.
  • When the sequence number reaches Long.MAX_VALUE, sequence will be reset to 1.
  • ‘gets’ is the service operation tagged to this API.
  • Upon restart, PxGrid publishes two messages with sequence number 0 and 1 having identical content in them which suggests the new consumers to perform bulk download.
  • If the client receives an unexpected sequence number from PxGrid, client needs to perform a bulk download operation.

Objects

endpoint object

Name Type Description ISE versions
macAddress String MACAddress of the endpoint. 3.3
authenticationIdentityStore String   3.3
networkDeviceGroups String Comma separated network device groups 3.3
nasPortType String ·      Ethernet ·      Wireless ·      VPN 3.3
uniqueSubjectId String   3.3
aaaServer String PSN’s hostname 3.3
userFetchLastName String   3.3
matchedPolicyID String   3.3
framedIpNetmask String   3.3
totalCertaintyFactor String Certainty factor value assigned to the endpoint during profiling 3.3
selectedAccessService String Policy engine team to contact 3.3
identityPolicyMatchedRule String Rule name of policy which matched. 3.3
networkDeviceName String   3.3
logicalProfile String   3.3
endPointPolicyID String   3.3
endpointSource String   3.3
ip String IP address of the endpoint. 3.3
phoneId String   3.3
deviceRegistrationStatus String ·      Registered ·      NotRegistered 3.3
staticGroupAssignment String ·      True ·      False 3.3
postureAssessmentStatus String   3.3
deviceIpAddress String NAD’s IP Address 3.3
nasPort String   3.3
identityGroupID String   3.3
macAddress String   3.3
authenticationMethod String Protocol used to authenticate. 3.3
failureReason String   3.3
allowedProtocolMatchedRule String   3.3
userType String   3.3
destinationIpAddress String   3.3
destinationPort String   3.3
policyVersion String Version of the policies used to profile the endpoint. 3.3
oui String Vendor’s ID of the network adapter. 3.3
nasPortId String   3.3
framedIpAddress String IPAddress of the endpoint 3.3
portalUser String   3.3
registrationTimeStamp String   3.3
endPointMACAddress String   3.3
deviceIdentifier String   3.3
identityGroup String   3.3
mdmServerId String   3.3
lastNmapScanTime String   3.3
nmapScanCount String   3.3
userFetchFirstName String   3.3
nasIdentifier string   3.3
firstCollection string   3.3
nasIpAddress string   3.3
selectedAuthenticationIdentityStores String Comma separated Identity stores 3.3
nmapSubnetScanID String   3.3
postureApplicable String   3.3
endPointProfilerServer String   3.3
userFetchEmail String   3.3
updateTime string   3.3
userName string   3.3
matchedPolicy string   3.3
byodRegistration string   3.3
nadDeviceType string   3.3
createTime string Time in EPOCH. 3.3
dhcpHostName string   3.3
selectedAuthorizationProfiles string   3.3
authorizationPolicyMatchedRule string   3.3
userFetchUserName string   3.3
messageCode String Message code which is responsible for creation of the endpoint 3.3
lastActivity String   3.3
location String   3.3
cacheUpdateTime String Time in EPOCH 3.3
staticAssignment String ·      True ·      False 3.3
endPointPolicy String   3.3
callingStationId String   3.3
customAttributes String JSON string containing key – value pairs of custom attributes of endpoint. 3.3
sequence Long   3.5
mfcInfoHardwareModel String Provides information about the hardware model 3.3
mfcInfoEndpointType String Provides information about the endpoint type 3.3
timeToProfile String Time taken to profile the endpoint
edfCreateTime String Creation time of the endpoint
edfUpdateTime String Update time of the endpoint
mfcInfoDeviceType String Provides information about the device type 3.3
mfcInfoHardwareManufacturer String Provides information about the Hardware Manufacturer 3.3
devicePort String Device port of the endpoint
⚠️ **GitHub.com Fallback** ⚠️