cisco-ise 1.0.0

package/cli/commands/tacacs.js

@@ -0,0 +1,125 @@
+const { resolveConnection } = require("../utils/connection.js");
+const { printResult, printError } = require("../utils/output.js");
+const { resolveTimeRange } = require("../utils/time.js");
+const IseClient = require("../utils/api.js");
+
+module.exports = function (program) {
+  const cmd = program.command("tacacs").description("TACACS+ monitoring and configuration");
+
+  cmd.command("failures")
+    .description("Show TACACS+ authentication failures")
+    .option("--last <duration>", "time window (e.g., 30m, 2h, 1d)", "1h")
+    .option("--user <user>", "filter by username")
+    .option("--nas <nas>", "filter by NAS IP")
+    .action(async (opts, command) => {
+      try {
+        const globalOpts = command.optsWithGlobals();
+        const conn = resolveConnection(globalOpts);
+        const client = new IseClient(conn, { noCache: true, debug: globalOpts.debug });
+
+        const { from, to } = resolveTimeRange({ last: opts.last });
+
+        const data = await client.mntGet("/Session/AuthList/null/null");
+        let records = [];
+        const authList = data?.authStatusList?.authStatusElements;
+        if (authList) {
+          const list = Array.isArray(authList) ? authList : [authList];
+          records = list.filter((r) => {
+            if (r.passed === "true" || r.passed === true) return false;
+            const ts = new Date(r.acs_timestamp || 0).getTime();
+            return ts >= from && ts <= to;
+          });
+        }
+
+        if (opts.user) {
+          const search = opts.user.toLowerCase();
+          records = records.filter((r) => (r.user_name || "").toLowerCase().includes(search));
+        }
+        if (opts.nas) {
+          records = records.filter((r) => (r.nas_ip_address || "").includes(opts.nas));
+        }
+
+        const results = records.map((r) => ({
+          timestamp: r.acs_timestamp || "",
+          user: r.user_name || "",
+          nas: r.nas_ip_address || "",
+          reason: r.failure_reason || "Unknown",
+        }));
+
+        await printResult(results, globalOpts.format);
+      } catch (err) { printError(err); }
+    });
+
+  cmd.command("live")
+    .description("Live polling of TACACS+ events (Ctrl+C to stop)")
+    .option("--interval <seconds>", "polling interval in seconds", parseInt, 5)
+    .action(async (opts, command) => {
+      try {
+        const globalOpts = command.optsWithGlobals();
+        const conn = resolveConnection(globalOpts);
+        const client = new IseClient(conn, { noCache: true, debug: globalOpts.debug });
+
+        const seen = new Set();
+        const interval = (opts.interval || 5) * 1000;
+
+        process.stderr.write("Live TACACS+ monitoring started. Press Ctrl+C to stop.\n");
+
+        const poll = async () => {
+          try {
+            const data = await client.mntGet("/Session/ActiveList");
+            const sessions = data?.activeList?.activeSession;
+            if (!sessions) return;
+            const list = Array.isArray(sessions) ? sessions : [sessions];
+            for (const s of list) {
+              const id = s.acct_session_id;
+              if (id && !seen.has(id)) {
+                seen.add(id);
+                console.log(JSON.stringify({
+                  timestamp: new Date().toISOString(),
+                  user: s.user_name || "",
+                  nas: s.nas_ip_address || "",
+                  status: s.acct_status_type || "",
+                }));
+              }
+            }
+          } catch (err) {
+            process.stderr.write(`Poll error: ${err.message}\n`);
+          }
+        };
+
+        await poll();
+        const timer = setInterval(poll, interval);
+        process.on("SIGINT", () => {
+          clearInterval(timer);
+          process.stderr.write("\nStopped.\n");
+          process.exit(0);
+        });
+      } catch (err) { printError(err); }
+    });
+
+  cmd.command("command-sets")
+    .description("List TACACS+ command sets")
+    .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("/tacacscommandsets");
+        await printResult(resources, globalOpts.format);
+      } catch (err) { printError(err); }
+    });
+
+  cmd.command("profiles")
+    .description("List TACACS+ 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("/tacacsprofile");
+        await printResult(resources, globalOpts.format);
+      } catch (err) { printError(err); }
+    });
+};

