unbound-cli 1.14.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {

package/src/api.js

@@ -234,6 +234,101 @@ function postStream(path, { body, timeoutMs, onEvent } = {}) {
   });
 }
 
+/**
+ * Stream an absolute URL to a destination, sending no credentials.
+ *
+ * For presigned S3 downloads: the signature is in the URL, and an Authorization
+ * header would both break it and hand our API key to a third party. Redirects
+ * are refused, so a tampered response cannot steer the client at another host.
+ *
+ * `onHeaders` fires before the first byte is written so the caller can pick the
+ * destination. Resolves { headers, bytes }.
+ */
+function fetchToStream(absoluteUrl, { timeoutMs, onHeaders, transport } = {}) {
+  let url;
+  try {
+    url = new URL(absoluteUrl);
+  } catch {
+    return Promise.reject(new Error('The server returned an unusable download URL.'));
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    return Promise.reject(new Error(`Refusing to download from a ${url.protocol} URL.`));
+  }
+  const client = transport || (url.protocol === 'https:' ? https : http);
+
+  return new Promise((resolve, reject) => {
+    // The caller deletes the partial file when this rejects, and on Windows
+    // that fails while a write handle is open. A socket reset arrives on the
+    // request, not the response, so closing it in one place covers every path.
+    let destination;
+    const fail = (err) => {
+      if (destination && destination !== process.stdout) destination.destroy();
+      reject(err);
+    };
+
+    const req = client.request(url, { method: 'GET', headers: { 'User-Agent': USER_AGENT } }, (res) => {
+      const status = res.statusCode;
+
+      // Redirects are not followed. A presigned URL points straight at the
+      // signing endpoint, so a Location header means either a misconfigured
+      // bucket region or a response steering us at a host nobody vetted.
+      if (status >= 300 && status < 400) {
+        res.resume();
+        fail(new Error(
+          `The download server redirected to somewhere unexpected (HTTP ${status}). Nothing was downloaded.`));
+        return;
+      }
+
+      if (status < 200 || status >= 300) {
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => {
+          // S3 answers with XML, so the body is unhelpful to a user. An expired
+          // signature is the one case worth naming, since re-running fixes it.
+          const message = status === 403
+            ? 'This download link has expired. Run the export again.'
+            : `The download failed (HTTP ${status}).`;
+          fail(new ApiError(status, { error: message }));
+        });
+        return;
+      }
+
+      try {
+        destination = onHeaders(res.headers);
+      } catch (err) {
+        res.destroy();
+        fail(err);
+        return;
+      }
+
+      let bytes = 0;
+      res.on('data', (chunk) => { bytes += chunk.length; });
+      // A stream that dies mid-transfer must surface as an error, never as a
+      // silently short file.
+      res.on('error', (err) => fail(new Error(
+        `The download from ${url.host} was cut short (${err.code || err.message}). The file is incomplete.`)));
+      destination.on('error', (err) => { res.destroy(); reject(err); });
+
+      res.pipe(destination, { end: destination !== process.stdout });
+      const done = destination === process.stdout ? res : destination;
+      done.on(destination === process.stdout ? 'end' : 'finish', () => {
+        resolve({ headers: res.headers, bytes });
+      });
+    });
+
+    // Bounds silence, not the whole transfer: Node's socket timeout resets on
+    // every byte, which is what a multi-megabyte download needs.
+    const effectiveTimeout = Number.isInteger(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS;
+    req.setTimeout(effectiveTimeout, () => {
+      req.destroy();
+      fail(new Error(`The download from ${url.host} stalled for ${Math.round(effectiveTimeout / 1000)}s. Please try again.`));
+    });
+
+    req.on('error', (err) => fail(new Error(`Network error: ${err.message}`)));
+    req.end();
+  });
+}
+
 // Plain unauthenticated GET to an arbitrary URL. Returns the raw response body
 // as a UTF-8 string. Callers that want JSON must do JSON.parse() themselves.
 // Used by `unbound oacb` to fetch baseline JSONs and hook scripts from GitHub.
