Constructor
new Client(options)
- Source:
- See:
-
- Control
- Cisco PxGrid 2.0 GitHub Wiki for more information on the Cisco PxGrid 2.0 implementation.
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
|
Methods
applyAncToEndpointByIp(policy, ip) → {Promise}
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}
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}
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}
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
|
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
|
Returns:
A fully activated client session.
- Type
- Promise
createAncPolicy(name, actions) → {Promise}
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}
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}
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}
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)
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}
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}
Get all endpoints assigned an ANC policy.
Returns:
An array of endpoint objects.
- Type
- Promise
getAncOperationStatus(id) → {Promise}
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}
Get all ANC policies.
Returns:
An array of ANC policy objects.
- Type
- Promise
getAncPolicyByName(name) → {Promise}
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}
Get all TrustSec egress matrices.
Returns:
An array of egress matrix objects.
- Type
- Promise
getEgressPolicies() → {Promise}
Get all TrustSec egress policies.
Returns:
An array of egress policy objects.
- Type
- Promise
getMdmEndpointByMac(mac) → {Promise}
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:
-
- PxGrid MDM Documentation for endpoint object used for filter.
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}
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}
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}
Get all endpoint profiles.
Returns:
An array of endpoint profile objects.
- Type
- Promise
getRadiusFailureById(id) → {Promise}
Get RADIUS failure by ID.
Parameters:
Name | Type | Description |
---|---|---|
id |
string | Failure ID. |
Returns:
A failure object.
- Type
- Promise
getRadiusFailures(startTimestampopt) → {Promise}
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}
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}
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}
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}
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}
Get all active sessions.
Returns:
An array of session objects.
- Type
- Promise
getSxpBindings() → {Promise}
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}
Get system health events.
Parameters:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object | Options for filtering the system health events. Properties
|
Returns:
An array of system health objects.
- Type
- Promise
getSystemPerformance(options) → {Promise}
Get system performance events.
Parameters:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object | Options for filtering the system performance. Properties
|
Returns:
An array of system performance objects.
- Type
- Promise
getUserGroupByUserName(name) → {Promise}
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}
Gets all user groups.
Returns:
An array of group objects.
- Type
- Promise
publishEndpointAssetUpdate(stompClient, assetBody, debugopt)
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
|
||||||||||||||||||||||||||||||||||||||||||||||||||
debug |
boolean |
<optional> |
false
|
Enables debug messages being logged to console. |
subscribeToAllTopics(stompClient, messageCallback)
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}
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)
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}
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}
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}
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}
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}
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}
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}
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}
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}
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