package/cli/commands/trustsec.js

@@ -0,0 +1,37 @@
+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("trustsec").description("TrustSec SGT and SGACL management (read-only)");
+
+  const sgt = cmd.command("sgt").description("Security Group Tags");
+
+  sgt.command("list")
+    .description("List all SGTs")
+    .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("/sgt");
+        await printResult(resources, globalOpts.format);
+      } catch (err) { printError(err); }
+    });
+
+  const sgacl = cmd.command("sgacl").description("Security Group ACLs");
+
+  sgacl.command("list")
+    .description("List all SGACLs")
+    .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("/sgacl");
+        await printResult(resources, globalOpts.format);
+      } catch (err) { printError(err); }
+    });
+};

package/cli/formatters/csv.js

@@ -0,0 +1,10 @@
+const { stringify } = require("csv-stringify/sync");
+
+function formatCsv(data) {
+  const rows = Array.isArray(data) ? data : [data];
+  if (rows.length === 0) return "";
+  const columns = Object.keys(rows[0]);
+  return stringify(rows, { header: true, columns });
+}
+
+module.exports = formatCsv;

package/cli/formatters/json.js

@@ -0,0 +1,5 @@
+function formatJson(data) {
+  return JSON.stringify(data, null, 2);
+}
+
+module.exports = formatJson;

package/cli/formatters/table.js

@@ -0,0 +1,29 @@
+const Table = require("cli-table3");
+
+function formatTable(data) {
+  if (Array.isArray(data)) return formatListTable(data);
+  return formatItemTable(data);
+}
+
+function formatListTable(rows) {
+  if (rows.length === 0) return "No results found";
+  const columns = Object.keys(rows[0]);
+  const table = new Table({ head: columns });
+  for (const row of rows) {
+    table.push(columns.map((col) => String(row[col] ?? "")));
+  }
+  return `${table.toString()}\n${rows.length} result${rows.length !== 1 ? "s" : ""} found`;
+}
+
+function formatItemTable(item) {
+  const table = new Table();
+  for (const [key, value] of Object.entries(item)) {
+    const displayValue = typeof value === "object" && value !== null
+      ? JSON.stringify(value, null, 2)
+      : String(value ?? "");
+    table.push({ [key]: displayValue });
+  }
+  return table.toString();
+}
+
+module.exports = formatTable;

package/cli/formatters/toon.js

@@ -0,0 +1,6 @@
+async function formatToon(data) {
+  const { encode } = await import("@toon-format/toon");
+  return encode(data);
+}
+
+module.exports = formatToon;

package/cli/index.js

@@ -0,0 +1,44 @@
+const { Command } = require("commander");
+const pkg = require("../package.json");
+
+import("update-notifier")
+  .then(({ default: updateNotifier }) => updateNotifier({ pkg }).notify())
+  .catch(() => {});
+
+const program = new Command();
+
+program
+  .name("cisco-ise")
+  .description("CLI for Cisco ISE (Identity Services Engine)")
+  .version(pkg.version)
+  .option("--format <format>", "output format (table, json, toon, csv)", "table")
+  .option("--host <host>", "ISE hostname or IP")
+  .option("--username <user>", "ISE username")
+  .option("--password <pass>", "ISE password")
+  .option("--cluster <name>", "use a named cluster from config")
+  .option("--ppan <host>", "PAN node for ERS/OpenAPI (large deployments)")
+  .option("--pmnt <host>", "MNT node for monitoring APIs (large deployments)")
+  .option("--sponsor-user <user>", "sponsor username for guest API")
+  .option("--sponsor-password <pass>", "sponsor password for guest API")
+  .option("--insecure", "skip TLS certificate verification")
+  .option("--read-only", "block write operations")
+  .option("--dry-run", "show what would happen without executing")
+  .option("--no-audit", "disable audit logging")
+  .option("--no-cache", "bypass response cache")
+  .option("--debug", "enable debug logging");
+
+// Commands — registered as each command file is created
+require("./commands/config.js")(program);
+require("./commands/endpoint.js")(program);
+require("./commands/identity-group.js")(program);
+require("./commands/auth-profile.js")(program);
+require("./commands/network-device.js")(program);
+require("./commands/guest.js")(program);
+require("./commands/session.js")(program);
+require("./commands/radius.js")(program);
+require("./commands/tacacs.js")(program);
+require("./commands/trustsec.js")(program);
+require("./commands/internal-user.js")(program);
+require("./commands/deployment.js")(program);
+
+program.parse(process.argv);