@@ -287,6 +382,7 @@ async function validateApiKey(apiKey, { baseUrl, timeoutMs = 3000 } = {}) {
 module.exports = {
   ApiError,
   get: (path, opts) => request('GET', path, opts),
+  fetchToStream,
   post: (path, opts) => request('POST', path, opts),
   postStream,
   put: (path, opts) => request('PUT', path, opts),

package/src/commands/analytics.js

@@ -0,0 +1,344 @@
+const fs = require('fs');
+const path = require('path');
+
+const api = require('../api');
+const config = require('../config');
+const output = require('../output');
+const downloads = require('../lib/downloads');
+const {
+  DEFAULT_LIMIT,
+  DEFAULT_TIME_WINDOW,
+  MAX_LIMIT,
+  MAX_TABLE_LIMIT,
+  TIME_WINDOWS,
+  buildQuery,
+  buildQueryString,
+  resolveFormat,
+} = require('../lib/analytics-query');
+
+const EXPORT_PATH = '/api/v1/analytics/export';
+const { MAX_EXPORT_ROWS, RETENTION_HOURS } = downloads;
+
+// Squeezing every column into one terminal makes all of them unreadable, so the
+// table view shows a curated subset. --format json/csv and --wide return all of
+// them; these names are matched against the server's `columns` array.
+const DATASETS = {
+  terminal: {
+    key: 'terminal-runs',
+    title: 'Terminal Runs',
+    summary: 'Terminal commands agents ran, with risk score and matched tool policies.',
+    tableColumns: ['Timestamp', 'User', 'Command Family', 'Command', 'Risk Score', 'Initiator', 'Matched Policies'],
+  },
+  'mcp-actions': {
+    key: 'mcp-actions',
+    title: 'MCP Actions',
+    summary: 'Individual MCP tool calls, with server, tool, targets and risk score.',
+    tableColumns: ['Timestamp', 'User', 'MCP Server', 'MCP Tool', 'Risk Score', 'Initiator', 'Matched Policies'],
+  },
+  unsanctioned: {
+    key: 'unsanctioned',
+    title: 'Unsanctioned Usage',
+    summary: 'MCP calls to servers your org has not sanctioned (blocked or warned).',
+    tableColumns: ['Timestamp', 'User', 'MCP Server', 'MCP Tool', 'Status'],
+  },
+  'mcp-servers': {
+    key: 'mcp-servers',
+    title: 'MCP Servers',
+    summary: 'One row per MCP server: action count and average risk. Use it to find --server values.',
+    tableColumns: ['MCP Server', 'Actions', 'Average Risk Score'],
+  },
+};
+
+/**
+ * Narrow a response to a dataset's table columns, preserving the server's order.
+ * Unknown names are ignored so an older CLI still renders a newer response.
+ */
+function selectTableColumns(dataset, columns, rows) {
+  const wanted = new Set(dataset.tableColumns || []);
+  const indices = columns.map((name, i) => (wanted.has(name) ? i : -1)).filter((i) => i >= 0);
+  if (indices.length === 0) return { columns, rows };
+  return {
+    columns: indices.map((i) => columns[i]),
+    rows: rows.map((row) => indices.map((i) => row[i])),
+    hidden: columns.length - indices.length,
+  };
+}
+
+const AGENT_HELP = `
+AGENTS / SCRIPTING
+  --format json is a stable contract. The envelope is:
+
+    {
+      "dataset":        "terminal-runs",
+      "columns":        ["Timestamp", "User", ...],   // header order
+      "rows":           [["2026-08-05T09:55:44Z", ...], ...],  // aligned to columns
+      "total_count":    1431,   // rows matching the filters, ignoring --limit
+      "returned_count": 20,
+      "offset":         0,
+      "next_offset":    20,     // pass as --offset for the next page
+      "has_more":       true
+    }
+
+  Every cell is a string. Page with --offset next_offset until has_more is false.
+  Do NOT compute the next offset as offset + returned_count: the server counts
+  source rows, and drops some while serializing, so the two differ.
+
+  Diagnostics go to stderr; stdout carries only the payload, so it is safe to pipe.
+  Exit code is 0 on success and 1 on any error.
+
+  $ unbound analytics tool-use terminal --format json --limit 100 \\
+      | jq -r '.rows[] | @tsv'
+  $ unbound analytics tool-use terminal --format json \\
+      | jq '[.columns, .rows[]] | @csv'
+`;
+
+const FILTER_HELP = `
+FILTERS (all accept comma-separated values)
+  --time-window <w>   ${TIME_WINDOWS.join(' | ')}
+                      Default ${DEFAULT_TIME_WINDOW}.
+  --start, --end      Custom range as YYYY-MM-DD (max 90 days). Not with --time-window.
+  --tool <types>      AI tool, e.g. CLAUDE_CODE,CURSOR,CODEX
+  --user <ids>        User IDs (see \`unbound users list\`)
+  --risk <levels>     Low, Medium, High
+  --policy <ids>      Tool policy IDs (see \`unbound policy tool list\`)
+
+OUTPUT
+  --format <f>        table (default) | json | csv
+  --json              Shorthand for --format json
+  -o, --output <file> Write to a file instead of stdout
+  --limit <n>         Rows to show (default ${DEFAULT_LIMIT}; max ${MAX_TABLE_LIMIT} table, ${MAX_LIMIT} json)
+  --offset <n>        Skip n rows — page through with --limit
+  --wide              Do not clip long values to the terminal width
+
+  csv contains EVERY matching row, not just --limit. It is prepared in the
+  background and can take a few minutes; the command waits and then saves it.
+  A selection over ${MAX_EXPORT_ROWS.toLocaleString()} rows is refused up front — narrow the window or filter.
+  With --format csv and no -o: writes a named .csv in the current directory when
+  run in a terminal, or streams to stdout when piped.
+  If you interrupt the wait, fetch the file within ${RETENTION_HOURS} hours with
+  \`unbound download get <job-id>\`.
+  \`unbound download\` exports Logs, Tasks and Users the same way.
+  The table view hides the widest columns; --wide or json/csv return all of them.
+`;
+
+function requireLogin() {
+  if (!config.isLoggedIn()) {
+    throw new Error('Not logged in. Run `unbound login` first.');
+  }
+}
+
+function writeOut(body, destination) {
+  if (!destination) {
+    process.stdout.write(body);
+    return null;
+  }
+  const resolved = path.resolve(destination);
+  fs.writeFileSync(resolved, body, 'utf8');
+  return resolved;
+}
+
+async function runCsv(dataset, opts) {
+  // The query string is passed whole: filters repeat keys (risk_levels,
+  // server, ...) and an object would collapse them to the last value.
+  const query = buildQuery(opts, { format: 'csv' });
+  const job = await downloads.startExportAt(
+    `${EXPORT_PATH}/${dataset.key}/?${buildQueryString(query)}`);
+  const finished = await downloads.waitForJob(job.id, dataset.title);
+  await downloads.downloadJob(finished, opts.output, dataset.title);
+}
+
+async function runJsonOrTable(dataset, opts, format) {
+  // -o is meaningful for json and csv, which produce a file. The table is laid
+  // out for a terminal, so accepting -o there would report a save that is not
+  // one of the formats anybody wants on disk.
+  if (format === 'table' && opts.output) {
+    throw new Error('-o needs --format json or --format csv. The table view prints to the terminal.');
+  }
+  const query = buildQuery(opts, { format });
+  const data = await api.get(`${EXPORT_PATH}/${dataset.key}/?${buildQueryString(query)}`);
+
+  if (format === 'json') {
+    const payload = JSON.stringify(data, null, 2);
+    const written = writeOut(`${payload}\n`, opts.output);
+    if (written) output.success(`Wrote ${dataset.title} JSON to ${written}`);
+    return;
+  }
+
+  const rows = data.rows || [];
+  if (rows.length === 0) {
+    const total = data.total_count || 0;
+    const offset = data.offset || 0;
+    // An empty page past the end is not an empty result set, and saying "no
+    // activity" hides the rows that are sitting at a lower offset.
+    output.info(
+      total > 0 && offset > 0
+        ? `No rows at --offset ${offset}. There are ${total.toLocaleString()} in total — lower the offset.`
+        : `No ${dataset.title} activity for this window and filter set.`
+    );
+    return;
+  }
+
+  const wide = Boolean(opts.wide);
+  const view = wide
+    ? { columns: data.columns || [], rows, hidden: 0 }
+    : selectTableColumns(dataset, data.columns || [], rows);
+
+  output.logTable(view.columns, view.rows, { wide });
+
+  const offset = data.offset || 0;
+  const total = data.total_count || rows.length;
+  // next_offset counts source rows read, which is not offset + rows.length
+  // whenever the server dropped rows while serializing.
+  const nextOffset = data.next_offset ?? offset + rows.length;
+  console.log('');
+  if (data.has_more ?? nextOffset < total) {
+    output.info(
+      `Showing ${offset + 1}-${offset + rows.length} of ${total.toLocaleString()}. ` +
+      `Page with --offset ${nextOffset}, or use --format csv to export every row.`
+    );
+  } else if (offset > 0) {
+    // Last page, not the only page: "all" here would read as the whole result
+    // set while a fraction of it is on screen.
+    output.info(`Showing ${offset + 1}-${offset + rows.length} of ${total.toLocaleString()}. End of results.`);
+  } else {
+    output.info(`Showing all ${total.toLocaleString()} row(s).`);
+  }
+  if (view.hidden) {
+    output.info(`${view.hidden} more column(s) hidden — use --wide, or --format json/csv for all of them.`);
+  }
+}
+
+function addSharedOptions(command, { server = false, family = false, initiator = false } = {}) {
+  command
+    .option('--time-window <window>', `Preset window (default ${DEFAULT_TIME_WINDOW})`)
+    .option('--start <date>', 'Custom range start, YYYY-MM-DD (use with --end)')
+    .option('--end <date>', 'Custom range end, YYYY-MM-DD (use with --start)')
+    .option('--tool <types>', 'Filter by AI tool type, comma-separated')
+    .option('--user <ids>', 'Filter by user ID, comma-separated')
+    .option('--risk <levels>', 'Filter by risk level: Low, Medium, High')
+    .option('--policy <ids>', 'Filter by tool policy ID, comma-separated');
+
+  if (family) command.option('--family <families>', 'Filter by command family, comma-separated');
+  if (server) command.option('--server <names>', 'Filter by MCP service or server name, comma-separated');
+  if (initiator) command.option('--initiator <who>', 'Filter by initiator: user, agent, unknown');
+
+  return command
+    // No commander default: resolveFormat needs to tell "unset" from an
+    // explicit --format table, or --json would look like a contradiction.
+    .option('--format <format>', 'Output format: table (default), json or csv')
+    .option('--json', 'Shorthand for --format json')
+    .option('-o, --output <file>', 'Write output to a file instead of stdout')
+    .option('--limit <n>', `Rows to display (default ${DEFAULT_LIMIT}; max ${MAX_TABLE_LIMIT} table, ${MAX_LIMIT} json)`)
+    .option('--offset <n>', 'Skip n rows before displaying')
+    .option('--wide', 'Print full values instead of clipping to terminal width');
+}
+
+function attach(parent, name, dataset, help, flags) {
+  const command = parent
+    .command(name)
+    .description(dataset.summary);
+  addSharedOptions(command, flags);
+  command.addHelpText('after', help);
+  command.action(async (opts) => {
+    let format = 'table';
+    try {
+      requireLogin();
+      format = resolveFormat(opts);
+      if (format === 'csv') {
+        await runCsv(dataset, opts);
+      } else {
+        await runJsonOrTable(dataset, opts, format);
+      }
+    } catch (err) {
+      output.error(format === 'csv'
+        ? downloads.describeError(err, `${dataset.title} export`)
+        : downloads.describeError(err, `Analytics > Tool Use`, { listing: true }));
+      process.exitCode = 1;
+    }
+  });
+  return command;
+}
+
+function register(program) {
+  const analytics = program
+    .command('analytics')
+    .description('Read Analytics data from the command line. Mirrors the Analytics section of the dashboard.');
+
+  const toolUse = analytics
+    .command('tool-use')
+    .description('Agentic activity: terminal commands and MCP tool calls (Analytics > Tool Use).')
+    .addHelpText('after', `
+DATASETS
+  terminal        ${DATASETS.terminal.summary}
+  mcp-actions     ${DATASETS['mcp-actions'].summary}
+  unsanctioned    ${DATASETS.unsanctioned.summary}
+  mcp-servers     ${DATASETS['mcp-servers'].summary}
+
+Examples:
+  $ unbound analytics tool-use terminal
+  $ unbound analytics tool-use mcp-servers
+  $ unbound analytics tool-use mcp-actions --server claude_ai_notion
+  $ unbound analytics tool-use unsanctioned --format csv -o blocked.csv
+
+Admin role required — for listing as well as CSV export.
+${FILTER_HELP}${AGENT_HELP}`);
+
+  attach(toolUse, 'terminal', DATASETS.terminal, `
+Columns:
+  Timestamp, User, Email, AI Tool, Command Family, All Command Families,
+  Command, User Prompt, Risk Score, Risk Reason, Initiator, Matched Policies
+
+Examples:
+  $ unbound analytics tool-use terminal
+  $ unbound analytics tool-use terminal --risk High --time-window SEVEN_DAYS
+  $ unbound analytics tool-use terminal --family git_action,delete_file --wide
+  $ unbound analytics tool-use terminal --tool CLAUDE_CODE --initiator agent
+  $ unbound analytics tool-use terminal --start 2026-07-01 --end 2026-07-31 \\
+      --format csv -o july-terminal-runs.csv
+  $ unbound analytics tool-use terminal --limit 50 --offset 50
+${FILTER_HELP}${AGENT_HELP}`, { family: true, initiator: true });
+
+  attach(toolUse, 'mcp-actions', DATASETS['mcp-actions'], `
+Columns:
+  Timestamp, User, Email, AI Tool, MCP Server, MCP Tool, Targets,
+  User Prompt, Risk Score, Risk Reason, Initiator, Matched Policies
+
+--server matches the server name case-insensitively.
+Run \`unbound analytics tool-use mcp-servers\` to see the available values.
+
+Examples:
+  $ unbound analytics tool-use mcp-actions
+  $ unbound analytics tool-use mcp-actions --server claude_ai_notion
+  $ unbound analytics tool-use mcp-actions --server claude_ai_notion --risk High
+  $ unbound analytics tool-use mcp-actions --server claude_ai_slack,claude_ai_notion --format csv -o mcp.csv
+${FILTER_HELP}${AGENT_HELP}`, { server: true, initiator: true });
+
+  attach(toolUse, 'unsanctioned', DATASETS.unsanctioned, `
+Columns:
+  Timestamp, User, Email, AI Tool, MCP Server, MCP Tool,
+  Status, Sanction Message, User Prompt
+
+Status is Blocked or Warned, matching the Unsanctioned Usage lens in the dashboard.
+
+Examples:
+  $ unbound analytics tool-use unsanctioned
+  $ unbound analytics tool-use unsanctioned --time-window THIRTY_DAYS
+  $ unbound analytics tool-use unsanctioned --format csv -o unsanctioned.csv
+${FILTER_HELP}${AGENT_HELP}`, { server: true });
+
+  attach(toolUse, 'mcp-servers', DATASETS['mcp-servers'], `
+Columns:
+  MCP Server, Actions, Average Risk Score
+
+Use this to find the value to pass to --server on \`mcp-actions\`.
+
+Examples:
+  $ unbound analytics tool-use mcp-servers
+  $ unbound analytics tool-use mcp-servers --limit 50
+  $ unbound analytics tool-use mcp-servers --format csv -o mcp-servers.csv
+${FILTER_HELP}${AGENT_HELP}`, { server: true });
+
+  return analytics;
+}
+
+module.exports = { register, DATASETS, selectTableColumns };