unbound-cli 1.6.3 → 1.6.5

package/README.md

@@ -299,3 +299,28 @@ All list/get commands support `--json` for machine-readable JSON output.
 unbound policy list --json
 unbound users list --json | jq '.members[].email'
 ```
+
+## Onboarding failure reporting & telemetry
+
+So onboarding steps never fail silently, the CLI:
+
+- **Fails loud.** A failed setup or discovery step exits non-zero (no fake
+  successes). A broken script download (GitHub down/404/empty body) is detected
+  before the script runs, so it can no longer "succeed" with an empty script.
+- **Reports failures to the backend.** When a setup step fails, the CLI makes a
+  best-effort `POST /api/v1/setup/failed/` with the failing step name and exit
+  code so the failure is visible server-side. The device is identified by
+  `os.hostname()` (used only as an org-scoped key, not a true hardware serial).
+  This report is best-effort: if it can't be sent (offline / rate-limited), the
+  CLI still shows the real error and keeps its non-zero exit code.
+
+### Error reporting (Sentry) — opt-out
+
+Crash/error reporting is **off by default** and only activates when a DSN is
+configured. Secrets (API/discovery keys), home-directory paths, and your OS
+username are scrubbed before any event is sent.
+
+| Env var | Effect |
+|---------|--------|
+| `UNBOUND_CLI_SENTRY_DSN` | Set to enable error reporting. **Unset = fully disabled** (nothing initializes, no network). |
+| `UNBOUND_TELEMETRY` | Set to `0`, `false`, or `no` to disable error reporting even if a DSN is configured. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "1.6.3",
+  "version": "1.6.5",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {
@@ -21,6 +21,7 @@
   "private": false,
   "dependencies": {
     "@iarna/toml": "^2.2.5",
+    "@sentry/node": "^10.59.0",
     "commander": "^12.1.0",
     "open": "^10.1.0"
   },

package/scripts/verify-nuke-ubuntu.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# WEB-4922 end-to-end verification: `sudo unbound nuke` removes /opt/unbound
+# (plus newsyslog conf + log dir) on Linux when invoked as root.
+#
+# Runs ENTIRELY inside a fresh ubuntu:24.04 container — the host's filesystem
+# is mounted read-only and the repo is copied into the container before
+# `npm link`, so the host's real /opt/unbound (if any) is never touched.
+#
+# Usage: ./scripts/verify-nuke-ubuntu.sh
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+if ! command -v docker >/dev/null 2>&1; then
+  echo "FAIL: docker not on PATH" >&2
+  exit 2
+fi
+
+echo "Running WEB-4922 nuke verification inside ubuntu:24.04..."
+echo "Host repo (mounted read-only): $REPO_ROOT"
+echo
+
+docker run --rm \
+  -v "$REPO_ROOT:/repo:ro" \
+  ubuntu:24.04 bash -c '
+set -euo pipefail
+
+# Refuse to run on a host (e.g. if someone copy-pastes this heredoc into a
+# terminal): /.dockerenv is created by the docker engine in every container
+# but never exists on a real host.
+[ -f /.dockerenv ] || { echo "FAIL: refusing to run outside a container" >&2; exit 99; }
+
+echo "[setup] installing node + curl..."
+export DEBIAN_FRONTEND=noninteractive
+apt-get update -qq >/dev/null
+apt-get install -y -qq curl ca-certificates >/dev/null
+curl -fsSL https://deb.nodesource.com/setup_20.x | bash - >/dev/null 2>&1
+apt-get install -y -qq nodejs >/dev/null
+
+# Copy repo into a writable spot — host mount is read-only.
+cp -R /repo /work
+cd /work
+echo "[setup] npm link..."
+npm link --silent >/dev/null 2>&1
+
+# Fake the pkg layout from setup/packaging/pkg/postinstall.
+echo "[setup] faking /opt/unbound + newsyslog + log dir..."
+mkdir -p /opt/unbound/0.1.5/unbound-hook
+mkdir -p /opt/unbound/0.1.5/unbound-discovery
+mkdir -p /opt/unbound/etc
+echo "#!fake binary" > /opt/unbound/0.1.5/unbound-hook/unbound-hook
+echo "#!fake binary" > /opt/unbound/0.1.5/unbound-discovery/unbound-discovery
+echo "{}" > /opt/unbound/etc/discovery.json
+ln -sfn /opt/unbound/0.1.5 /opt/unbound/current
+mkdir -p /etc/newsyslog.d
+echo "# rotate" > /etc/newsyslog.d/ai.getunbound.conf
+mkdir -p /var/log/unbound
+echo "old log" > /var/log/unbound/discovery.log
+
+echo
+echo "===== BEFORE ====="
+ls -la /opt/unbound
+ls -la /etc/newsyslog.d/ai.getunbound.conf
+ls -la /var/log/unbound
+echo
+
+# EUID 0 inside the container, so hasRootPrivileges() returns true and the
+# includeMdm branch (where removeBinaryInstall is called) runs.
+# Per-tool MDM clears WILL fail (no real tool installs) — that is best-effort
+# and must not abort the binary install removal.
+echo "[run] unbound nuke --yes (per-tool clears may noisily fail; that is fine)"
+unbound nuke --yes || true
+
+echo
+echo "===== AFTER ====="
+ls -la /opt/unbound 2>/dev/null || echo "(gone) /opt/unbound"
+ls -la /etc/newsyslog.d/ai.getunbound.conf 2>/dev/null || echo "(gone) /etc/newsyslog.d/ai.getunbound.conf"
+ls -la /var/log/unbound 2>/dev/null || echo "(gone) /var/log/unbound"
+echo
+
+FAIL=0
+[ ! -e /opt/unbound ]                           || { echo "FAIL: /opt/unbound survived"; FAIL=1; }
+[ ! -e /etc/newsyslog.d/ai.getunbound.conf ]    || { echo "FAIL: newsyslog conf survived"; FAIL=1; }
+[ ! -e /var/log/unbound ]                       || { echo "FAIL: log dir survived"; FAIL=1; }
+if [ "$FAIL" = "0" ]; then
+  echo "PASS: WEB-4922 Ubuntu container — all binary install artifacts removed"
+  exit 0
+else
+  echo "FAIL: at least one artifact survived"
+  exit 1
+fi
+'

package/src/api.js

@@ -29,7 +29,9 @@ class ApiError extends Error {
   }
 }
 
-function request(method, path, { body, query, apiKey, baseUrl } = {}) {
+const DEFAULT_TIMEOUT_MS = 30000;
+
+function request(method, path, { body, query, apiKey, baseUrl, timeoutMs } = {}) {
   // Explicit baseUrl wins over env-var-aware getBaseUrl(). Used by login /
   // setup / onboard so a user's just-passed --backend-url isn't shadowed by a
   // stale UNBOUND_API_URL env var from a prior shell session.
@@ -83,9 +85,13 @@ function request(method, path, { body, query, apiKey, baseUrl } = {}) {
       });
     });
 
-    req.setTimeout(30000, () => {
+    // Callers may bound a request more tightly than the default (e.g. the
+    // best-effort failure ledger uses 3s so a hung backend can't delay surfacing
+    // the user's real error).
+    const effectiveTimeout = Number.isInteger(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS;
+    req.setTimeout(effectiveTimeout, () => {
       req.destroy();
-      reject(new Error(`Request to ${url.host} timed out after 30s. Please try again.`));
+      reject(new Error(`Request to ${url.host} timed out after ${Math.round(effectiveTimeout / 1000)}s. Please try again.`));
     });
 
     req.on('error', (err) => {

package/src/auth.js

@@ -17,7 +17,7 @@ const { getDeviceSerial } = require('./device-serial');
  * @param {string} frontendUrl - The frontend URL to open
  * @returns {Promise<{email: string, orgName: string}>}
  */
-async function loginWithBrowser(frontendUrl) {
+async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
   const server = http.createServer();
   let callbackResolve;
   let callbackReject;
@@ -27,11 +27,31 @@ async function loginWithBrowser(frontendUrl) {
     callbackReject = reject;
   });
 
+  // server.close() only stops accepting NEW connections; it does NOT destroy a
+  // socket the browser is holding open via HTTP/1.1 keep-alive. That socket stays
+  // ref'd and keeps the event loop (the whole CLI) alive ~60s until the browser
+  // drops it. Responses set `Connection: close` so the answered socket closes
+  // gracefully once its body flushes; this also force-drops any idle / pre-connected
+  // / timed-out socket so the process exits immediately. closeAllConnections is
+  // Node >=18.2 — guard for the package's >=18 engine floor.
+  //
+  // Calling this synchronously right after res.end() is safe ONLY because the
+  // callback responses are a few hundred bytes of static HTML — they fit in the
+  // socket send buffer, so the body reaches the kernel before closeAllConnections
+  // destroys the socket. If these pages ever grow to multi-KB (inline assets,
+  // styling), defer teardown to res.on('finish') to avoid truncating the response.
+  function shutdownServer() {
+    server.close();
+    if (typeof server.closeAllConnections === 'function') {
+      server.closeAllConnections();
+    }
+  }
+
   server.on('request', (req, res) => {
     const url = new URL(req.url, `http://localhost`);
 
     if (url.pathname !== '/callback') {
-      res.writeHead(404);
+      res.writeHead(404, { 'Connection': 'close' });
       res.end('Not found');
       return;
     }