package/cli/utils/api.js

@@ -0,0 +1,297 @@
+const axios = require("axios");
+const { XMLParser } = require("fast-xml-parser");
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const xmlParser = new XMLParser({ ignoreAttributes: false });
+
+class IseClient {
+  constructor(conn, opts = {}) {
+    this.conn = conn;
+    this.noCache = opts.noCache || false;
+    this.debug = opts.debug || false;
+    this.dryRun = opts.dryRun || false;
+    this.configDir = process.env.CISCO_ISE_CONFIG_DIR || path.join(require("os").homedir(), ".cisco-ise");
+    this.cacheDir = path.join(this.configDir, "cache");
+    this.cacheTTL = 5 * 60 * 1000;
+
+    const httpsAgent = conn.insecure
+      ? new (require("https").Agent)({ rejectUnauthorized: false })
+      : undefined;
+
+    this.axios = axios.create({
+      auth: { username: conn.username, password: conn.password },
+      httpsAgent,
+      timeout: 90000,
+    });
+
+    // Sponsor axios instance for guest API (uses sponsor credentials)
+    if (conn.sponsorUser && conn.sponsorPassword) {
+      this.sponsorAxios = axios.create({
+        auth: { username: conn.sponsorUser, password: conn.sponsorPassword },
+        httpsAgent,
+        timeout: 90000,
+      });
+    }
+  }
+
+  sponsorGet(endpoint, params = {}) {
+    if (!this.sponsorAxios) {
+      throw new Error(
+        "Guest API requires sponsor credentials. Run:\n" +
+        "  cisco-ise config update <name> --sponsor-user <user> --sponsor-password <pass>"
+      );
+    }
+    const url = this.ersUrl(endpoint);
+    if (this.debug) process.stderr.write(`[DEBUG] SPONSOR GET ${url}\n`);
+    return this.sponsorAxios({ method: "GET", url, headers: { Accept: "application/json" }, params })
+      .then((res) => res.data);
+  }
+
+  sponsorPost(endpoint, body) {
+    if (!this.sponsorAxios) {
+      throw new Error(
+        "Guest API requires sponsor credentials. Run:\n" +
+        "  cisco-ise config update <name> --sponsor-user <user> --sponsor-password <pass>"
+      );
+    }
+    const url = this.ersUrl(endpoint);
+    if (this.dryRun) return Promise.resolve({ dryRun: true, method: "POST", url, body });
+    if (this.debug) process.stderr.write(`[DEBUG] SPONSOR POST ${url}\n`);
+    return this.sponsorAxios({ method: "POST", url, headers: { Accept: "application/json", "Content-Type": "application/json" }, data: body })
+      .then((res) => { this.invalidateCache(); return res.data; });
+  }
+
+  sponsorPut(endpoint, body) {
+    if (!this.sponsorAxios) {
+      throw new Error(
+        "Guest API requires sponsor credentials. Run:\n" +
+        "  cisco-ise config update <name> --sponsor-user <user> --sponsor-password <pass>"
+      );
+    }
+    const url = this.ersUrl(endpoint);
+    if (this.dryRun) return Promise.resolve({ dryRun: true, method: "PUT", url, body });
+    if (this.debug) process.stderr.write(`[DEBUG] SPONSOR PUT ${url}\n`);
+    return this.sponsorAxios({ method: "PUT", url, headers: { Accept: "application/json", "Content-Type": "application/json" }, data: body })
+      .then((res) => { this.invalidateCache(); return res.data; });
+  }
+
+  sponsorDelete(endpoint) {
+    if (!this.sponsorAxios) {
+      throw new Error(
+        "Guest API requires sponsor credentials. Run:\n" +
+        "  cisco-ise config update <name> --sponsor-user <user> --sponsor-password <pass>"
+      );
+    }
+    const url = this.ersUrl(endpoint);
+    if (this.dryRun) return Promise.resolve({ dryRun: true, method: "DELETE", url });
+    if (this.debug) process.stderr.write(`[DEBUG] SPONSOR DELETE ${url}\n`);
+    return this.sponsorAxios({ method: "DELETE", url, headers: { Accept: "application/json" } })
+      .then((res) => { this.invalidateCache(); return res.data; });
+  }
+
+  async sponsorPaginateAll(endpoint, params = {}, opts = {}) {
+    const limit = opts.limit || Infinity;
+    const pageSize = opts.pageSize || 100;
+    let page = opts.page || 1;
+    let all = [];
+
+    while (all.length < limit) {
+      const data = await this.sponsorGet(endpoint, { ...params, size: pageSize, page });
+      const result = data?.SearchResult;
+      if (!result?.resources?.length) break;
+      all = all.concat(result.resources);
+      if (all.length >= result.total || result.resources.length < pageSize) break;
+      page++;
+    }
+
+    const results = all.slice(0, limit === Infinity ? undefined : limit);
+    return results.map((r) => {
+      if (!r.link) return r;
+      const { link, ...rest } = r;
+      return rest;
+    });
+  }
+
+  ersUrl(endpoint) {
+    const host = this.conn.ppan || this.conn.host;
+    return `https://${host}:9060/ers/config${endpoint}`;
+  }
+
+  openApiUrl(endpoint) {
+    const host = this.conn.ppan || this.conn.host;
+    return `https://${host}/api/v1${endpoint}`;
+  }
+
+  mntUrl(endpoint) {
+    const host = this.conn.pmnt || this.conn.host;
+    return `https://${host}/admin/API/mnt${endpoint}`;
+  }
+
+  cacheKey(url, params = {}) {
+    const data = JSON.stringify({ url, params });
+    return crypto.createHash("md5").update(data).digest("hex");
+  }
+
+  getCached(key) {
+    if (this.noCache) return null;
+    const file = path.join(this.cacheDir, `${key}.json`);
+    try {
+      const stat = fs.statSync(file);
+      if (Date.now() - stat.mtimeMs > this.cacheTTL) {
+        fs.unlinkSync(file);
+        return null;
+      }
+      return JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+
+  setCache(key, data) {
+    if (this.noCache) return;
+    fs.mkdirSync(this.cacheDir, { recursive: true });
+    fs.writeFileSync(path.join(this.cacheDir, `${key}.json`), JSON.stringify(data));
+  }
+
+  invalidateCache(prefix) {
+    try {
+      const files = fs.readdirSync(this.cacheDir);
+      for (const file of files) {
+        if (!prefix || file.startsWith(prefix)) {
+          fs.unlinkSync(path.join(this.cacheDir, file));
+        }
+      }
+    } catch { /* cache dir may not exist */ }
+  }
+
+  async ersGet(endpoint, params = {}) {
+    const url = this.ersUrl(endpoint);
+    const key = this.cacheKey(url, params);
+    const cached = this.getCached(key);
+    if (cached) return cached;
+
+    const res = await this.request("GET", url, {
+      headers: { Accept: "application/json" },
+      params,
+    });
+    this.setCache(key, res.data);
+    return res.data;
+  }
+
+  async ersPaginateAll(endpoint, params = {}, opts = {}) {
+    const limit = opts.limit || Infinity;
+    const pageSize = opts.pageSize || 100;
+    let page = opts.page || 1;
+    let all = [];
+
+    while (all.length < limit) {
+      const data = await this.ersGet(endpoint, { ...params, size: pageSize, page });
+      const result = data?.SearchResult;
+      if (!result?.resources?.length) break;
+      all = all.concat(result.resources);
+      if (all.length >= result.total || result.resources.length < pageSize) break;
+      page++;
+    }
+
+    const results = all.slice(0, limit === Infinity ? undefined : limit);
+    // Strip ERS link objects (they render as [object Object] in table output)
+    return results.map((r) => {
+      if (!r.link) return r;
+      const { link, ...rest } = r;
+      return rest;
+    });
+  }
+
+  async ersPost(endpoint, body) {
+    const url = this.ersUrl(endpoint);
+    if (this.dryRun) {
+      return { dryRun: true, method: "POST", url, body };
+    }
+    const res = await this.request("POST", url, {
+      headers: { Accept: "application/json", "Content-Type": "application/json" },
+      data: body,
+    });
+    this.invalidateCache();
+    return res.data;
+  }
+
+  async ersPut(endpoint, body) {
+    const url = this.ersUrl(endpoint);
+    if (this.dryRun) {
+      return { dryRun: true, method: "PUT", url, body };
+    }
+    const res = await this.request("PUT", url, {
+      headers: { Accept: "application/json", "Content-Type": "application/json" },
+      data: body,
+    });
+    this.invalidateCache();
+    return res.data;
+  }
+
+  async ersDelete(endpoint) {
+    const url = this.ersUrl(endpoint);
+    if (this.dryRun) {
+      return { dryRun: true, method: "DELETE", url };
+    }
+    const res = await this.request("DELETE", url, {
+      headers: { Accept: "application/json" },
+    });
+    this.invalidateCache();
+    return res.data;
+  }
+
+  async openApiGet(endpoint, params = {}) {
+    const url = this.openApiUrl(endpoint);
+    const key = this.cacheKey(url, params);
+    const cached = this.getCached(key);
+    if (cached) return cached;
+
+    const res = await this.request("GET", url, {
+      headers: { Accept: "application/json" },
+      params,
+    });
+    this.setCache(key, res.data);
+    return res.data;
+  }
+
+  async mntGet(endpoint) {
+    const url = this.mntUrl(endpoint);
+    const key = this.cacheKey(url);
+    const cached = this.getCached(key);
+    if (cached) return cached;
+
+    const res = await this.request("GET", url, {
+      headers: { Accept: "application/xml" },
+    });
+    const parsed = xmlParser.parse(res.data);
+    this.setCache(key, parsed);
+    return parsed;
+  }
+
+  async request(method, url, config = {}) {
+    if (this.debug) {
+      process.stderr.write(`[DEBUG] ${method} ${url}\n`);
+    }
+    try {
+      return await this.axios({ method, url, ...config });
+    } catch (err) {
+      if (err.response?.status === 429) {
+        for (let attempt = 1; attempt <= 3; attempt++) {
+          const delay = Math.pow(2, attempt) * 1000;
+          process.stderr.write(`Rate limited, retrying in ${delay / 1000}s...\n`);
+          await new Promise((r) => setTimeout(r, delay));
+          try {
+            return await this.axios({ method, url, ...config });
+          } catch (retryErr) {
+            if (retryErr.response?.status !== 429 || attempt === 3) throw retryErr;
+          }
+        }
+      }
+      throw err;
+    }
+  }
+}
+
+module.exports = IseClient;

package/cli/utils/audit.js

@@ -0,0 +1,30 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { getConfigDir } = require("./config.js");
+
+const MAX_FILE_SIZE = 10 * 1024 * 1024;
+
+function getAuditPath() {
+  return path.join(getConfigDir(), "audit.jsonl");
+}
+
+function rotateIfNeeded(auditPath) {
+  try {
+    const stats = fs.statSync(auditPath);
+    if (stats.size >= MAX_FILE_SIZE) {
+      const rotated = auditPath + ".1";
+      if (fs.existsSync(rotated)) fs.unlinkSync(rotated);
+      fs.renameSync(auditPath, rotated);
+    }
+  } catch { /* file doesn't exist yet */ }
+}
+
+function log(entry) {
+  const dir = getConfigDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const auditPath = getAuditPath();
+  rotateIfNeeded(auditPath);
+  fs.appendFileSync(auditPath, JSON.stringify({ timestamp: new Date().toISOString(), ...entry }) + "\n");
+}
+
+module.exports = { log };