cisco-ise 1.0.0

package/EXAMPLES.md

@@ -0,0 +1,46 @@
+# Setup
+cisco-ise config add lab --host ise01.automate.builders --username admin --password '<your-pass>' --insecure
+cisco-ise config test
+
+# Endpoints
+cisco-ise endpoint list
+cisco-ise endpoint list --format json --limit 10
+cisco-ise endpoint search --mac E2:7C:7E:5B:F0:E0
+
+# Identity groups & auth profiles
+cisco-ise identity-group list
+cisco-ise identity-group list --type endpoint
+cisco-ise auth-profile list
+
+# Network devices
+cisco-ise network-device list
+
+# Deployment
+cisco-ise deployment nodes
+cisco-ise deployment status
+
+# Sessions
+cisco-ise session list
+
+# RADIUS
+cisco-ise radius failures --last 1h
+
+# TACACS
+cisco-ise tacacs command-sets
+cisco-ise tacacs profiles
+
+# TrustSec
+cisco-ise trustsec sgt list
+cisco-ise trustsec sgacl list
+
+# Guest
+cisco-ise guest portals
+cisco-ise guest list
+
+# Dry run a write operation (safe — no changes)
+cisco-ise endpoint add --mac AA:BB:CC:DD:EE:FF --group "Unknown" --dry-run
+
+# Output formats
+cisco-ise endpoint list --format json
+cisco-ise endpoint list --format csv
+cisco-ise endpoint list --format toon

package/RADIUS.md

@@ -0,0 +1,19 @@
+# Get your machine's IP
+ipconfig getifaddr en0
+
+# Add it as a NAD on ISE
+cisco-ise network-device add --name "macbook-test" --ip 192.168.40.140 --radius-secret "testing123"
+2. Test RADIUS authentication:
+
+You'll need a RADIUS test client. The easiest is radtest from FreeRADIUS:
+
+
+brew install freeradius-server
+
+# Test auth against ISE (port 1812)
+radtest admin Cisco123 ise01.automate.builders 0 testing123
+3. Check the logs:
+
+
+cisco-ise radius failures --last 30m
+cisco-ise session list

package/README.md

