unbound-cli 1.16.19 → 1.16.21

package/src/lib/flags.js

@@ -0,0 +1,231 @@
+/**
+ * Query building and row shaping for `unbound flags` and `unbound trace`.
+ * Pure functions — no network, no process state — so they are unit-testable.
+ */
+
+const { parseList, resolveWindow } = require('./analytics-query');
+
+// Outcome ids the backend's ?policy_actions= filter accepts on Terminal Runs.
+const TERMINAL_ACTIONS = ['block', 'approval', 'warn', 'audit'];
+
+// Actions a data security detection can carry (GatewayGuardrailAction.action).
+const DATA_SECURITY_ACTIONS = ['block', 'redact', 'route', 'audit'];
+
+// The backend's ?findings= values; `all` sends both.
+const FINDINGS = {
+  real: ['real'],
+  'false-positive': ['false_positive'],
+  all: ['real', 'false_positive'],
+};
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function resolveTraceId(value) {
+  const trace = String(value || '').trim().toLowerCase();
+  if (!UUID_RE.test(trace)) {
+    throw new Error(`Invalid trace ID "${value}". Expected a UUID such as 3f2a6c1e-8b7d-4e2f-9a1c-5d6e7f8a9b0c.`);
+  }
+  return trace;
+}
+
+function resolvePage(opts) {
+  if (opts.page === undefined) return 1;
+  const page = Number(opts.page);
+  if (!Number.isInteger(page) || page < 1) {
+    throw new Error(`Invalid --page "${opts.page}". Must be a positive integer.`);
+  }
+  return page;
+}
+
+function resolveChoices(flag, raw, allowed) {
+  return parseList(raw).map((value) => {
+    const match = allowed.find((a) => a === value.toLowerCase());
+    if (!match) throw new Error(`Invalid ${flag} "${value}". Must be one of: ${allowed.join(', ')}.`);
+    return match;
+  });
+}
+
+/** Query for /api/v1/analytics/terminal_commands/, narrowed to runs a policy flagged. */
+function buildTerminalQuery(opts) {
+  const actions = resolveChoices('--action', opts.action, TERMINAL_ACTIONS);
+  const query = {
+    ...resolveWindow(opts),
+    page: resolvePage(opts),
+    // Without an outcome filter the endpoint returns every run, flagged or not.
+    policy_actions: actions.length ? actions : TERMINAL_ACTIONS,
+  };
+  const lists = {
+    policy_ids: parseList(opts.policy),
+    tool_types: parseList(opts.tool).map((t) => t.toUpperCase().replace(/-/g, '_')),
+    command_families: parseList(opts.family),
+  };
+  for (const [key, values] of Object.entries(lists)) {
+    if (values.length) query[key] = values;
+  }
+  if (opts.trace) query.search = resolveTraceId(opts.trace);
+  return query;
+}
+
+/** Query for /api/v1/analytics/guardrails/; guardrailIds are already resolved from names. */
+function buildDataSecurityQuery(opts, guardrailIds = []) {
+  // A trace ID names one event, so it is shown whatever its finding unless --findings narrows it.
+  const findings = String(opts.findings || (opts.trace ? 'all' : 'real')).toLowerCase();
+  if (!FINDINGS[findings]) {
+    throw new Error(`Invalid --findings "${opts.findings}". Must be one of: ${Object.keys(FINDINGS).join(', ')}.`);
+  }
+  const query = {
+    ...resolveWindow(opts),
+    page: resolvePage(opts),
+    findings: FINDINGS[findings],
+  };
+  const actions = resolveChoices('--action', opts.action, DATA_SECURITY_ACTIONS);
+  if (actions.length) query.actions = actions;
+  if (guardrailIds.length) query.guardrails = guardrailIds;
+  if (opts.trace) query.search = resolveTraceId(opts.trace);
+  return query;
+}
+
+/** Map --guardrail names or IDs to IDs using /analytics/guardrails/filters/. */
+function resolveGuardrailIds(raw, available) {
+  return parseList(raw).map((value) => {
+    const match = (available || []).find(
+      (g) => String(g.id) === value || String(g.name).toLowerCase() === value.toLowerCase());
+    if (!match) {
+      const names = (available || []).map((g) => g.name).join(', ') || 'none';
+      throw new Error(`Unknown --guardrail "${value}". Available: ${names}.`);
+    }
+    return String(match.id);
+  });
+}
+
+/** Hide a detected secret or PII value; the backend returns it in clear. */
+function maskValue(value) {
+  const text = String(value ?? '');
+  if (!text) return '';
+  if (text.length < 10) return '****';
+  return `${text.slice(0, 2)}****${text.slice(-2)}`;
+}
+
+/** A data security log with every detected value masked and the raw prompt removed. */
+function redactDataSecurityLog(log) {
+  const { prompt, sensitive_contents: contents, ...rest } = log;
+  return {
+    ...rest,
+    sensitive_contents: (contents || []).map(maskValue),
+    sensitive_content_details: (log.sensitive_content_details || []).map((d) => ({
+      ...d,
+      sensitive_content: maskValue(d.sensitive_content),
+    })),
+  };
+}
+
+/** ISO timestamp as `YYYY-MM-DD HH:MM` in UTC; anything unparseable passes through. */
+function shortTime(value) {
+  const date = new Date(value);
+  return value && !Number.isNaN(date.getTime()) ? date.toISOString().slice(0, 16).replace('T', ' ') : (value || '');
+}
+
+// Free-text cells are cut before the table shares out the width, or a long
+// command takes the room the ID and trace ID columns need.
+function clipText(value, max, wide) {
+  const text = String(value ?? '');
+  return wide || text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+
+function policySummary(row) {
+  return (row.all_matched_policies || [])
+    .map((p) => (p.action ? `${p.name} (${p.action})` : p.name))
+    .join('; ');
+}
+
+function feedbackLabel(feedback) {
+  if (!feedback) return '';
+  if (feedback.feedback_type === 'reject') return 'False positive';
+  if (feedback.feedback_type === 'confirm') return 'Confirmed';
+  return feedback.feedback_type || '';
+}
+
+const TERMINAL_HEADERS = ['ID', 'Time (UTC)', 'User', 'Command', 'Policies', 'Outcome', 'Risk', 'Feedback', 'Trace ID'];
+
+function terminalRows(rows, { wide = false } = {}) {
+  return (rows || []).map((r) => [
+    String(r.id),
+    shortTime(r.created_at),
+    r.email || r.user || '',
+    clipText(r.terminal_command || r.path || '', 40, wide),
+    clipText(policySummary(r), 30, wide),
+    r.policy_action || '',
+    r.risk_score ?? '',
+    feedbackLabel(r.user_feedback),
+    r.trace_id || '',
+  ]);
+}
+
+const DATA_SECURITY_HEADERS = ['Action ID', 'Time (UTC)', 'User', 'AI Tool', 'Guardrail', 'Action', 'Value', 'False Positive', 'Trace ID'];
+
+/** One row per detection, because mark-fp takes a detection's action ID. */
+function dataSecurityRows(logs, { reveal = false, wide = false } = {}) {
+  const rows = [];
+  for (const log of logs || []) {
+    const base = [shortTime(log.timestamp), log.user_email || log.user_name || '', log.application_name || ''];
+    const details = log.sensitive_content_details || [];
+    if (details.length === 0) {
+      // Detections with no stored value carry no action ID in the response.
+      rows.push(['-', ...base, (log.guardrails || []).join(', '), (log.guardrail_actions || []).join(', '),
+        '', log.has_false_positive ? 'yes' : '', log.trace_id || '']);
+      continue;
+    }
+    for (const d of details) {
+      rows.push([String(d.action_id), ...base, d.guardrail_name || d.entity_type || '', d.action || '',
+        reveal ? clipText(d.sensitive_content, 40, wide) : maskValue(d.sensitive_content),
+        d.is_false_positive ? 'yes' : '', log.trace_id || '']);
+    }
+  }
+  return rows;
+}
+
+// Prompt text on a log can hold the same secret a data security guardrail found.
+const LOG_TEXT_FIELDS = ['userPrompt', 'systemPrompt', 'assistantPrompt', 'cleanedPrompt'];
+
+/** A log with its prompt text removed. */
+function redactLog(log) {
+  const copy = { ...log };
+  for (const field of LOG_TEXT_FIELDS) delete copy[field];
+  return copy;
+}
+
+const LOG_HEADERS = ['Log ID', 'Time (UTC)', 'User', 'AI Tool', 'Model', 'Status', 'User Prompt'];
+
+function logRows(prompts, { reveal = false, wide = false } = {}) {
+  return (prompts || []).map((p) => [
+    p.urlKey || p.id || '',
+    shortTime(p.requestInitializedAt),
+    (p.user && (p.user.email || p.user.name)) || '',
+    p.toolType || '',
+    (p.aiModel && p.aiModel.name) || '',
+    p.statusCode ?? '',
+    reveal ? clipText(p.userPrompt || '', 60, wide) : '(hidden)',
+  ]);
+}
+
+module.exports = {
+  DATA_SECURITY_ACTIONS,
+  DATA_SECURITY_HEADERS,
+  FINDINGS,
+  LOG_HEADERS,
+  TERMINAL_ACTIONS,
+  TERMINAL_HEADERS,
+  buildDataSecurityQuery,
+  buildTerminalQuery,
+  dataSecurityRows,
+  feedbackLabel,
+  logRows,
+  maskValue,
+  redactDataSecurityLog,
+  redactLog,
+  resolveGuardrailIds,
+  resolvePage,
+  resolveTraceId,
+  shortTime,
+  terminalRows,
+};

package/src/toolDetect.js

@@ -0,0 +1,239 @@
+// Detects whether an AI coding tool is actually present on this device, so
+// `unbound onboard` can set a tool up only where it is in use. Pi is the only
+// tool gated on detection today; every other tool has no signals here and is
+// always treated as installed.
+//
+// A tool counts as installed when ANY of its signals is found: its CLI binary,
+// or a file the tool writes for itself. Detection deliberately leans towards
+// "installed": a false positive only installs an unused extension, while a
+// false negative leaves a tool ungoverned. For the same reason detection
+// throws, instead of answering "not installed", when it found nothing but
+// could not inspect some place it needed to.
+//
+// The one thing a signal must never be is a path Unbound's own setup scripts
+// create (~/.pi/agent/extensions/unbound/). That would make pi look installed
+// on any device that was onboarded before, so the markers below are files only
+// pi itself writes.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const childProcess = require('child_process');
+
+// Where a per-user CLI lands, relative to a home. PATH alone is not enough:
+// under sudo and under the scheduled run it is a minimal system PATH that
+// lacks these. `.pi/agent/bin` is where pi's own installer puts its binary.
+const HOME_BIN_DIRS = [
+  '.pi/agent/bin',
+  '.local/bin',
+  '.bun/bin',
+  '.npm-global/bin',
+  '.volta/bin',
+  '.yarn/bin',
+  'AppData/Roaming/npm',
+  'AppData/Local/Microsoft/WinGet/Links',
+];
+
+const TOOL_SIGNALS = {
+  'pi': {
+    bins: ['pi'],
+    markers: ['.pi/agent/auth.json', '.pi/agent/sessions'],
+  },
+};
+
+// Directories under the users root that are not accounts. Linux has no entry:
+// a user named Shared or Guest there is a real one.
+const SKIP_HOME_NAMES = {
+  darwin: ['Shared', 'Guest'],
+  win32: ['Public', 'Default', 'Default User', 'All Users'],
+};
+
+// "Not there" and "could not look" are different answers. Only the first means
+// a signal is absent; anything else (no permission, an I/O error) is kept in
+// `errors` so the caller does not report a tool it could not rule out as
+// missing.
+const ABSENT = new Set(['ENOENT', 'ENOTDIR']);
+
+function stat(p, errors) {
+  try {
+    return fs.statSync(p);
+  } catch (err) {
+    if (!ABSENT.has(err.code)) errors.push(err);
+    return null;
+  }
+}
+
+function listDir(p, errors) {
+  try {
+    return fs.readdirSync(p);
+  } catch (err) {
+    if (!ABSENT.has(err.code)) errors.push(err);
+    return [];
+  }
+}
+
+function isLink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function pathDirs() {
+  return (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+}
+
+function machineBinDirs(platform) {
+  if (platform === 'win32') return [];
+  return ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/snap/bin'];
+}
+
+// Dirs the OS package manager owns, where a bare tool name may be another
+// program: Debian and Ubuntu ship a digits-of-pi calculator at /usr/bin/pi.
+function osPackageBinDirs(platform) {
+  return platform === 'win32' ? [] : ['/usr/bin', '/bin'];
+}
+
+function realDir(dir) {
+  try {
+    return fs.realpathSync(dir);
+  } catch {
+    return path.resolve(dir);
+  }
+}
+
+const HOME_PREFIXES = { darwin: '/Users/', linux: '/home/' };
+const ACCOUNT_LOOKUP_TIMEOUT_MS = 30000;
+
+// Home directories from the account database. A listing of the users root
+// alone misses a home that is not its direct child, such as /home/DOMAIN/alice.
+// The MDM setup scripts are Python and find their users with pwd.getpwall(),
+// so the same interpreter is asked the same question: detection then looks in
+// every home a setup script would install into. Windows has no such database;
+// its profile directories are the list.
+//
+// Two ways of getting no answer are told apart:
+// - Python is missing, or getpwall() itself fails. A setup script fails the
+//   same way, so it could not install into those homes either. Nothing
+//   reachable went unseen, and the users root listing is the whole answer.
+// - The lookup timed out or printed something unreadable. The database may be
+//   slow rather than down, and a setup script, which waits far longer, could
+//   still list those homes. That is kept in `errors` as a place that could
+//   not be inspected.
+function accountHomes(platform, errors) {
+  const prefix = HOME_PREFIXES[platform];
+  if (!prefix) return [];
+  const script = 'import json, pwd; print(json.dumps([e.pw_dir for e in pwd.getpwall()]))';
+  for (const python of ['python3', 'python']) {
+    let out;
+    try {
+      out = childProcess.execFileSync(python, ['-c', script], {
+        encoding: 'utf8', timeout: ACCOUNT_LOOKUP_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'ignore'],
+      });
+    } catch (err) {
+      if (err.code === 'ETIMEDOUT') {
+        errors.push(err);
+        return [];
+      }
+      continue;
+    }
+    try {
+      return JSON.parse(out).filter(home => typeof home === 'string' && home.startsWith(prefix));
+    } catch (err) {
+      errors.push(err);
+      return [];
+    }
+  }
+  return [];
+}
+
+// Every real user's home, for the sudo/MDM scope where the tools belong to
+// users other than the one running the command: every home the account
+// database names, and every directory under the users root for accounts the
+// database does not enumerate.
+function allUserHomes(platform, { errors = [], root, accounts } = {}) {
+  const usersRoot = root || (platform === 'win32'
+    ? path.join(process.env.SystemDrive || 'C:', path.sep, 'Users')
+    : platform === 'darwin' ? '/Users' : '/home');
+  const skip = new Set(SKIP_HOME_NAMES[platform] || []);
+  const candidates = [
+    ...(accounts || accountHomes(platform, errors)),
+    ...listDir(usersRoot, errors).filter(name => !name.startsWith('.')).map(name => path.join(usersRoot, name)),
+  ];
+  const homes = new Set([os.homedir()]);
+  for (const home of candidates) {
+    if (skip.has(path.basename(home))) continue;
+    const found = stat(home, errors);
+    if (found && found.isDirectory()) homes.add(home);
+  }
+  return [...homes];
+}
+
+function binDirsFor(ctx) {
+  const dirs = [...ctx.pathDirs, ...ctx.machineBinDirs];
+  for (const home of ctx.homes) {
+    for (const rel of HOME_BIN_DIRS) dirs.push(path.join(home, rel));
+    // nvm keeps one bin dir per installed Node version.
+    const nvm = path.join(home, '.nvm', 'versions', 'node');
+    for (const version of listDir(nvm, ctx.errors)) dirs.push(path.join(nvm, version, 'bin'));
+  }
+  return dirs;
+}
+
+function hasBinary(name, ctx) {
+  const names = ctx.platform === 'win32'
+    ? [`${name}.exe`, `${name}.cmd`, `${name}.ps1`, name]
+    : [name];
+  return binDirsFor(ctx).some((dir) => {
+    // In a dir the OS package manager owns, a regular file with the tool's
+    // name is the OS's own program. npm links a tool in, so there only a
+    // symlink counts.
+    const linksOnly = ctx.osPackageBinDirs.has(realDir(dir));
+    return names.some((n) => {
+      const p = path.join(dir, n);
+      if (!stat(p, ctx.errors)) return false;
+      return !linksOnly || isLink(p);
+    });
+  });
+}
+
+function isInstalled(toolName, ctx) {
+  const signals = TOOL_SIGNALS[toolName];
+  // An unknown tool has no way to be ruled out, so it is treated as installed.
+  if (!signals) return true;
+  if ((signals.bins || []).some(bin => hasBinary(bin, ctx))) return true;
+  if ((signals.markers || []).some(rel => ctx.homes.some(home => stat(path.join(home, rel), ctx.errors)))) return true;
+  return false;
+}
+
+/**
+ * Splits `toolNames` into those present on this device and those that are not.
+ * `allUsers` checks every user's home (sudo/MDM scope) instead of only the
+ * current user's. The remaining options exist so tests can point detection at
+ * a fixture tree instead of the real machine.
+ *
+ * Throws when a tool was not found but some place could not be inspected, so
+ * the caller can set the tool up instead of treating it as absent.
+ */
+function detectInstalledTools(toolNames, { allUsers = false, platform = process.platform, ...overrides } = {}) {
+  const errors = [];
+  const ctx = {
+    platform,
+    errors,
+    homes: overrides.homes || (allUsers ? allUserHomes(platform, { errors }) : [os.homedir()]),
+    pathDirs: overrides.pathDirs || pathDirs(),
+    machineBinDirs: overrides.machineBinDirs || machineBinDirs(platform),
+    osPackageBinDirs: new Set((overrides.osPackageBinDirs || osPackageBinDirs(platform)).map(realDir)),
+  };
+
+  const detected = [];
+  const missing = [];
+  for (const name of toolNames) {
+    (isInstalled(name, ctx) ? detected : missing).push(name);
+  }
+  if (missing.length && errors.length) throw errors[0];
+  return { detected, missing };
+}
+
+module.exports = { detectInstalledTools, allUserHomes, accountHomes, TOOL_SIGNALS };