unbound-cli 1.16.20 → 1.16.21

package/README.md

@@ -242,6 +242,28 @@ Alias: `unbound groups` works the same as `unbound user-groups`.
 
 Supported tool types: `CLAUDE_CODE`, `CURSOR`, `COPILOT`, `AUGMENT_CODE`, `ROO_CODE`, `CLINE`, `GEMINI_CLI`, `CODEX`, `KILO_CODE`, `CUSTOM_ACCESS`
 
+### Flags and False Positives
+
+Listing needs Admin, Manager or Analytics Viewer. `mark-fp` needs Admin.
+
+| Command | Description |
+|---------|-------------|
+| `unbound flags terminal` | Terminal runs that a tool policy flagged (block, approval, warn, audit) |
+| `unbound flags terminal mark-fp <id> --risk-score <n>` | Reject the run's risk score as a false positive |
+| `unbound flags data-security` | PII and secrets a guardrail found (values masked; `--reveal` shows them) |
+| `unbound flags data-security mark-fp <action-id>` | Mark a detection as a false positive |
+| `unbound trace <trace-id>` | The log, terminal runs and data security detections for one trace ID (prompts and values hidden; `--reveal` shows them) |
+
+```bash
+unbound flags terminal --action block,warn --time-window SEVEN_DAYS
+unbound flags terminal mark-fp 81234 --risk-score 8 --comment "Our build script"
+unbound flags data-security --guardrail Secrets --findings all
+unbound flags data-security mark-fp 5521
+unbound trace 3f2a6c1e-8b7d-4e2f-9a1c-5d6e7f8a9b0c --json
+```
+
+Terminal `mark-fp` records the same feedback as rejecting a risk score in the dashboard. It does not hide the run. Data security `mark-fp` moves the detection to `--findings false-positive`, and the gateway then skips that value for the organization.
+
 ## Configuration
 
 Config is stored in `~/.unbound/config.json`. For tenant deployments, point the CLI at your own hosts in one command (recommended for new installs):

package/package.json

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

package/src/commands/flags.js