@@ -0,0 +1,222 @@
+# cisco-ise
+
+[![npm](https://img.shields.io/npm/v/cisco-ise.svg)](https://www.npmjs.com/package/cisco-ise)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-donate-orange.svg)](https://buymeacoffee.com/automatebldrs)
+
+CLI for Cisco ISE (Identity Services Engine) 3.1+ — day-to-day operations and troubleshooting via ERS, OpenAPI, and MNT APIs.
+
+## Installation
+
+```bash
+npm install -g cisco-ise
+```
+
+## Quick Start
+
+```bash
+# Add a cluster
+cisco-ise config add lab --host 10.0.0.1 --username admin --password '<ss:ID:password>' --insecure
+
+# Test connection
+cisco-ise config test
+
+# List endpoints
+cisco-ise endpoint list
+
+# Check RADIUS failures
+cisco-ise radius failures --last 1h
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `config` | Manage cluster configurations (add/use/list/show/remove/test/update/clear-cache) |
+| `endpoint` | Manage endpoints (list/search/add/update/delete, CSV bulk import) |
+| `guest` | Manage guest users (list/search/create/extend/suspend/reinstate/delete/portals) |
+| `network-device` | Manage network access devices (list/search/get/add/update/delete) |
+| `session` | Active sessions (list/search/disconnect/reauth via CoA) |
+| `radius` | RADIUS monitoring (failures with human-readable reasons, live polling) |
+| `tacacs` | TACACS+ monitoring (failures/live/command-sets/profiles) |
+| `identity-group` | List identity groups (--type endpoint/user) |
+| `auth-profile` | List/get authorization profiles |
+| `trustsec` | TrustSec SGTs and SGACLs (read-only) |
+| `deployment` | ISE deployment nodes and status (read-only) |
+
+## Configuration
+
+### Config file
+
+```bash
+cisco-ise config add prod --host ise.example.com --username admin --password '<ss:ID:password>' --insecure --read-only
+cisco-ise config add lab --host 10.0.0.1 --username admin --password '<ss:ID:password>' --insecure
+cisco-ise config use lab
+cisco-ise config list
+```
+
+Config stored in `~/.cisco-ise/config.json` (mode 0600).
+
+### Environment variables
+
+```bash
+export CISCO_ISE_HOST=<host>
+export CISCO_ISE_USERNAME=<user>
+export CISCO_ISE_PASSWORD=<password>
+```
+
+### Secret Server (ss-cli)
+
+Passwords can reference Delinea Secret Server:
+
+```bash
+cisco-ise config add prod --host ise.example.com --username admin --password '<ss:1234:password>' --insecure
+```
+
+### Precedence
+
+CLI flags > environment variables > config file.
+
+## MAC Address Formats
+
+Any common format is accepted and automatically normalized to `AA:BB:CC:DD:EE:FF`:
+
+- `AA:BB:CC:DD:EE:FF` — colon-separated
+- `AA-BB-CC-DD-EE-FF` — dash-separated
+- `AABB.CCDD.EEFF` — Cisco dot notation
+- `aabbccddeeff` — bare hex
+
+## Endpoint Management
+
+```bash
+# List all endpoints
+cisco-ise endpoint list
+cisco-ise endpoint list --limit 50 --format json
+
+# Search by MAC or group
+cisco-ise endpoint search --mac AA:BB:CC:DD:EE:FF
+cisco-ise endpoint search --group "Profiled"
+
+# Add endpoint
+cisco-ise endpoint add --mac AA:BB:CC:DD:EE:FF --group "Unknown" --description "Test device"
+
+# Bulk import from CSV
+cisco-ise endpoint add --csv endpoints.csv
+
+# Update and delete
+cisco-ise endpoint update AA:BB:CC:DD:EE:FF --group "Profiled"
+cisco-ise endpoint delete AA:BB:CC:DD:EE:FF
+```
+
+## Guest User Management
+
+```bash
+# List portals and guests
+cisco-ise guest portals
+cisco-ise guest list
+
+# Create a guest
+cisco-ise guest create --first "John" --last "Doe" --email "john@example.com" --portal "Sponsored Guest Portal (default)"
+
+# Manage guest lifecycle
+cisco-ise guest extend <id> --duration 1d
+cisco-ise guest suspend <id>
+cisco-ise guest reinstate <id>
+cisco-ise guest delete <id>
+```
+
+## Session Management
+
+```bash
+# List active sessions
+cisco-ise session list
+cisco-ise session search --mac E2:7C:7E:5B:F0:E0
+cisco-ise session search --user jdoe
+
+# CoA operations
+cisco-ise session disconnect E2:7C:7E:5B:F0:E0
+cisco-ise session reauth E2:7C:7E:5B:F0:E0
+```
+
+## RADIUS & TACACS+ Monitoring
+
+```bash
+# RADIUS failures with human-readable reasons
+cisco-ise radius failures --last 1h
+cisco-ise radius failures --last 30m --user jdoe
+
+# Live RADIUS monitoring (Ctrl+C to stop)
+cisco-ise radius live
+
+# TACACS+
+cisco-ise tacacs failures --last 2h
+cisco-ise tacacs command-sets
+cisco-ise tacacs profiles
+```
+
+## Network Devices
+
+```bash
+cisco-ise network-device list
+cisco-ise network-device search --name "switch"
+cisco-ise network-device add --name "switch01" --ip 10.0.0.1 --radius-secret '<ss:ID:radius-secret>'
+cisco-ise network-device delete "switch01"
+```
+
+## Read-Only Protection
+
+Clusters marked `--read-only` require typing a random word before any write operation:
+
+```bash
+cisco-ise config add prod --host ise.example.com --username admin --password '<ss:ID:password>' --read-only --insecure
+```
+
+Non-interactive environments are blocked entirely.
+
+## Dry Run
+
+Preview write operations without executing:
+
+```bash
+cisco-ise endpoint add --mac AA:BB:CC:DD:EE:FF --group "Unknown" --dry-run
+# Output: DRY RUN — no changes made
+#         POST https://ise.example.com:9060/ers/config/endpoint
+#         { ... payload ... }
+```
+
+## Output Formats
+
+```bash
+cisco-ise endpoint list --format table   # default, human-readable
+cisco-ise endpoint list --format json    # for scripting
+cisco-ise endpoint list --format csv     # for spreadsheets
+cisco-ise endpoint list --format toon    # token-efficient for AI agents
+```
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--format <type>` | Output format: table, json, toon, csv |
+| `--host <host>` | ISE hostname or IP |
+| `--username <user>` | ISE username |
+| `--password <pass>` | ISE password |
+| `--cluster <name>` | Use a named cluster |
+| `--insecure` | Skip TLS certificate verification |
+| `--read-only` | Block write operations |
+| `--dry-run` | Show what would happen without executing |
+| `--no-audit` | Disable audit logging |
+| `--no-cache` | Bypass response cache |
+| `--debug` | Enable debug logging |
+
+## ISE API Details
+
+- **ERS API** (port 9060) — endpoints, groups, network devices, guests, auth profiles, TrustSec
+- **OpenAPI** (port 443) — deployment, modern endpoints
+- **MNT API** (port 443) — sessions, CoA, RADIUS/TACACS monitoring
+
+ERS must be enabled in ISE Admin > Settings > ERS Settings.
+
+## License
+
+MIT

package/bin/cisco-ise.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+// Suppress Node.js TLS warning — users opt into insecure mode explicitly
+// via --insecure flag or cluster config, so the warning is redundant noise
+const originalEmit = process.emit;
+process.emit = function (event, warning) {
+  if (event === "warning" && warning?.name === "Warning" &&
+      warning?.message?.includes("NODE_TLS_REJECT_UNAUTHORIZED")) {
+    return false;
+  }
+  return originalEmit.apply(this, arguments);
+};
+
+require("../cli/index.js");

package/cli/commands/auth-profile.js

@@ -0,0 +1,36 @@
+const { resolveConnection } = require("../utils/connection.js");
+const { printResult, printError } = require("../utils/output.js");
+const IseClient = require("../utils/api.js");
+
+module.exports = function (program) {
+  const cmd = program.command("auth-profile").description("List ISE authorization profiles");
+
+  cmd.command("list")
+    .description("List all authorization profiles")
+    .action(async (opts, command) => {
+      try {
+        const globalOpts = command.optsWithGlobals();
+        const conn = resolveConnection(globalOpts);
+        const client = new IseClient(conn, { noCache: !globalOpts.cache, debug: globalOpts.debug });
+
+        const resources = await client.ersPaginateAll("/authorizationprofile");
+        await printResult(resources, globalOpts.format);
+      } catch (err) { printError(err); }
+    });
+
+  cmd.command("get <name>")
+    .description("Get authorization profile details")
+    .action(async (name, opts, command) => {
+      try {
+        const globalOpts = command.optsWithGlobals();
+        const conn = resolveConnection(globalOpts);
+        const client = new IseClient(conn, { noCache: !globalOpts.cache, debug: globalOpts.debug });
+
+        const data = await client.ersGet("/authorizationprofile", { filter: `name.EQ.${name}`, size: 1 });
+        const resources = data?.SearchResult?.resources;
+        if (!resources?.length) throw new Error(`Authorization profile "${name}" not found.`);
+        const detail = await client.ersGet(`/authorizationprofile/${resources[0].id}`);
+        await printResult(detail?.AuthorizationProfile || detail, globalOpts.format);
+      } catch (err) { printError(err); }
+    });
+};

package/cli/commands/config.js

@@ -0,0 +1,140 @@
+const { resolveConnection } = require("../utils/connection.js");
+const config = require("../utils/config.js");
+const { printResult, printError } = require("../utils/output.js");
+const audit = require("../utils/audit.js");
+const IseClient = require("../utils/api.js");
+
+module.exports = function (program) {
+  const cmd = program.command("config").description("Manage ISE cluster configurations");
+
+  cmd.command("add <name>")
+    .description("Add a named ISE cluster")
+    .action((name, opts, command) => {
+      try {
+        const globalOpts = command.optsWithGlobals();
+        const { host, username, password, ppan, pmnt, insecure, readOnly } = globalOpts;
+        if (!host) throw new Error("--host is required");
+        if (!username) throw new Error("--username is required");
+        if (!password) throw new Error("--password is required");
+        config.addCluster(name, { host, username, password, ppan, pmnt, insecure, readOnly });
+        console.log(`Cluster "${name}" added successfully.`);
+      } catch (err) { printError(err); }
+    });
+
+  cmd.command("use <name>")
+    .description("Set the active cluster")
+    .action((name) => {
+      try {
+        config.useCluster(name);
+        console.log(`Active cluster set to "${name}".`);
+      } catch (err) { printError(err); }
+    });
+
+  cmd.command("list")
+    .description("List all configured clusters")
+    .action(async (opts, command) => {
+      try {
+        const clusters = config.listClusters();
+        const active = config.loadConfig().activeCluster;
+        const rows = Object.entries(clusters).map(([name, c]) => ({
+          name: name === active ? `${name} *` : name,
+          host: c.host,
+          username: c.username,
+          readOnly: c.readOnly ? "yes" : "no",
+        }));
+        await printResult(rows, command.optsWithGlobals().format);
+      } catch (err) { printError(err); }
+    });
+
+  cmd.command("show")
+    .description("Show active cluster details")
+    .action(async (opts, command) => {
+      try {
+        const data = config.loadConfig();
+        const cluster = data.clusters[data.activeCluster];
+        if (!cluster) throw new Error("No active cluster. Run: cisco-ise config add <name> ...");
+        const details = {
+          name: data.activeCluster,
+          host: cluster.host,
+          username: cluster.username,
+          password: config.maskPassword(cluster.password),
+          insecure: cluster.insecure || false,
+          readOnly: cluster.readOnly || false,
+        };
+        if (cluster.ppan) details.ppan = cluster.ppan;
+        if (cluster.pmnt) details.pmnt = cluster.pmnt;
+        if (cluster.sponsorUser) details.sponsorUser = cluster.sponsorUser;
+        if (cluster.sponsorPassword) details.sponsorPassword = config.maskPassword(cluster.sponsorPassword);
+        await printResult(details, command.optsWithGlobals().format);
+      } catch (err) { printError(err); }
+    });
+
+  cmd.command("remove <name>")
+    .description("Remove a cluster from config")
+    .action((name) => {
+      try {
+        config.removeCluster(name);
+        console.log(`Cluster "${name}" removed.`);
+      } catch (err) { printError(err); }
+    });
+
+  cmd.command("test")
+    .description("Test connection to active cluster")
+    .action(async (opts, command) => {
+      try {
+        const globalOpts = command.optsWithGlobals();
+        const conn = resolveConnection(globalOpts);
+        const client = new IseClient(conn, { debug: globalOpts.debug });
+
+        let ersOk = false, openApiOk = false;
+        try {
+          await client.ersGet("/endpoint", { size: 1 });
+          ersOk = true;
+        } catch { /* ERS not available */ }
+
+        try {
+          await client.openApiGet("/deployment/node");
+          openApiOk = true;
+        } catch { /* OpenAPI not available */ }
+
+        if (!ersOk && !openApiOk) {
+          throw new Error("Connection failed. Check host, credentials, and that ERS is enabled.");
+        }
+        console.log("Connection successful.");
+        console.log(`  ERS API (port 9060): ${ersOk ? "\u2713" : "\u2717"}`);
+        console.log(`  OpenAPI (port 443):  ${openApiOk ? "\u2713" : "\u2717"}`);
+      } catch (err) { printError(err); }
+    });
+
+  cmd.command("update <name>")
+    .description("Update cluster settings")
+    .action((name, opts, command) => {
+      try {
+        const globalOpts = command.optsWithGlobals();
+        const updates = {};
+        if (globalOpts.host) updates.host = globalOpts.host;
+        if (globalOpts.username) updates.username = globalOpts.username;
+        if (globalOpts.password) updates.password = globalOpts.password;
+        if (globalOpts.ppan) updates.ppan = globalOpts.ppan;
+        if (globalOpts.pmnt) updates.pmnt = globalOpts.pmnt;
+        if (globalOpts.sponsorUser) updates.sponsorUser = globalOpts.sponsorUser;
+        if (globalOpts.sponsorPassword) updates.sponsorPassword = globalOpts.sponsorPassword;
+        if (globalOpts.insecure !== undefined) updates.insecure = globalOpts.insecure;
+        if (globalOpts.readOnly !== undefined) updates.readOnly = globalOpts.readOnly;
+        config.updateCluster(name, updates);
+        console.log(`Cluster "${name}" updated.`);
+      } catch (err) { printError(err); }
+    });
+
+  cmd.command("clear-cache")
+    .description("Clear response cache")
+    .action((opts, command) => {
+      try {
+        const globalOpts = command.optsWithGlobals();
+        const conn = resolveConnection(globalOpts);
+        const client = new IseClient(conn);
+        client.invalidateCache();
+        console.log("Cache cleared.");
+      } catch (err) { printError(err); }
+    });
+};

package/cli/commands/deployment.js

@@ -0,0 +1,49 @@
+const { resolveConnection } = require("../utils/connection.js");
+const { printResult, printError } = require("../utils/output.js");
+const IseClient = require("../utils/api.js");
+
+module.exports = function (program) {
+  const cmd = program.command("deployment").description("ISE deployment information (read-only)");
+
+  cmd.command("nodes")
+    .description("List ISE deployment nodes")
+    .action(async (opts, command) => {
+      try {
+        const globalOpts = command.optsWithGlobals();
+        const conn = resolveConnection(globalOpts);
+        const client = new IseClient(conn, { noCache: !globalOpts.cache, debug: globalOpts.debug });
+
+        const data = await client.openApiGet("/deployment/node");
+        const nodes = data?.response || data || [];
+        const result = Array.isArray(nodes) ? nodes : [nodes];
+        await printResult(result.map((n) => ({
+          hostname: n.hostname || n.fqdn || "",
+          fqdn: n.fqdn || "",
+          ip: n.ipAddress || n.ipAddresses?.[0] || "",
+          roles: Array.isArray(n.roles) ? n.roles.join(", ") : (n.roles || ""),
+          services: Array.isArray(n.services) ? n.services.join(", ") : (n.services || ""),
+          status: n.nodeStatus || "",
+        })), globalOpts.format);
+      } catch (err) { printError(err); }
+    });
+
+  cmd.command("status")
+    .description("Show ISE deployment status")
+    .action(async (opts, command) => {
+      try {
+        const globalOpts = command.optsWithGlobals();
+        const conn = resolveConnection(globalOpts);
+        const client = new IseClient(conn, { noCache: !globalOpts.cache, debug: globalOpts.debug });
+
+        const data = await client.openApiGet("/deployment/node");
+        const nodes = data?.response || data || [];
+        const result = Array.isArray(nodes) ? nodes : [nodes];
+        await printResult(result.map((n) => ({
+          hostname: n.hostname || n.fqdn || "",
+          status: n.nodeStatus || "unknown",
+          roles: Array.isArray(n.roles) ? n.roles.join(", ") : (n.roles || ""),
+          services: Array.isArray(n.services) ? n.services.join(", ") : (n.services || ""),
+        })), globalOpts.format);
+      } catch (err) { printError(err); }
+    });
+};