unbound-cli 1.16.23 → 1.16.25

package/package.json

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

package/src/commands/analytics.js

@@ -41,6 +41,12 @@ const DATASETS = {
     summary: 'MCP calls to servers your org has not sanctioned (blocked or warned).',
     tableColumns: ['Timestamp', 'User', 'MCP Server', 'MCP Tool', 'Status'],
   },
+  unofficial: {
+    key: 'unofficial',
+    title: 'Unofficial MCP Usage',
+    summary: 'MCP calls blocked because the publisher is not an official one.',
+    tableColumns: ['Timestamp', 'User', 'MCP Server', 'MCP Tool', 'Status'],
+  },
   'mcp-servers': {
     key: 'mcp-servers',
     title: 'MCP Servers',
@@ -272,6 +278,7 @@ DATASETS
   terminal        ${DATASETS.terminal.summary}
   mcp-actions     ${DATASETS['mcp-actions'].summary}
   unsanctioned    ${DATASETS.unsanctioned.summary}
+  unofficial      ${DATASETS.unofficial.summary}
   mcp-servers     ${DATASETS['mcp-servers'].summary}
 
 Examples:
@@ -326,6 +333,21 @@ Examples:
   $ unbound analytics tool-use unsanctioned --format csv -o unsanctioned.csv
 ${FILTER_HELP}${AGENT_HELP}`, { server: true });
 
+  attach(toolUse, 'unofficial', DATASETS.unofficial, `
+Columns:
+  Timestamp, User, Email, AI Tool, MCP Server, MCP Tool,
+  Status, Sanction Message, User Prompt
+
+A narrower slice of unsanctioned: only the calls blocked because the MCP
+publisher is not an official one. No dashboard page shows this on its own,
+so the CLI and the API are the only ways to read it.
+
+Examples:
+  $ unbound analytics tool-use unofficial
+  $ unbound analytics tool-use unofficial --time-window THIRTY_DAYS
+  $ unbound analytics tool-use unofficial --format csv -o unofficial.csv
+${FILTER_HELP}${AGENT_HELP}`, { server: true });
+
   attach(toolUse, 'mcp-servers', DATASETS['mcp-servers'], `
 Columns:
   MCP Server, Actions, Average Risk Score

package/src/commands/download.js

@@ -57,6 +57,36 @@ FILTERS
   than failing — 'tool_type=CURSOR' returns every tool. An invalid VALUE for a
   known key IS rejected, with the supported values listed. Run --check first and
   confirm the count moved.
+
+FILTER VALUES
+  Most filters take IDs or names. These take a fixed vocabulary:
+
+    weeks            ai-usage kinds only: 4, 8 or 12 (default 8). These cover
+                     whole weeks, so --last and --start/--end do not apply.
+    status           ai-usage-users-export: active | silent
+    band             ai-usage-teams-export: high | mid | low
+    trend            ai-usage-teams-export: up | down | flat
+    enforcement      users-export, analytics-tasks-export. Repeatable:
+                     data:audit, data:block, mcp:audit, mcp:block, mcp:warn,
+                     mcp:approval, terminal:audit, terminal:block,
+                     terminal:warn, terminal:approval, skills:inject
+    policy           users-export, analytics-tasks-export: cmd:<id>, data:<id>,
+                     finding:<name>, sanction:unsanctioned, sanction:unofficial
+    sort_field       users-export: total_cost (default), total_tokens,
+                     task_count, avg_cost_per_task, cache_rate, models_used,
+                     policy_enforcements
+    risk_level       discovery-risky-users-export. Repeatable:
+                     low | medium | high | critical
+                     An unrecognised value is DROPPED, not rejected, so a typo
+                     exports every risk level. Confirm with --check.
+    autonomy_level   discovery-risky-users-export. Repeatable:
+                     read_only | ask_first | auto_edit | full_auto
+                     Dropped on a typo, same as risk_level above.
+    columns          discovery-risky-users-export. Repeatable; omit for the
+                     default seven. user, email, system_user, device_id,
+                     last_sync, risk_score, risk_level, risk_factors,
+                     autonomy_level, tools, tool_count, permission_risk,
+                     config_file_risk. The file keeps that order whatever you ask for.
 `;
 
 /** `--last 7d` / `--last 24h` -> an absolute window the server understands. */
@@ -201,8 +231,12 @@ Examples:
   $ unbound download start logs-tasks-export --start 2026-07-01 --end 2026-07-31
   $ unbound download start users-export --last 30d
   $ unbound download start analytics-export --filter dataset=terminal-runs --last 7d
+  $ unbound download start ai-usage-teams-export --filter weeks=12
   $ unbound download start logs-export --check --last 90d --json
 
+The two ai-usage kinds cover whole weeks, not a date range: pass
+'--filter weeks=4|8|12' (default 8). --last and --start/--end do not apply.
+
 Admin or Analytics Viewer. Exports are kept for ${RETENTION_HOURS} hours.
 ${FILTER_HELP}${AGENT_HELP}`)
     .action(async (kind, opts) => {

package/src/lib/downloads.js

@@ -35,24 +35,44 @@ const KINDS = {
   'logs-export': {
     summary: 'Every LLM call: prompt, model, tokens, status, user and task ID.',
     filters: ['model_ids', 'application_ids', 'status_codes', 'application_owner_email',
-      'application_types', 'tool_types'],
+      'application_types', 'tool_types', 'search'],
   },
   'logs-tasks-export': {
     summary: 'One row per task (agent session), with its thread ID.',
-    filters: ['model_ids', 'tool_types', 'application_owner_email', 'user_ids'],
+    filters: ['model_ids', 'tool_types', 'application_owner_email', 'user_ids', 'search'],
   },
   'analytics-export': {
-    summary: 'Tool Use rows. Needs dataset=terminal-runs|mcp-actions|unsanctioned|mcp-servers.',
-    filters: ['dataset', 'risk_levels', 'command_families', 'server', 'intent_attribution',
-      'policy_ids', 'tool_types', 'user_ids'],
+    summary: 'Tool Use rows. Needs dataset=terminal-runs|mcp-actions|unsanctioned|unofficial|mcp-servers.',
+    filters: ['dataset', 'risk_levels', 'command_families', 'policy_ids', 'policy_actions',
+      'server', 'server_name', 'canonical_group_id', 'grouped', 'intent_attribution',
+      'has_policy_match', 'application_types', 'application_ids', 'application_owner_email',
+      'tool_types', 'user_ids', 'department_names', 'manager_names', 'search',
+      'sort_field', 'sort_order'],
   },
   'analytics-tasks-export': {
     summary: 'Analytics > Tasks, optionally narrowed to one heatmap day.',
-    filters: ['user_ids', 'tool_types', 'date', 'tz'],
+    filters: ['user_ids', 'department_names', 'manager_names', 'tool_types', 'date', 'tz',
+      'enforcement', 'policy'],
   },
   'users-export': {
     summary: 'Analytics > Users: per-user cost, tokens and activity.',
-    filters: ['user_ids', 'sort_field', 'sort_order'],
+    filters: ['user_ids', 'department_names', 'manager_names', 'tool_types', 'search',
+      'enforcement', 'policy', 'sort_field', 'sort_order'],
+  },
+  'ai-usage-teams-export': {
+    summary: 'Analytics > Usage: weekly AI adoption per team, one column per week.',
+    filters: ['weeks', 'department_names', 'manager_names', 'search', 'band', 'trend',
+      'group_by', 'sort_by', 'sort_dir'],
+  },
+  'ai-usage-users-export': {
+    summary: 'Analytics > Usage: the people inside a team. Needs department_names.',
+    filters: ['weeks', 'department_names', 'manager_names', 'search', 'status',
+      'sort_by', 'sort_dir'],
+  },
+  'discovery-risky-users-export': {
+    summary: 'AI Tools Discovery > Users Risk Leaderboard. Pick your own columns.',
+    filters: ['search', 'filter', 'high_risk', 'risk_level', 'autonomy_level', 'tool',
+      'sort_by', 'sort_direction', 'columns'],
   },
 };
 

package/test/analytics-columns.test.js

@@ -48,6 +48,9 @@ test('every dataset names only columns the export actually returns', () => {
       'Targets', 'User Prompt', 'Risk Score', 'Risk Reason', 'Initiator', 'Matched Policies'],
     unsanctioned: ['Timestamp', 'User', 'Email', 'AI Tool', 'MCP Server', 'MCP Tool',
       'Status', 'Sanction Message', 'User Prompt'],
+    // The server builds unofficial from the same column set as unsanctioned.
+    unofficial: ['Timestamp', 'User', 'Email', 'AI Tool', 'MCP Server', 'MCP Tool',
+      'Status', 'Sanction Message', 'User Prompt'],
     'mcp-servers': ['MCP Server', 'Actions', 'Average Risk Score'],
   };
 
@@ -66,3 +69,16 @@ test('every dataset names only columns the export actually returns', () => {
 test('--json works when --format was never passed', () => {
   assert.strictEqual(resolveFormat({ json: true, format: undefined }), 'json');
 });
+
+test('every Tool Use dataset the server has is reachable as a subcommand', () => {
+  // 'unofficial' has no dashboard page, so the CLI and the API are the only
+  // ways to read it; dropping it here makes it unreachable rather than awkward.
+  assert.deepEqual(Object.keys(DATASETS), [
+    'terminal', 'mcp-actions', 'unsanctioned', 'unofficial', 'mcp-servers',
+  ]);
+  for (const [name, meta] of Object.entries(DATASETS)) {
+    assert.ok(meta.key, `${name} needs the server's dataset key`);
+    assert.ok(meta.summary && meta.summary.length > 10, `${name} needs a summary`);
+    assert.ok(meta.tableColumns.length > 0, `${name} needs table columns`);
+  }
+});

package/test/download-query.test.js

@@ -69,6 +69,44 @@ test('every advertised kind names the filters it accepts', () => {
   }
 });
 
+test('every kind the backend serves is listed', () => {
+  // Literal list, in the order help prints them. The backend registry cannot be
+  // queried, so a kind added there is only discoverable once it is added here
+  // too — this is what makes that omission a failing test rather than silence.
+  assert.deepEqual(Object.keys(KINDS), [
+    'logs-export',
+    'logs-tasks-export',
+    'analytics-export',
+    'analytics-tasks-export',
+    'users-export',
+    'ai-usage-teams-export',
+    'ai-usage-users-export',
+    'discovery-risky-users-export',
+  ]);
+});
+
+test('the filters a kind advertises include the ones that change what is exported', () => {
+  // An unknown filter key is ignored by the server rather than rejected, so a
+  // missing entry here reads to the caller as "this kind cannot be narrowed"
+  // and they take a wider file than they asked for.
+  const required = {
+    'logs-export': ['search', 'tool_types'],
+    'logs-tasks-export': ['search', 'user_ids'],
+    'analytics-export': ['dataset', 'department_names', 'manager_names', 'search'],
+    'analytics-tasks-export': ['department_names', 'manager_names', 'enforcement', 'policy'],
+    'users-export': ['department_names', 'manager_names', 'tool_types', 'search',
+      'enforcement', 'policy'],
+    'ai-usage-teams-export': ['weeks', 'band', 'trend'],
+    'ai-usage-users-export': ['weeks', 'department_names', 'status'],
+    'discovery-risky-users-export': ['risk_level', 'autonomy_level', 'columns'],
+  };
+  for (const [kind, filters] of Object.entries(required)) {
+    for (const filter of filters) {
+      assert.ok(KINDS[kind].filters.includes(filter), `${kind} must advertise ${filter}`);
+    }
+  }
+});
+
 test('isJobId accepts a UUID and rejects anything else', () => {
   assert.ok(isJobId('4f2a1c9e-1b2c-4d5e-8f90-a1b2c3d4e5f6'));
   assert.ok(isJobId('4F2A1C9E-1B2C-4D5E-8F90-A1B2C3D4E5F6'));