@@ -0,0 +1,253 @@
+const api = require('../api');
+const config = require('../config');
+const output = require('../output');
+const { buildQueryString, TIME_WINDOWS, DEFAULT_TIME_WINDOW } = require('../lib/analytics-query');
+const {
+  DATA_SECURITY_ACTIONS,
+  DATA_SECURITY_HEADERS,
+  FINDINGS,
+  TERMINAL_ACTIONS,
+  TERMINAL_HEADERS,
+  buildDataSecurityQuery,
+  buildTerminalQuery,
+  dataSecurityRows,
+  redactDataSecurityLog,
+  resolveGuardrailIds,
+  terminalRows,
+} = require('../lib/flags');
+
+const TERMINAL_PATH = '/api/v1/analytics/terminal_commands/';
+const DATA_SECURITY_PATH = '/api/v1/analytics/guardrails/';
+const GUARDRAIL_FILTERS_PATH = '/api/v1/analytics/guardrails/filters/';
+const FEEDBACK_PATH = '/api/v1/analytics/feedback/';
+const MARK_FP_PATH = '/api/v1/analytics/guardrails/mark_false_positive/';
+
+const WINDOW_HELP = `
+TIME RANGE
+  --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.
+`;
+
+function requireLogin() {
+  if (!config.isLoggedIn()) {
+    throw new Error('Not logged in. Run `unbound login` first.');
+  }
+}
+
+async function run(fn) {
+  try {
+    requireLogin();
+    await fn();
+  } catch (err) {
+    output.error(err.message);
+    process.exitCode = 1;
+  }
+}
+
+function addWindowOptions(command) {
+  return 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)');
+}
+
+function pageFooter(page, totalPages, total, noun, hasMore) {
+  console.log('');
+  if (total !== undefined) {
+    output.info(`Page ${page} of ${Math.max(totalPages || 1, 1)} (${Number(total).toLocaleString()} ${noun}).`);
+  }
+  if (hasMore) output.info(`Next page: --page ${page + 1}`);
+}
+
+function parsePositiveInt(flag, value) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1) throw new Error(`Invalid ${flag} "${value}". Must be a positive integer.`);
+  return n;
+}
+
+async function listTerminal(opts) {
+  const query = buildTerminalQuery(opts);
+  const data = await api.get(`${TERMINAL_PATH}?${buildQueryString(query)}`);
+  if (opts.json) {
+    output.json(data);
+    return;
+  }
+  const rows = data.terminal_commands || [];
+  if (rows.length === 0) {
+    output.info('No flagged terminal runs for this window and filter set.');
+    return;
+  }
+  output.logTable(TERMINAL_HEADERS, terminalRows(rows, { wide: Boolean(opts.wide) }), { wide: Boolean(opts.wide) });
+  pageFooter(query.page, data.total_pages, data.total_count, 'flagged runs', data.has_more);
+  output.info('Mark one as a false positive: unbound flags terminal mark-fp <ID> --risk-score <Risk>');
+}
+
+async function markTerminalFalsePositive(id, opts) {
+  const riskScore = Number(opts.riskScore);
+  if (!Number.isInteger(riskScore) || riskScore < 1 || riskScore > 10) {
+    throw new Error(`Invalid --risk-score "${opts.riskScore}". Must be an integer from 1 to 10 (the Risk column).`);
+  }
+  const body = {
+    prompt_analytics_id: parsePositiveInt('ID', id),
+    analytics_type: 'terminal_command',
+    feedback_type: 'reject',
+    risk_score: riskScore,
+  };
+  if (opts.comment !== undefined) body.comment = opts.comment;
+  const data = await api.post(FEEDBACK_PATH, { body });
+  if (opts.json) {
+    output.json(data);
+    return;
+  }
+  output.success(`Terminal run ${id} marked as a false positive (feedback ${data.action || 'saved'}).`);
+}
+
+async function listDataSecurity(opts) {
+  let guardrailIds = [];
+  if (opts.guardrail) {
+    const filters = await api.get(GUARDRAIL_FILTERS_PATH);
+    guardrailIds = resolveGuardrailIds(opts.guardrail, filters.guardrails);
+  }
+  const query = buildDataSecurityQuery(opts, guardrailIds);
+  const data = await api.get(`${DATA_SECURITY_PATH}?${buildQueryString(query)}`);
+  const logs = (data.logs && data.logs.data) || [];
+  if (opts.json) {
+    const payload = opts.reveal ? data : { ...data, logs: { ...data.logs, data: logs.map(redactDataSecurityLog) } };
+    output.json(payload);
+    return;
+  }
+  if (logs.length === 0) {
+    output.info('No data security flags for this window and filter set.');
+    return;
+  }
+  output.logTable(DATA_SECURITY_HEADERS, dataSecurityRows(logs, { reveal: Boolean(opts.reveal), wide: Boolean(opts.wide) }),
+    { wide: Boolean(opts.wide) });
+  const totalPages = data.logs.total_pages;
+  pageFooter(query.page, totalPages, data.logs.total_items, 'flagged requests', query.page < (totalPages || 0));
+  if (!opts.reveal) output.info('Detected values are masked. Use --reveal to show them.');
+  output.info('Mark one as a false positive: unbound flags data-security mark-fp <Action ID>');
+}
+
+async function markDataSecurityFalsePositive(id, opts) {
+  const data = await api.post(MARK_FP_PATH, { body: { guardrail_action_id: parsePositiveInt('Action ID', id) } });
+  if (opts.json) {
+    output.json(data);
+    return;
+  }
+  output.success(`Data security detection ${id} marked as a false positive.`);
+}
+
+function register(program) {
+  const flags = program
+    .command('flags')
+    .description('Review what your policies flagged, and mark false positives.')
+    .addHelpText('after', `
+KINDS
+  terminal        Terminal commands that matched a tool policy (block, approval, warn, audit)
+  data-security   Prompts where a data security guardrail found PII or a secret
+
+Examples:
+  $ unbound flags terminal
+  $ unbound flags terminal --action block --time-window SEVEN_DAYS
+  $ unbound flags terminal mark-fp 81234 --risk-score 8 --comment "Expected cleanup script"
+  $ unbound flags data-security --guardrail Secrets
+  $ unbound flags data-security mark-fp 5521
+
+  Search every source for one trace ID with \`unbound trace <trace-id>\`.
+`);
+
+  const terminal = flags
+    .command('terminal')
+    .description('List terminal runs that a tool policy flagged (Analytics > Tool Use > Terminal Runs).')
+    .option('--action <actions>', `Policy outcome, comma-separated: ${TERMINAL_ACTIONS.join(', ')} (default: all)`)
+    .option('--policy <ids>', 'Tool policy IDs, comma-separated (see `unbound policy tool list`)')
+    .option('--trace <trace-id>', 'Only the run with this gateway trace ID')
+    .option('--tool <types>', 'AI tool type, comma-separated, e.g. CLAUDE_CODE,CURSOR')
+    .option('--family <families>', 'Command family, comma-separated')
+    .option('--page <n>', 'Page number (10 runs per page)')
+    .option('--json', 'Output the raw JSON response')
+    .option('--wide', 'Print full values instead of clipping to terminal width');
+  addWindowOptions(terminal)
+    .addHelpText('after', `
+Columns:
+  ID        The run's ID. Pass it to \`mark-fp\`.
+  Outcome   The strongest action across the matched policies.
+  Risk      The risk score. \`mark-fp\` records it with the dispute.
+  Feedback  Your earlier feedback on this run, if any.
+${WINDOW_HELP}
+Examples:
+  $ unbound flags terminal
+  $ unbound flags terminal --action block,warn --policy 12
+  $ unbound flags terminal --trace 3f2a6c1e-8b7d-4e2f-9a1c-5d6e7f8a9b0c
+  $ unbound flags terminal --page 2 --json
+
+Admin, Manager or Analytics Viewer.
+`)
+    .action((opts) => run(() => listTerminal(opts)));
+
+  terminal
+    .command('mark-fp <id>')
+    .description('Mark a flagged terminal run as a false positive (reject its risk score).')
+    .requiredOption('--risk-score <n>', 'The Risk value shown for the run (1-10)')
+    .option('--comment <text>', 'Why this run is a false positive')
+    .option('--json', 'Output the raw JSON response')
+    .addHelpText('after', `
+Records your feedback that the run was not risky. This is the same feedback as
+rejecting a risk score in the dashboard. It does not hide the run or change the
+policy. Running it again updates your earlier feedback.
+
+Examples:
+  $ unbound flags terminal mark-fp 81234 --risk-score 8
+  $ unbound flags terminal mark-fp 81234 --risk-score 8 --comment "Our build script"
+
+Admin only.
+`)
+    .action((id, opts) => run(() => markTerminalFalsePositive(id, opts)));
+
+  const dataSecurity = flags
+    .command('data-security')
+    .description('List prompts where a data security guardrail found PII or a secret (Analytics > Data Security).')
+    .option('--guardrail <names>', 'Guardrail names or IDs, comma-separated, e.g. PII,Secrets')
+    .option('--action <actions>', `Action taken, comma-separated: ${DATA_SECURITY_ACTIONS.join(', ')}`)
+    .option('--findings <which>', `${Object.keys(FINDINGS).join(' | ')} (default real)`)
+    .option('--trace <trace-id>', 'Only the request with this gateway trace ID (default --findings all)')
+    .option('--reveal', 'Show detected values and prompts in clear text')
+    .option('--page <n>', 'Page number (10 requests per page)')
+    .option('--json', 'Output the JSON response (values masked unless --reveal)')
+    .option('--wide', 'Print full values instead of clipping to terminal width');
+  addWindowOptions(dataSecurity)
+    .addHelpText('after', `
+Columns:
+  Action ID  The detection's ID. Pass it to \`mark-fp\`.
+  Value      The detected value, masked unless --reveal.
+${WINDOW_HELP}
+Examples:
+  $ unbound flags data-security
+  $ unbound flags data-security --guardrail Secrets --action block
+  $ unbound flags data-security --findings false-positive
+  $ unbound flags data-security --trace 3f2a6c1e-8b7d-4e2f-9a1c-5d6e7f8a9b0c --reveal
+
+Admin, Manager or Analytics Viewer.
+`)
+    .action((opts) => run(() => listDataSecurity(opts)));
+
+  dataSecurity
+    .command('mark-fp <action-id>')
+    .description('Mark a data security detection as a false positive.')
+    .option('--json', 'Output the raw JSON response')
+    .addHelpText('after', `
+The detection moves to --findings false-positive. The gateway then skips the
+same value for everyone in your organization.
+
+Examples:
+  $ unbound flags data-security mark-fp 5521
+
+Admin only.
+`)
+    .action((id, opts) => run(() => markDataSecurityFalsePositive(id, opts)));
+
+  return flags;
+}
+
+module.exports = { register };

