Client

Client

Client

Constructor

new Client(options)

Source:
See:

Series of functions that allow easy interaction with Cisco PxGrid 2.0 protocol implementation (typically with a Cisco ISE PxGrid Controller).

PxGrid 2.0 makes use of REST API for push/pull options, and Web Sockets for messaging-style connections.

The web sockets use a STOMP-based messaging framework.

Example
const fs = require('fs');
const Pxgrid = require('pxgrid-node');

certs = [];
certs.clientCert = fs.readFileSync('./certs/publiccert.cer');
certs.clientKey = fs.readFileSync('./certs/key.pem');
certs.caBundle = fs.readFileSync('./certs/caBundle.cer');

const pxgridControlOptions = {
  hosts: ['ise01.domain.com', 'ise02.domain.com']
  client: 'node-pxgrid',
  clientCert: certs.clientCert,
  clientKey: certs.clientKey,
  caBundle: certs.caBundle,
  clientKeyPassword: false,
}

const pxclient = new Pxgrid.Client(options);

pxclient.connect()
  .then(session => {
    pxclient.getProfiles()
       .then(profiles => console.log(profiles));

    pxclient.applyAncToEndpointByMac('QUARANTINE', '11:00:00:00:00:01')
      .then(response => console.log(response));
  });
Parameters:
Name Type Description
options Object

Options for the PxGrid Control instance. See examples for more information.

Properties
Name Type Attributes Default Description
host string

The IP or URL of the PxGrid Controller. Deprecated in v1.3.0, please use hosts array.

hosts Object

An array of PxGrid controllers to attempt connecting to. The first successful connection will be used.

port number <optional>

The host port to connect to the PxGrid Controller on.

client string

The desired name of the client for the client.

clientCert Buffer

A byte stream of the client public key certificate file to use.

clientKey Buffer

A byte stream of the client private key file to use.

caBundle Buffer

A byte stream of the CA Bundle used to verify the PxGrid Controller's identity.

verifySSL Boolean <optional>
true

If true, verify server's SSL certificate.

httpTimeout number <optional>
1000

Value, in milliseconds, to consider a server unavailable.

clientKeyPassword string <optional>

The password to unlock the client private key file.

secret string <optional>

The secret to help authenticate a newly registered service.

Methods

applyAncToEndpointByIp(policy, ip) → {Promise}

Source:

Apply an ANC policy to an endpoint by IP address.

Parameters:
Name Type Description
policy string

The name of the ANC policy to apply.

ip string

The IP address to apply the policy to.

Returns:

A status object.

Type
Promise

applyAncToEndpointByMac(policy, mac) → {Promise}

Source:

Apply an ANC policy to an endpoint by MAC address.

Parameters:
Name Type Description
policy string

The name of the ANC policy to apply.

mac string

The MAC address to apply the policy to.

Returns:

A status object.

Type
Promise

clearAncFromEndpointByIp(policy, ip) → {Promise}

Source:

Clears an ANC policy from an endpoint by IP address.

Parameters:
Name Type Description
policy string

The name of the ANC policy to clear.

ip string

The IP address to clear the policy from.

Returns:

A status object.

Type
Promise

clearAncFromEndpointByMac(policy, mac) → {Promise}

Source:

Clears an ANC policy from an endpoint by MAC address.

Parameters:
Name Type Description
policy string

The name of the ANC policy to clear.

mac string

The MAC address to clear the policy from.

Returns:

A status object.

Type
Promise

connect(optionsopt) → {Promise}

Source:
See:

Alternative to Client.connectToBroker(). Primarily added to give a jargon-free method to connect.

Parameters:
Name Type Attributes Description
options Object <optional>

An object with desired options.

Properties
Name Type Attributes Default Description
accountDesc string <optional>
'pxgrid-node'

A description for the client you are registering.

retryInterval number <optional>
60000

Retry interval in milliseconds.

maxRetries number <optional>
10

Maximum retries that will be attempted.

retryAttempt number <optional>
1

Which attempt we are on. This is necessary since we use recursion for retries.

debug boolean <optional>
false

false

Returns:

A fully activated client session.

Type
Promise

connectToBroker(optionsopt) → {Promise}

Source:
See:

Creates a STOMP client over a Web Socket connection to the PxGrid Controller.

This returned client object can be passed to subscribe/publish function to enable pub/sub functionality.

Example
const ancCallback = function(message) {
  const body = message.body;
  console.log(`${Date.now()}: Endpoint ${body.macAddress} has had an ${body.status} ANC event`);
};