@@ -41,10 +61,10 @@ async function loginWithBrowser(frontendUrl) {
     const orgName = url.searchParams.get('org');
 
     if (!apiKey) {
-      res.writeHead(400, { 'Content-Type': 'text/html' });
+      res.writeHead(400, { 'Content-Type': 'text/html', 'Connection': 'close' });
       res.end('<html><body><h2>Authentication failed</h2><p>No API key received. Please try again.</p></body></html>');
       callbackReject(new Error('No API key received in callback'));
-      server.close();
+      shutdownServer();
       return;
     }
 
@@ -54,11 +74,11 @@ async function loginWithBrowser(frontendUrl) {
     if (orgName) cfg.org_name = orgName;
     config.writeConfig(cfg);
 
-    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.writeHead(200, { 'Content-Type': 'text/html', 'Connection': 'close' });
     res.end('<html><body><h2>Authentication successful!</h2><p>You can close this tab and return to the terminal.</p></body></html>');
 
     callbackResolve({ email, orgName });
-    server.close();
+    shutdownServer();
   });
 
   await new Promise((resolve, reject) => {
@@ -70,7 +90,7 @@ async function loginWithBrowser(frontendUrl) {
   const callbackUrl = `http://localhost:${port}/callback`;
   const authUrl = `${frontendUrl}/automations/api-key-callback?callback_url=${encodeURIComponent(callbackUrl)}&app_type=cli`;
 
-  const open = (await import('open')).default;
+  const open = openFn || (await import('open')).default;
 
   output.info('Opening browser for authentication...');
   output.info(`If the browser does not open, visit:\n${authUrl}`);
@@ -84,7 +104,7 @@ async function loginWithBrowser(frontendUrl) {
 
   const timeout = setTimeout(() => {
     callbackReject(new Error('Authentication timed out after 120 seconds'));
-    server.close();
+    shutdownServer();
   }, 120_000);
 
   const reminder = setInterval(() => {

package/src/commands/discover.js

@@ -4,7 +4,8 @@ const path = require('path');
 const os = require('os');
 const config = require('../config');
 const output = require('../output');
-const { shellEscape, downloadToFile, DISCOVER_BASE_URL } = require('../utils');
+const telemetry = require('../telemetry');
+const { shellEscape, downloadToFile, withSecureTempFile, DISCOVER_BASE_URL } = require('../utils');
 const LAUNCH_AGENT_LABEL = 'ai.getunbound.discovery';
 
 // install.sh exits with this code when the OS isn't supported for discovery
@@ -46,29 +47,46 @@ function isRoot() {
  * install.ps1 automatically; any other bash-only script (e.g.
  * setup-scheduled-scan.sh) remains unsupported on native Windows.
  */
-function runDiscoveryScript(scriptName, args) {
+async function runDiscoveryScript(scriptName, args) {
   if (isWindowsNative()) {
     return runDiscoveryScriptWindows(scriptName, args);
   }
-  return new Promise((resolve, reject) => {
-    const url = `${DISCOVER_BASE_URL}/${scriptName}`;
-    const cmd = `curl -fsSL "${url}" | bash -s -- ${args}`;
-
-    const child = spawn(cmd, { shell: true, stdio: 'inherit' });
-
-    child.on('close', (code) => {
-      const result = classifyDiscoveryExit(code);
-      if (result === 'failure') {
-        reject(new Error(`Discovery script failed with exit code ${code}`));
-        return;
-      }
-      if (result === 'unsupported') {
-        output.warn('AI tool discovery is not supported on this operating system. Skipping the scan — the Unbound CLI works normally.');
-      }
-      resolve();
+  // Download-then-run instead of `curl -fsSL ... | bash -s --`. The pipe's exit
+  // code was bash's, not curl's, and /bin/sh=dash has no pipefail — so a failed
+  // download (GitHub down/404/partial) silently ran an empty/partial script and
+  // exited 0 = fake success. downloadToFile rejects on non-200/empty body BEFORE
+  // bash runs, closing that hole. Mirrors runDiscoveryScriptWindows.
+  const url = `${DISCOVER_BASE_URL}/${scriptName}`;
+  // The downloaded script is executed (as root under `sudo unbound …`), so it
+  // must live in a per-run PRIVATE temp dir an attacker can't pre-create or
+  // symlink. withSecureTempFile creates it (mode 0700) and cleans it up after.
+  return withSecureTempFile('.sh', async (tmp) => {
+    try {
+      await downloadToFile(url, tmp);
+    } catch (err) {
+      err.downloadFailed = true;
+      throw err;
+    }
+    return await new Promise((resolve, reject) => {
+      const child = spawn('bash', [tmp, ...parsePosixArgs(args)], {
+        stdio: 'inherit',
+        shell: false,
+      });
+      child.on('close', (code) => {
+        const result = classifyDiscoveryExit(code);
+        if (result === 'failure') {
+          const e = new Error(`Discovery script failed with exit code ${code}`);
+          e.exitCode = code;
+          reject(e);
+          return;
+        }
+        if (result === 'unsupported') {
+          output.warn('AI tool discovery is not supported on this operating system. Skipping the scan — the Unbound CLI works normally.');
+        }
+        resolve();
+      });
+      child.on('error', reject);
     });
-
-    child.on('error', reject);
   });
 }
 
@@ -101,17 +119,18 @@ async function runDiscoveryScriptWindows(scriptName, args) {
   }
   const winScript = 'install.ps1';
   const url = `${DISCOVER_BASE_URL}/${winScript}`;
-  const tmp = path.join(os.tmpdir(), `unbound-discover-${Date.now()}-${Math.random().toString(36).slice(2)}.ps1`);
-  try {
-    await downloadToFile(url, tmp);
-  } catch (err) {
-    throw new Error(
-      `${err.message}. Native Windows support requires ${winScript} in the coding-discovery-tool repo.`
-    );
-  }
-  // Map posix flags to PowerShell-style parameter names (install.ps1's convention).
-  const argv = parsePosixArgs(args).map((a) => a === '--api-key' ? '-ApiKey' : a === '--domain' ? '-Domain' : a);
-  try {
+  // Same hardening as the bash path: download into a per-run private temp dir
+  // and run from there, then clean up.
+  return withSecureTempFile('.ps1', async (tmp) => {
+    try {
+      await downloadToFile(url, tmp);
+    } catch (err) {
+      throw new Error(
+        `${err.message}. Native Windows support requires ${winScript} in the coding-discovery-tool repo.`
+      );
+    }
+    // Map posix flags to PowerShell-style parameter names (install.ps1's convention).
+    const argv = parsePosixArgs(args).map((a) => a === '--api-key' ? '-ApiKey' : a === '--domain' ? '-Domain' : a);
     await new Promise((resolve, reject) => {
       const child = spawn(
         'powershell',
@@ -131,9 +150,7 @@ async function runDiscoveryScriptWindows(scriptName, args) {
       });
       child.on('error', reject);
     });
-  } finally {
-    try { fs.unlinkSync(tmp); } catch { /* best-effort */ }
-  }
+  });
 }
 
 /**
@@ -197,8 +214,10 @@ Examples:
   $ unbound discover --api-key KEY                   Scan current user only
   $ sudo unbound discover --api-key KEY --domain https://custom.backend.com
 `)
-    .action(async (opts) => {
+    .action(telemetry.wrapAction('discover', async (opts) => {
       let scanSucceeded = false;
+      // Register the discovery key so beforeSend redacts it from any event.
+      telemetry.rememberSecret(opts.apiKey);
       try {
         if (!opts.apiKey) {
           output.error('--api-key is required.');
@@ -224,6 +243,7 @@ Examples:
         console.log('');
         output.success('Discovery complete');
       } catch (err) {
+        telemetry.captureError(err, { tags: { flow: 'discover' } });
         output.error(err.message);
         // Hint only when the scan completed and the user actually asked for
         // cron setup — guards against a future code path between scanSucceeded
@@ -236,7 +256,7 @@ Examples:
         }
         process.exitCode = 1;
       }
-    });
+    }));
 
   // --- Schedule / Unschedule / Status ---
 

package/src/commands/onboard.js

@@ -1,6 +1,7 @@
 const { Option } = require('commander');
 const config = require('../config');
 const output = require('../output');
+const telemetry = require('../telemetry');
 const { ensureLoggedIn } = require('../auth');
 const { runSetupAllBundle, runMdmSetupAllBundle, hasRootPrivileges, ALL_TOOLS, MDM_ALL_TOOLS } = require('./setup');
 const { runDiscoveryScan } = require('./discover');
@@ -55,9 +56,13 @@ Examples:
   $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --backfill
   $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --set-cron
 `)
-    .action(async (opts) => {
+    .action(telemetry.wrapAction('onboard', async (opts) => {
       const apiKeyOpt = opts.apiKey || opts.adminApiKey || process.env.UNBOUND_API_KEY;
       const discoveryKeyOpt = opts.discoveryKey || process.env.UNBOUND_DISCOVERY_KEY;
+      // Register the concrete secret values so beforeSend redacts the exact
+      // strings (not just key-shaped guesses) from any captured event.
+      telemetry.rememberSecret(apiKeyOpt);
+      telemetry.rememberSecret(discoveryKeyOpt);
       const isMdm = hasRootPrivileges();
 
       if (!discoveryKeyOpt) {
@@ -109,7 +114,10 @@ Examples:
           const { ok, skipped } = await runMdmSetupAllBundle(adminApiKey, {
             backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
           });
-          if (!ok) return;
+          // A failed setup must NOT report onboarding success. runBatch already
+          // reported the failure to the ledger and set exitCode; make the
+          // non-zero exit explicit here so onboard never returns 0 on failure.
+          if (!ok) { process.exitCode = 1; return; }
           setupSucceeded = true;
 
           console.log('');
@@ -131,7 +139,10 @@ Examples:
           const { ok, skipped } = await runSetupAllBundle(apiKey, {
             backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
           });
-          if (!ok) return;
+          // A failed setup must NOT report onboarding success. runBatch already
+          // reported the failure to the ledger and set exitCode; make the
+          // non-zero exit explicit here so onboard never returns 0 on failure.
+          if (!ok) { process.exitCode = 1; return; }
           setupSucceeded = true;
 
           console.log('');
@@ -173,6 +184,9 @@ Examples:
           ? 'Onboarding complete — tools managed by MDM were skipped (see above)'
           : 'Onboarding complete');
       } catch (err) {
+        // Capture the real onboarding error to Sentry (no-op unless enabled).
+        // The action catches its own errors, so capture here before we swallow.
+        telemetry.captureError(err, { tags: { flow: 'onboard' } });
         if (!err.displayed) output.error(err.message);
         const suffix = domainHintSuffix(discoveryDomain);
         const sudo = isMdm ? 'sudo ' : '';
@@ -193,7 +207,7 @@ Examples:
         }
         process.exitCode = 1;
       }
-    });
+    }));
 
   // --- onboard unschedule ---