package/src/commands/trace.js

@@ -0,0 +1,158 @@
+const api = require('../api');
+const config = require('../config');
+const output = require('../output');
+const { buildQueryString } = require('../lib/analytics-query');
+const {
+  DATA_SECURITY_HEADERS,
+  FINDINGS,
+  LOG_HEADERS,
+  TERMINAL_HEADERS,
+  dataSecurityRows,
+  logRows,
+  redactDataSecurityLog,
+  redactLog,
+  resolveTraceId,
+  terminalRows,
+} = require('../lib/flags');
+
+// The widest preset the analytics endpoints accept; Logs takes no window.
+const TRACE_WINDOW = 'THREE_MONTHS';
+
+// One trace rarely fills a page; past this cap the result is reported as incomplete.
+const MAX_PAGES = 10;
+
+const sameTrace = (value, trace) => String(value || '').toLowerCase() === trace;
+
+const SOURCES = [
+  {
+    key: 'logs',
+    title: 'Logs',
+    path: (trace, page) => `/api/v1/logs/prompts/?${buildQueryString({ search: trace, page })}`,
+    // Logs search also matches the text of a prompt, so keep only the exact trace.
+    rows: (data, trace) => (data.prompts || []).filter((p) => sameTrace(p.traceId, trace)),
+    more: (data, page) => page < (data.total_pages || 0),
+    headers: LOG_HEADERS,
+    toTable: (rows, opts) => logRows(rows, { reveal: Boolean(opts.reveal), wide: Boolean(opts.wide) }),
+    redact: (rows) => rows.map(redactLog),
+  },
+  {
+    key: 'terminal_runs',
+    title: 'Terminal Runs',
+    path: (trace, page) => `/api/v1/analytics/terminal_commands/?${buildQueryString({ search: trace, time_window: TRACE_WINDOW, page })}`,
+    // The other sources match the trace exactly today; the filter guards an older backend that ignores search.
+    rows: (data, trace) => (data.terminal_commands || []).filter((r) => sameTrace(r.trace_id, trace)),
+    more: (data) => Boolean(data.has_more),
+    headers: TERMINAL_HEADERS,
+    toTable: (rows, opts) => terminalRows(rows, { wide: Boolean(opts.wide) }),
+  },
+  {
+    key: 'data_security',
+    title: 'Data Security',
+    path: (trace, page) => `/api/v1/analytics/guardrails/?${buildQueryString({ search: trace, time_window: TRACE_WINDOW, findings: FINDINGS.all, page })}`,
+    rows: (data, trace) => ((data.logs && data.logs.data) || []).filter((l) => sameTrace(l.trace_id, trace)),
+    more: (data, page) => page < ((data.logs && data.logs.total_pages) || 0),
+    headers: DATA_SECURITY_HEADERS,
+    toTable: (rows, opts) => dataSecurityRows(rows, { reveal: Boolean(opts.reveal), wide: Boolean(opts.wide) }),
+    redact: (rows) => rows.map(redactDataSecurityLog),
+  },
+];
+
+async function fetchAll(source, trace) {
+  const rows = [];
+  for (let page = 1; page <= MAX_PAGES; page += 1) {
+    const data = await api.get(source.path(trace, page));
+    rows.push(...source.rows(data, trace));
+    if (!source.more(data, page)) return { source, rows, incomplete: false };
+  }
+  return { source, rows, incomplete: true };
+}
+
+async function lookup(trace) {
+  return Promise.all(SOURCES.map(async (source) => {
+    try {
+      return await fetchAll(source, trace);
+    } catch (err) {
+      return { source, error: err.message };
+    }
+  }));
+}
+
+function printJson(trace, results, opts) {
+  const payload = { trace_id: trace };
+  for (const { source, rows, error, incomplete } of results) {
+    if (error) {
+      payload[source.key] = { error };
+    } else {
+      payload[source.key] = { rows: source.redact && !opts.reveal ? source.redact(rows) : rows };
+      if (incomplete) payload[source.key].incomplete = true;
+    }
+  }
+  output.json(payload);
+}
+
+function printTables(trace, results, opts) {
+  for (const { source, rows, error, incomplete } of results) {
+    console.log('');
+    console.log(output.colors.bold(`${source.title}`));
+    if (error) {
+      output.warn(`${source.title} lookup failed: ${error}`);
+    } else if (rows.length === 0) {
+      output.info(`No ${source.title} entries for trace ${trace}.`);
+    } else {
+      output.logTable(source.headers, source.toTable(rows, opts), { wide: Boolean(opts.wide) });
+    }
+    if (incomplete) output.warn(`${source.title}: more than ${MAX_PAGES} pages matched. Only the first ${MAX_PAGES} are shown.`);
+  }
+  if (!opts.reveal) {
+    console.log('');
+    output.info('Prompts and detected values are hidden. Use --reveal to show them.');
+  }
+}
+
+async function runTrace(value, opts) {
+  try {
+    if (!config.isLoggedIn()) throw new Error('Not logged in. Run `unbound login` first.');
+    const trace = resolveTraceId(value);
+    const results = await lookup(trace);
+    if (opts.json) {
+      printJson(trace, results, opts);
+    } else {
+      printTables(trace, results, opts);
+    }
+    // A failed or cut-off source means the answer is incomplete, so scripts must not read it as complete.
+    if (results.some((r) => r.error || r.incomplete)) process.exitCode = 1;
+  } catch (err) {
+    output.error(err.message);
+    process.exitCode = 1;
+  }
+}
+
+function register(program) {
+  program
+    .command('trace <trace-id>')
+    .description('Find everything recorded for one gateway trace ID: the log, terminal runs and data security flags.')
+    .option('--json', 'Output one JSON object with a key per source')
+    .option('--reveal', 'Show prompts and detected data security values in clear text')
+    .option('--wide', 'Print full values instead of clipping to terminal width')
+    .addHelpText('after', `
+The trace ID is the UUID shown to a user under a blocked or warned action.
+
+Sources:
+  Logs           The request and its prompt (any age)
+  Terminal Runs  Tool calls on the request, flagged or not (last 3 months)
+  Data Security  PII or secret detections on the request (last 3 months)
+
+Prompts and detected values are hidden unless --reveal is given.
+
+The exit code is 1 when a source cannot be read, for example because your
+role cannot see it, or when a source has more than ${MAX_PAGES} pages. The
+other sources still print.
+
+Examples:
+  $ unbound trace 3f2a6c1e-8b7d-4e2f-9a1c-5d6e7f8a9b0c
+  $ unbound trace 3f2a6c1e-8b7d-4e2f-9a1c-5d6e7f8a9b0c --json | jq '.terminal_runs.rows[0]'
+`)
+    .action(runTrace);
+}
+
+module.exports = { register, SOURCES };

