@gtadi/k8s-node-debugger 1.0.0

package/LICENSE

@@ -0,0 +1,183 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and subsequently
+      incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an addendum to
+          the NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Contribution, either alone or combined with the Work.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Liability While Redistributing. While
+      redistributing the Work or Derivative Works thereof, You may
+      choose to offer, and charge a fee for, acceptance of support,
+      warranty, indemnity, or other liability obligations and/or rights
+      consistent with this License. However, in accepting such obligations,
+      You may act only on Your own behalf and on Your sole responsibility,
+      not on behalf of any other Contributor, and only if You agree to
+      indemnify, defend, and hold each Contributor harmless for any
+      liability incurred by, or claims asserted against, such Contributor
+      by reason of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Goutam Tadi
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,118 @@
+# k8s node debugger
+
+Spin up a privileged debug pod on any Kubernetes node and inspect its full network stack from a browser — no SSH required.
+
+One command creates the pod, opens the browser, and cleans up when you're done.
+
+```bash
+node bin/k8s-node-debugger.js <node-name>
+```
+
+## Screenshots
+
+### Firewall — iptables, nftables, and IPVS tabs
+
+![Firewall view](docs/screenshot-firewall.png)
+
+### Conntrack — live connection tracking
+
+![Conntrack view](docs/screenshot-conntrack-tabs.png)
+
+### Node Health — CPU, memory, disk, PSI, OOM, kubelet logs
+
+![Node Health view](docs/screenshot-health.png)
+
+## Install
+
+```bash
+git clone git@github.com:goutamtadi1/k8s-node-debugger.git
+cd k8s-node-debugger
+npm install
+```
+
+Requires `kubectl` on your PATH with an active kubeconfig. The debug image (`nicolaka/netshoot`) is pulled from Docker Hub on first use.
+
+## Usage
+
+```bash
+# list nodes in the current context
+node bin/k8s-node-debugger.js --list
+
+# debug a specific node (opens http://localhost:7878)
+node bin/k8s-node-debugger.js <node-name>
+
+# options
+node bin/k8s-node-debugger.js <node-name> \
+  --namespace kube-system \   # namespace for the debug pod (default: default)
+  --context my-ctx \          # kubeconfig context (default: current)
+  --port 9000 \               # UI port (default: 7878)
+  --keep \                    # leave the pod running after exit
+  --no-open                   # don't auto-open the browser
+```
+
+Press **Ctrl-C** to stop the server and delete the debug pod.
+
+## What it shows
+
+| Section | Probes |
+|---|---|
+| **Firewall** | iptables (all tables), iptables nat, nftables, IPVS — each as a tab |
+| **DNS** | resolv.conf, nsswitch.conf, /etc/hosts |
+| **Conntrack** | connection table, per-CPU stats, count/max gauge — each as a tab |
+| **Routing** | IPv4 routes, IPv6 routes, policy rules |
+| **Interfaces** | ip addr, ip link stats, ARP/neighbors |
+| **Sockets** | listening sockets, all TCP/UDP with process names |
+| **Kernel** | key net.* sysctls |
+| **Health** | CPU & load, memory, disk usage, PSI pressure, OOM kills, kubelet logs — each as a tab |
+| **GPU** | nvidia-smi status, GPU processes, DCGM health check |
+| **Terminal** | streaming terminal — run any command inside the pod (tcpdump, dig, ping, conntrack -E …) |
+
+### Node Health view features
+
+- **CPU & load** — load averages (1/5/15 min) vs core count, CPU model, steal %, top processes
+- **Memory** — used/available/cached/swap gauges from `/proc/meminfo`
+- **Disk usage** — `df -h` per filesystem with usage bars
+- **PSI pressure** — CPU, memory, and I/O stall metrics from `/proc/pressure/*`; colour-coded ok/warn/critical
+- **OOM kills** — parsed dmesg entries with process names and timestamps; empty means no OOM events since boot
+- **kubelet logs** — last 100 lines from journalctl, errors and warnings highlighted
+
+### iptables view features
+
+- Tabs per table (mangle · security · raw · filter · nat) with rule counts
+- Collapsible chain cards with default-policy badge and packet/byte counters
+- Colour-coded target badges: ACCEPT / DROP / REJECT / MASQUERADE / DNAT / LOG / MARK / k8s chain / …
+- Human-readable rule summaries with port service names (SSH, HTTPS, etcd, kubelet, k8s-API, NodePort range …)
+- Live search across all tables and chains
+- KUBE-SVC-\* / KUBE-SEP-\* chains collapsed by default; toggle with **K8s chains** button
+- Click any rule to reveal the raw `iptables-save` line
+- **Raw** toggle to fall back to plain text
+
+### conntrack view features
+
+- Stat cards: Total · TCP ESTABLISHED · TCP TIME\_WAIT · UDP · ICMP · total bytes
+- Protocol distribution bar and TCP state breakdown bar
+- Top 8 source IPs and top 8 destination ports (with service names)
+- Filter by protocol and TCP state; full-text search by IP, port, or state
+- Connection rows show state badge, ASSURED/UNREPLIED flag, src:port → dst:port, TTL, bytes, and a NAT tag when the reply source differs from the original destination
+- Paginated 200 at a time
+- Per-CPU stats table with drops/errors highlighted in red
+- Count/max capacity gauge (green → amber → red at 50% / 80%)
+
+## How it works
+
+The debug pod (`nicolaka/netshoot`) is created with:
+
+- `hostNetwork: true` — shares the node's network namespace
+- `hostPID: true` — allows `nsenter` to enter the host mount namespace
+- `privileged: true` — required for iptables / conntrack / tcpdump
+- Host root mounted at `/host` — for reading node files
+- Tolerations for all taints — schedules onto control-plane nodes too
+
+The server shells out to your local `kubectl`, so your active kubeconfig, current context, and any exec auth plugins (EKS, GKE, AKS) are reused automatically.
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `KUBECTL_BIN` | `kubectl` | Path to the kubectl binary |
+| `DEBUGGER_IMAGE` | `nicolaka/netshoot:latest` | Debug container image |