pxclient
  .connect()
  .then(session => pxclient.subscribeToAncPolicies(session, ancCallback));
Parameters:
Name Type Attributes Description
options Object <optional>

An object with desired options.

Properties
Name Type Attributes Default Description
accountDesc string <optional>
'pxgrid-node'

A description for the client you are registering.

retryInterval number <optional>
60000

Retry interval in milliseconds.

maxRetries number <optional>
10

Maximum retries that will be attempted.

retryAttempt number <optional>
1

Which attempt we are on. This is necessary since we use recursion for retries.

debug boolean <optional>
false

false

Returns:

A fully activated client session.

Type
Promise

createAncPolicy(name, actions) → {Promise}

Source:

Create a new ANC policy.

Parameters:
Name Type Description
name string

The name of the new ANC policy.

actions Object

Actions must be an array, and there must only be one item in the array. Acceptable values are 'QUARANTINE', 'SHUT_DOWN', 'PORT_BOUNCE'.

Returns:

An ANC policy object.

Type
Promise

createCustomPublisher(stompClient, service, topic, debugopt) → {Object.publisher}

Source:

Creates a publisher for a custom topic. This also registers the client as a service for the topic with the controller.

Example
pxclient
 .connect()
 .then(session => pxclient.createCustomPublisher(session, 'my.service.name', 'myTopic'))
 .then(publisher => publisher.publish({ someData: 'Some sort of data.' }));
Parameters:
Name Type Attributes Default Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

service string

The custom service name that is providing the topic.

topic string

The custom topic.

debug boolean <optional>
false

Enables debugging.

Returns:

A publisher object.

Type
Object.publisher

createEndpointAssetPublisher() → {Promise}

Source:

Creates a publisher for the Endpoint Asset service. This also registers the client as a publisher for the topic with the controller.

Returns:

A status object.

Type
Promise

deleteAncPolicy(name) → {Promise}

Source:

Deletes an ANC policy.

Parameters:
Name Type Description
name string

The name of the ANC policy to be deleted.

Returns:

Empty.

Type
Promise

disconnect(stompClient)

Source:

Gracefully disconnects the STOMP client over a Web Socket connection to the PxGrid Controller.

This is recommended in order to prevent excessive stale connections on the ISE server from causing issues.

The PxGrid Controller on ISE will reap stale connections; however, if you are using multiple, rapid connections it would be best to handle it directly to immediately clean unneeded connections.

Example
pxclient
  .connect()
  .then(session => pxclient.disconnect(session));
Parameters:
Name Type Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

getAncEndpointByMac(mac) → {Promise}

Source:

Get ANC policy for MAC address.

Parameters:
Name Type Description
mac string

MAC address of endpoint.

Returns:

An ANC endpoint object.

Type
Promise

getAncEndpoints() → {Promise}

Source:

Get all endpoints assigned an ANC policy.

Returns:

An array of endpoint objects.

Type
Promise

getAncOperationStatus(id) → {Promise}

Source:

The status of an ANC operation. If operation does not exist, HTTP status "204 No content" will be returned.

Parameters:
Name Type Description
id string

An operation ID.

Returns:

A status object.

Type
Promise

getAncPolicies() → {Promise}

Source:

Get all ANC policies.

Returns:

An array of ANC policy objects.

Type
Promise

getAncPolicyByName(name) → {Promise}

Source:

Gets an ANC policy details by name.

Parameters:
Name Type Description
name string

Name of an existing ANC policy.

Returns:

An ANC policy object.

Type
Promise

getEgressMatrices() → {Promise}

Source:

Get all TrustSec egress matrices.

Returns:

An array of egress matrix objects.

Type
Promise

getEgressPolicies() → {Promise}

Source:

Get all TrustSec egress policies.

Returns:

An array of egress policy objects.

Type
Promise

getMdmEndpointByMac(mac) → {Promise}

Source:

Gets an MDM endpoints by MAC address.

Parameters:
Name Type Description
mac string

MAC address of MDM client to retrieve.

Returns:

An MDM endpoint object.

Type
Promise

getMdmEndpoints(filteropt) → {Promise}

Source:
See:

Gets MDM endpoints.

Parameters:
Name Type Attributes Default Description
filter boolean <optional>
false

Filter to restrict endpoints returned.

Returns:

An array of MDM endpoint objects.

Type
Promise

getMdmEndpointsByOs(osType) → {Promise}

Source:

Get an MDM endpoint by OS type.

Parameters:
Name Type Description
osType string

Value must be 'ANDROID', 'IOS', or 'WINDOWS'.

Returns:

An MDM endpoint object.