package/src/index.js

@@ -164,6 +164,15 @@ ANALYTICS (Admin/Analytics Viewer only, for listing as well as CSV export)
   csv exports every matching row, not just the page.
   See "unbound analytics tool-use --help" for the JSON contract used by agents.
 
+FLAGS AND FALSE POSITIVES (Admin/Analytics Viewer/Manager; mark-fp is Admin only)
+  $ unbound flags terminal                 Terminal runs a tool policy flagged
+  $ unbound flags terminal mark-fp <id> --risk-score <n>
+                                           Mark a flagged run as a false positive
+  $ unbound flags data-security            PII and secrets a guardrail found (values masked)
+  $ unbound flags data-security mark-fp <action-id>
+                                           Mark a detection as a false positive
+  $ unbound trace <trace-id>               Log, terminal runs and data security for one trace ID
+
 CHAT (Admin/Analytics Viewer/Manager)
   $ unbound chat                           Interactive REPL (multi-turn, in-memory history)
   $ unbound chat -m "show cost by provider for the last 30 days"
@@ -206,6 +215,8 @@ require('./commands/users').register(program);
 require('./commands/user-groups').register(program);
 require('./commands/tools').register(program);
 require('./commands/analytics').register(program);
+require('./commands/flags').register(program);
+require('./commands/trace').register(program);
 require('./commands/download').register(program);
 require('./commands/setup').register(program);
 require('./commands/discover').register(program);

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/test/flags.test.js