package/bin/k8s-node-debugger.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+'use strict';
+
+const k8s = require('../src/k8s');
+const { createServer } = require('../src/server');
+
+function parseArgs(argv) {
+  const opts = { namespace: 'default', port: 7878, open: true };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '-n':
+      case '--namespace':
+        opts.namespace = argv[++i];
+        break;
+      case '--context':
+        opts.context = argv[++i];
+        break;
+      case '--kubeconfig':
+        opts.kubeconfig = argv[++i];
+        break;
+      case '-p':
+      case '--port':
+        opts.port = parseInt(argv[++i], 10);
+        break;
+      case '--no-open':
+        opts.open = false;
+        break;
+      case '--keep':
+        opts.keep = true;
+        break;
+      case '-h':
+      case '--help':
+        opts.help = true;
+        break;
+      default:
+        positional.push(a);
+    }
+  }
+  opts.node = positional[0];
+  return opts;
+}
+
+function usage() {
+  console.log(`
+k8s-node-debugger — inspect a node's network stack from your browser.
+
+Usage:
+  k8s-node-debugger <node-name> [options]
+  k8s-node-debugger --list                 # list nodes and exit
+
+Options:
+  -n, --namespace <ns>    Namespace for the debug pod      (default: default)
+      --context <ctx>     kubeconfig context to use        (default: current)
+      --kubeconfig <path> Explicit kubeconfig path
+  -p, --port <port>       UI port                          (default: 7878)
+      --no-open           Don't auto-open the browser
+      --keep              Leave the debug pod running on exit
+  -h, --help              Show this help
+
+The active kubeconfig on your shell is used. A privileged pod
+(${k8s.DEBUG_IMAGE}) is created on the target node with
+hostNetwork/hostPID and the host root mounted at /host.
+`);
+}
+
+async function openBrowser(url) {
+  try {
+    const open = (await import('open')).default;
+    await open(url);
+  } catch {
+    /* optional dependency / headless env — ignore */
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (opts.help) return usage();
+
+  const baseOpts = {
+    context: opts.context,
+    kubeconfig: opts.kubeconfig,
+    namespace: opts.namespace,
+  };
+
+  if (opts.node === '--list' || opts.list) {
+    const nodes = await k8s.listNodes(baseOpts);
+    console.log(`\nNodes (context: ${(await k8s.currentContext(baseOpts)) || 'n/a'}):\n`);
+    for (const n of nodes) {
+      console.log(
+        `  ${n.ready ? '●' : '○'} ${n.name}` +
+          `${n.roles.length ? `  [${n.roles.join(',')}]` : ''}` +
+          `  ${n.internalIP || ''}  ${n.os || ''}`
+      );
+    }
+    console.log('');
+    return;
+  }
+
+  if (!opts.node) {
+    usage();
+    console.error('error: a node name is required (or use --list).\n');
+    process.exit(1);
+  }
+
+  const ctx = (await k8s.currentContext(baseOpts)) || 'current';
+  console.log(`\n▶ context: ${ctx}`);
+  console.log(`▶ target node: ${opts.node}`);
+  console.log(`▶ creating privileged debug pod (${k8s.DEBUG_IMAGE})...`);
+
+  let session;
+  try {
+    const { podName, namespace } = await k8s.createDebugPod(opts.node, baseOpts);
+    session = {
+      node: opts.node,
+      podName,
+      namespace,
+      context: opts.context,
+      kubeconfig: opts.kubeconfig,
+    };
+    console.log(`▶ pod: ${namespace}/${podName} — waiting for Ready...`);
+    await k8s.waitForPodReady(podName, baseOpts);
+    console.log('▶ pod is Ready.');
+  } catch (err) {
+    console.error(`\n✖ failed to start debug pod: ${err.message}`);
+    if (session && session.podName && !opts.keep) {
+      await k8s.deletePod(session.podName, baseOpts);
+    }
+    process.exit(1);
+  }
+
+  const server = createServer(session);
+
+  let cleaningUp = false;
+  const cleanup = async (code = 0) => {
+    if (cleaningUp) return;
+    cleaningUp = true;
+    server.close();
+    if (!opts.keep) {
+      console.log(`\n▶ deleting debug pod ${session.namespace}/${session.podName}...`);
+      await k8s.deletePod(session.podName, baseOpts);
+      console.log('▶ done.');
+    } else {
+      console.log(
+        `\n▶ leaving pod ${session.namespace}/${session.podName} running ` +
+          `(remove with: kubectl delete pod ${session.podName} -n ${session.namespace}).`
+      );
+    }
+    process.exit(code);
+  };
+
+  process.on('SIGINT', () => cleanup(0));
+  process.on('SIGTERM', () => cleanup(0));
+
+  server.listen(opts.port, () => {
+    const url = `http://localhost:${opts.port}`;
+    console.log(`\n✓ UI ready → ${url}`);
+    console.log('  (press Ctrl-C to stop and clean up the pod)\n');
+    if (opts.open) openBrowser(url);
+  });
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@gtadi/k8s-node-debugger",
+  "version": "1.0.0",
+  "description": "Spin up a privileged debug pod on a target Kubernetes node and inspect its network stack (iptables, resolv.conf, conntrack, routes, sockets) from a browser UI.",
+  "bin": {
+    "k8s-node-debugger": "bin/k8s-node-debugger.js"
+  },
+  "type": "commonjs",
+  "main": "src/server.js",
+  "scripts": {
+    "start": "node bin/k8s-node-debugger.js",
+    "test": "node --check bin/k8s-node-debugger.js && node --check src/server.js && node --check src/probes.js && node --check src/k8s.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "public/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "express": "^4.19.2",
+    "open": "^8.4.2",
+    "ws": "^8.18.0"
+  },
+  "license": "Apache-2.0"
+}