Type
Promise

getMdmEndpointsByType(type) → {Promise}

Source:

Get an MDM endpoint by type.

Parameters:
Name Type Description
type string

Value must be 'NON_COMPLIANT', 'REGISTERED', or 'DISCONNECTED'.

Returns:

An array of MDM endpoint objects.

Type
Promise

getProfiles() → {Promise}

Source:

Get all endpoint profiles.

Returns:

An array of endpoint profile objects.

Type
Promise

getRadiusFailureById(id) → {Promise}

Source:

Get RADIUS failure by ID.

Parameters:
Name Type Description
id string

Failure ID.

Returns:

A failure object.

Type
Promise

getRadiusFailures(startTimestampopt) → {Promise}

Source:

Get all RADIUS failures.

Parameters:
Name Type Attributes Default Description
startTimestamp number <optional>
false

If not specified, failures from the last hour will be returned.

Returns:

An array of failure objects.

Type
Promise

getSecurityGroupAcls(idopt) → {Promise}

Source:

Get all security group ACLs (SGACLs).

Parameters:
Name Type Attributes Default Description
id string <optional>
false

Returns all if ID not specified.

Returns:

An array of SGACL objects.

Type
Promise

getSecurityGroups(idopt) → {Promise}

Source:

Get all Security Groups (SGTs).

Parameters:
Name Type Attributes Default Description
id string <optional>
false

Returns all if ID not specified.

Returns:

An array of security group objects.

Type
Promise

getSessionByIp(ip) → {Promise}

Source:

Get session information for a given IP address.

Parameters:
Name Type Description
ip string

IP address to lookup session for.

Returns:

A session object.

Type
Promise

getSessionByMac(mac) → {Promise}

Source:

Get session information for a given MAC address.

Parameters:
Name Type Description
mac string

MAC address to lookup session for.

Returns:

A session object.

Type
Promise

getSessions() → {Promise}

Source:

Get all active sessions.

Returns:

An array of session objects.

Type
Promise

getSxpBindings() → {Promise}

Source:

Get all TrustSec SXP bindings.

Note: Results are only returned for IP SGT Static Mapping, and only if an SXP device is configured with the SXP service enabled. Otherwise, nothing is returned (even if mappings are configured).

Returns:

An array of SXP binding objects.

Type
Promise

getSystemHealth(options) → {Promise}

Source:

Get system health events.

Parameters:
Name Type Description
options Object

Options for filtering the system health events.

Properties
Name Type Attributes Description
nodeName string <optional>

The name of the node to get system health for. Will return all nodes if nodeName not specified.

startTimestamp ISO8601Datetime <optional>

The timestamp to begin getting events with. Will return last hour if startTimestamp not specified.

Returns:

An array of system health objects.

Type
Promise

getSystemPerformance(options) → {Promise}

Source:

Get system performance events.

Parameters:
Name Type Description
options Object

Options for filtering the system performance.

Properties
Name Type Attributes Description
nodeName string <optional>

The name of the node to get system performance for. Will return all nodes if nodeName not specified.

startTimestamp ISO8601Datetime <optional>

The timestamp to begin getting events with. Will return last hour if startTimestamp not specified.

Returns:

An array of system performance objects.

Type
Promise

getUserGroupByUserName(name) → {Promise}

Source:

Gets all groups a given username is a member of.

Parameters:
Name Type Description
name string

User name.

Returns:

An array of group objects.

Type
Promise

getUserGroups() → {Promise}

Source:

Gets all user groups.

Returns:

An array of group objects.

Type
Promise

publishEndpointAssetUpdate(stompClient, assetBody, debugopt)

Source:

Publish an endpoint asset update.

This allows the addition of attributes from the IOTAsset dictionary, as well as any pre-configured custom attributes, into the endpoint.

Note: The Cisco ISE pxGrid Profiler Probe must be enabled for this published event to be processed by ISE. This is not on by default.

Parameters:
Name Type Attributes Default Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

assetBody Object

A JSON object of asset information to publish to an endpoint.

Properties
Name Type Description
assetMacAddress string

MAC address of endpoint.

assetId string

Arbitrary value.

assetName string

Arbitrary value.

assetHwRevision string

Arbitrary value.

assetProtocol string

Arbitrary value.

assetVendor string

Arbitrary value.

assetSwRevision string

Arbitrary value.

assetProductId string

Arbitrary value.

assetSerialNumber string

Arbitrary value.

assetDeviceType string

Arbitrary value.

assetIpAddress string

Arbitrary value.

assetCustomAttributes string

Arbitrary value.