@@ -0,0 +1,236 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const http = require('http');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const {
+  buildDataSecurityQuery,
+  buildTerminalQuery,
+  dataSecurityRows,
+  maskValue,
+  redactDataSecurityLog,
+  resolveGuardrailIds,
+  resolveTraceId,
+  terminalRows,
+} = require('../src/lib/flags');
+
+const TRACE = '225c6413-26e4-4cd2-85a6-8c5ccfc3c5ef';
+
+test('terminal query asks only for flagged runs when no --action is given', () => {
+  const q = buildTerminalQuery({});
+  assert.deepEqual(q.policy_actions, ['block', 'approval', 'warn', 'audit']);
+  assert.equal(q.page, 1);
+  assert.equal(q.time_window, 'THIRTY_DAYS');
+});
+
+test('terminal query narrows to the given outcomes, policies and trace', () => {
+  const q = buildTerminalQuery({ action: 'Block,warn', policy: '12,13', trace: TRACE.toUpperCase(), page: '2' });
+  assert.deepEqual(q.policy_actions, ['block', 'warn']);
+  assert.deepEqual(q.policy_ids, ['12', '13']);
+  assert.equal(q.search, TRACE);
+  assert.equal(q.page, 2);
+});
+
+test('terminal query rejects an unknown outcome, a bad page and a non-UUID trace', () => {
+  assert.throws(() => buildTerminalQuery({ action: 'nuke' }), /Invalid --action "nuke"/);
+  assert.throws(() => buildTerminalQuery({ page: '0' }), /Invalid --page/);
+  assert.throws(() => buildTerminalQuery({ trace: 'abc' }), /Invalid trace ID/);
+});
+
+test('data security query maps --findings to the backend values', () => {
+  assert.deepEqual(buildDataSecurityQuery({}).findings, ['real']);
+  assert.deepEqual(buildDataSecurityQuery({ findings: 'false-positive' }).findings, ['false_positive']);
+  assert.deepEqual(buildDataSecurityQuery({ findings: 'all' }).findings, ['real', 'false_positive']);
+  assert.throws(() => buildDataSecurityQuery({ findings: 'maybe' }), /Invalid --findings/);
+  const trace = '3f2a6c1e-8b7d-4e2f-9a1c-5d6e7f8a9b0c';
+  assert.deepEqual(buildDataSecurityQuery({ trace }).findings, ['real', 'false_positive']);
+  assert.deepEqual(buildDataSecurityQuery({ trace, findings: 'real' }).findings, ['real']);
+});
+
+test('guardrail names resolve to IDs case-insensitively, and an unknown name lists the choices', () => {
+  const available = [{ id: 4, name: 'PII' }, { id: 11, name: 'Secrets' }];
+  assert.deepEqual(resolveGuardrailIds('secrets,4', available), ['11', '4']);
+  assert.throws(() => resolveGuardrailIds('nope', available), /Available: PII, Secrets/);
+});
+
+test('maskValue keeps only the ends of a long value', () => {
+  assert.equal(maskValue('AKIAE2ETESTKEY0000001'), 'AK****01');
+  assert.equal(maskValue('short'), '****');
+  assert.equal(maskValue(''), '');
+});
+
+const LOG = {
+  id: 7,
+  trace_id: TRACE,
+  timestamp: '2026-09-24T19:17:53.790Z',
+  user_email: 'ada@example.com',
+  application_name: 'CLAUDE_CODE',
+  guardrails: ['Secrets'],
+  guardrail_actions: ['Block'],
+  sensitive_contents: ['AKIAE2ETESTKEY0000001'],
+  sensitive_content_details: [{
+    action_id: 1, action: 'Block', guardrail_name: 'Secrets', sensitive_content: 'AKIAE2ETESTKEY0000001', is_false_positive: false,
+  }],
+  prompt: { user_prompt: 'my key is AKIAE2ETESTKEY0000001' },
+};
+
+test('redacted data security JSON carries no detected value and no prompt', () => {
+  const text = JSON.stringify(redactDataSecurityLog(LOG));
+  assert.ok(!text.includes('AKIAE2ETESTKEY0000001'), text);
+  assert.ok(!('prompt' in redactDataSecurityLog(LOG)));
+});
+
+test('data security rows list one line per detection, masked unless revealed', () => {
+  const [row] = dataSecurityRows([LOG]);
+  assert.equal(row[0], '1');
+  assert.equal(row[1], '2026-09-24 19:17');
+  assert.equal(row[6], 'AK****01');
+  assert.equal(dataSecurityRows([LOG], { reveal: true })[0][6], 'AKIAE2ETESTKEY0000001');
+});
+
+test('terminal rows show policies with their action and the feedback as a label', () => {
+  const [row] = terminalRows([{
+    id: 554681,
+    created_at: '2026-09-24T19:17:53.790Z',
+    email: 'ada@example.com',
+    terminal_command: 'git status',
+    all_matched_policies: [{ name: 'Warn AWS', action: 'warn' }],
+    policy_action: 'warn',
+    risk_score: 5,
+    user_feedback: { feedback_type: 'reject' },
+    trace_id: TRACE,
+  }]);
+  assert.deepEqual(row, ['554681', '2026-09-24 19:17', 'ada@example.com', 'git status', 'Warn AWS (warn)',
+    'warn', 5, 'False positive', TRACE]);
+});
+
+test('resolveTraceId lowercases and trims', () => {
+  assert.equal(resolveTraceId(`  ${TRACE.toUpperCase()} `), TRACE);
+});
+
+// End to end through the real binary, against a fake backend that records requests.
+
+function startServer(routes) {
+  const seen = [];
+  const server = http.createServer((req, res) => {
+    let body = '';
+    req.on('data', (c) => { body += c; });
+    req.on('end', () => {
+      const url = new URL(req.url, 'http://x');
+      seen.push({ method: req.method, path: url.pathname, query: url.searchParams, body: body ? JSON.parse(body) : null });
+      const [status, payload] = routes(req.method, url) || [404, { error: 'no route' }];
+      res.writeHead(status, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(payload));
+    });
+  });
+  return new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve({ server, seen, port: server.address().port })));
+}
+
+function runCli(port, args) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'flags-test-'));
+  fs.mkdirSync(path.join(home, '.unbound'));
+  fs.writeFileSync(path.join(home, '.unbound', 'config.json'),
+    JSON.stringify({ api_key: 'test-key', base_url: `http://127.0.0.1:${port}` }));
+  return new Promise((resolve) => {
+    const child = spawn('node', [path.join(__dirname, '..', 'src', 'index.js'), ...args], {
+      env: { ...process.env, HOME: home, UNBOUND_API_URL: '', UNBOUND_TELEMETRY: '0', UNBOUND_NO_UPDATE_CHECK: '1' },
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('close', (code) => {
+      fs.rmSync(home, { recursive: true, force: true });
+      resolve({ code, stdout, stderr });
+    });
+  });
+}
+
+test('flags terminal mark-fp posts a reject feedback for the run', async () => {
+  const { server, seen, port } = await startServer((method, url) =>
+    (method === 'POST' && url.pathname === '/api/v1/analytics/feedback/'
+      ? [201, { status: 'success', action: 'created', feedback_id: 3 }] : null));
+  try {
+    const r = await runCli(port, ['flags', 'terminal', 'mark-fp', '554681', '--risk-score', '8', '--comment', 'build script']);
+    assert.equal(r.code, 0, r.stderr);
+    const post = seen.find((s) => s.method === 'POST');
+    assert.deepEqual(post.body, {
+      prompt_analytics_id: 554681, analytics_type: 'terminal_command', feedback_type: 'reject', risk_score: 8, comment: 'build script',
+    });
+  } finally {
+    server.close();
+  }
+});
+
+test('flags data-security mark-fp posts the detection ID', async () => {
+  const { server, seen, port } = await startServer((method, url) =>
+    (method === 'POST' && url.pathname === '/api/v1/analytics/guardrails/mark_false_positive/'
+      ? [200, { message: 'ok' }] : null));
+  try {
+    const r = await runCli(port, ['flags', 'data-security', 'mark-fp', '5521']);
+    assert.equal(r.code, 0, r.stderr);
+    assert.deepEqual(seen.find((s) => s.method === 'POST').body, { guardrail_action_id: 5521 });
+  } finally {
+    server.close();
+  }
+});
+
+test('trace keeps only exact log matches, masks values, and exits 1 when a source fails', async () => {
+  const { server, port } = await startServer((method, url) => {
+    if (url.pathname === '/api/v1/logs/prompts/') {
+      return [200, { prompts: [
+        { id: '1', traceId: TRACE, userPrompt: 'my key is AKIAE2ETESTKEY0000001' },
+        { id: '2', traceId: null, userPrompt: `mentions ${TRACE}` },
+      ] }];
+    }
+    if (url.pathname === '/api/v1/analytics/terminal_commands/') return [403, { error: 'Manager or admin access required' }];
+    if (url.pathname === '/api/v1/analytics/guardrails/') {
+      // A trace lookup must ask for false positives too.
+      const all = url.searchParams.getAll('findings').join() === 'real,false_positive';
+      return all ? [200, { logs: { data: [LOG] } }] : [400, { error: 'findings must be all' }];
+    }
+    return null;
+  });
+  try {
+    const r = await runCli(port, ['trace', TRACE, '--json']);
+    assert.equal(r.code, 1);
+    const out = JSON.parse(r.stdout);
+    assert.deepEqual(out.logs.rows.map((p) => p.id), ['1']);
+    assert.equal(out.terminal_runs.error, 'Manager or admin access required');
+    assert.equal(out.data_security.rows.length, 1);
+    assert.ok(!r.stdout.includes('AKIAE2ETESTKEY0000001'), 'values must be masked without --reveal');
+  } finally {
+    server.close();
+  }
+});
+
+test('trace reads every page of a source and hides log prompts in the table', async () => {
+  const { server, seen, port } = await startServer((method, url) => {
+    const page = url.searchParams.get('page');
+    if (url.pathname === '/api/v1/logs/prompts/') {
+      return [200, { prompts: [{ id: '1', traceId: TRACE, userPrompt: 'my key is AKIAE2ETESTKEY0000001' }], total_pages: 1 }];
+    }
+    if (url.pathname === '/api/v1/analytics/terminal_commands/') {
+      // A row from another trace stands in for an older backend that ignores search.
+      return [200, { terminal_commands: [{ id: Number(page), trace_id: TRACE }, { id: 99, trace_id: 'other' }], has_more: page === '1' }];
+    }
+    if (url.pathname === '/api/v1/analytics/guardrails/') return [200, { logs: { data: [], total_pages: 0 } }];
+    return null;
+  });
+  try {
+    const json = await runCli(port, ['trace', TRACE, '--json']);
+    assert.equal(json.code, 0, json.stderr);
+    assert.deepEqual(JSON.parse(json.stdout).terminal_runs.rows.map((row) => row.id), [1, 2]);
+    assert.deepEqual(seen.filter((s) => s.path === '/api/v1/analytics/terminal_commands/').map((s) => s.query.get('page')),
+      ['1', '2']);
+    const table = await runCli(port, ['trace', TRACE]);
+    assert.ok(!table.stdout.includes('AKIAE2ETESTKEY0000001'), table.stdout);
+    const revealed = await runCli(port, ['trace', TRACE, '--reveal', '--wide']);
+    assert.ok(revealed.stdout.includes('AKIAE2ETESTKEY0000001'), revealed.stdout);
+  } finally {
+    server.close();
+  }
+});