assetConnectedLinks string

Arbitrary value.

assetConnectedAttributes Object

Any other custom attributes that have been created in Cisco ISE.

assetCustomAttributes.attrName string

AttrName should match name of custom attribute in ISE. Value is arbitrary.

debug boolean <optional>
false

Enables debug messages being logged to console.

subscribeToAllTopics(stompClient, messageCallback)

Source:

Subscribes to all pre-defined topics.

Parameters:
Name Type Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

messageCallback function

A callback function that handles the message coming in on a topic subscription.

subscribeToAncPolicies(stompClient, messageCallback) → {Promise}

Source:

Subscribes to the ANC policy topic. Messages generated for endpoints being applied or cleared from an ANC policy.

Parameters:
Name Type Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

messageCallback function

A callback function that handles the message coming in on a topic subscription.

Returns:

A stomp subscriber object.

Type
Promise

subscribeToCustom(stompClient, service, topic, messageCallback, debugopt)

Source:

Subscribes to a custom topic on a specified service. This topic is assumed as previously created using Client.createCustomPublisher() or otherwise.

Example
pxclient
  .connect()
  .then(session => pxclient.subscribeToCustom(session, 'blah.blah.blah', 'customTopic', genericCallback));
Parameters:
Name Type Attributes Default Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

service string

The custom service name that is providing the topic.

topic string

The custom topic.

messageCallback function

A callback function that handles the message coming in on a topic subscription.

debug boolean <optional>
false

Enables debugging.

subscribeToEndpointAsset(stompClient, messageCallback) → {Promise}

Source:

Subscribes to the Endpoint Asset topic.

Parameters:
Name Type Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

messageCallback function

A callback function that handles the message coming in on a topic subscription.

Returns:

A stomp subscriber object.

Type
Promise

subscribeToGroups(stompClient, messageCallback) → {Promise}

Source:

Subscribes to the groups topic.

Note: During testing, this subscription did not appear to receive any data from create, update, delete operations on user/endpoint identity groups, or adding/removing users from an identity group.

Parameters:
Name Type Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

messageCallback function

A callback function that handles the message coming in on a topic subscription.

Returns:

A stomp subscriber object.

Type
Promise

subscribeToMdmEndpoints(stompClient, messageCallback) → {Promise}

Source:

Subscribes to the MDM endpoints topic.

Parameters:
Name Type Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

messageCallback function

A callback function that handles the message coming in on a topic subscription.

Returns:

A stomp subscriber object.

Type
Promise

subscribeToProfiler(stompClient, messageCallback) → {Promise}

Source:

Subscribes to the profiles topic.

Note: This topic only emits events when an endpoint profile is created or deleted. It doesn't emit anything when an endpoint changes profile.

Parameters:
Name Type Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

messageCallback function

A callback function that handles the message coming in on a topic subscription.

Returns:

A stomp subscriber object.

Type
Promise

subscribeToRadiusFailures(stompClient, messageCallback) → {Promise}

Source:

Subscribes to the RADIUS failures topic.

Parameters:
Name Type Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

messageCallback function

A callback function that handles the message coming in on a topic subscription.

Returns:

A stomp subscriber object.

Type
Promise

subscribeToSecurityGroups(stompClient, messageCallback) → {Promise}

Source:

Subscribes to the Security Groups (SGTs) topic.

Parameters:
Name Type Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

messageCallback function

A callback function that handles the message coming in on a topic subscription.

Returns:

A stomp subscriber object.

Type
Promise

subscribeToSessions(stompClient, messageCallback) → {Promise}

Source:

Subscribes to the sessions topic.

Parameters:
Name Type Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

messageCallback function

A callback function that handles the message coming in on a topic subscription.

Returns:

A stomp subscriber object.

Type
Promise

subscribeToSxpBindings(stompClient, messageCallback) → {Promise}

Source:

Subscribes to the SXP bindings topic.

Note: During testing, this topic did not emit any events for new SXP bindings (IP-SGT Mappings) or new SXP connections.

Parameters:
Name Type Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

messageCallback function

A callback function that handles the message coming in on a topic subscription.

Returns:

A stomp subscriber object.

Type
Promise

subscribeToTrustSecPolicyDownloads(stompClient, messageCallback) → {Promise}

Source:

Subscribes to the groups topic.

Note: this service only provide status of SGACL downloads via subscription (as of ISE 2.4).

Parameters:
Name Type Description
stompClient Object.<stompClient>

The active broker session to use for subscription.

messageCallback function

A callback function that handles the message coming in on a topic subscription.

Returns:

A stomp subscriber object.

Type
Promise