zeuslock-dlp-cli 0.2.0

package/src/commands/shadow-ai.js

@@ -0,0 +1,255 @@
+import { Command } from "commander";
+
+import { requestAuthenticatedJson } from "../lib/api-client.js";
+import { dash, formatTable } from "../lib/table.js";
+
+const DAYS = [7, 30, 90];
+const SOURCES = ["all", "endpoint", "browser", "both"];
+const STATUSES = ["all", "sanctioned", "shadow"];
+const CATEGORIES = ["all", "chatbot", "coding_assistant", "image_gen", "agent", "other"];
+const DISABLED_MESSAGE = "Shadow AI is not enabled for this organization.";
+
+export function createShadowAiCommand({
+  stdout = process.stdout,
+  env = process.env
+} = {}) {
+  const command = new Command("shadow-ai")
+    .description("Review Shadow AI tool usage");
+
+  command.addCommand(createStatsCommand({ stdout, env }));
+  command.addCommand(createToolsCommand({ stdout, env }));
+  command.addCommand(createUsersCommand({ stdout, env }));
+
+  return command;
+}
+
+function createStatsCommand({ stdout, env }) {
+  return new Command("stats")
+    .description("Show Shadow AI detection statistics")
+    .option("--days <days>", "history window: 7, 30, or 90", "30")
+    .option("--source <source>", "source filter: all, endpoint, browser, or both", "all")
+    .option("--status <status>", "policy status filter: all, sanctioned, or shadow", "all")
+    .option("--category <category>", "category filter: all, chatbot, coding_assistant, image_gen, agent, or other", "all")
+    .option("--json", "print machine-readable output")
+    .action(async (options) => {
+      const filters = parseSharedFilters(options);
+      if (!await isShadowAiEnabled(env)) {
+        writeDisabled(stdout, options, filters);
+        return;
+      }
+
+      const stats = await requestAuthenticatedJson(`/api/shadow-ai/stats?${buildShadowQuery(filters)}`, { env });
+      const output = { enabled: true, filters, stats };
+
+      if (options.json) {
+        stdout.write(`${JSON.stringify(output)}\n`);
+        return;
+      }
+
+      stdout.write(formatShadowStats(stats, filters.days));
+    });
+}
+
+function createToolsCommand({ stdout, env }) {
+  return new Command("tools")
+    .description("List detected Shadow AI tools")
+    .option("--days <days>", "history window: 7, 30, or 90", "30")
+    .option("--source <source>", "source filter: all, endpoint, browser, or both", "all")
+    .option("--status <status>", "policy status filter: all, sanctioned, or shadow", "all")
+    .option("--category <category>", "category filter: all, chatbot, coding_assistant, image_gen, agent, or other", "all")
+    .option("--json", "print machine-readable output")
+    .action(async (options) => {
+      const filters = parseSharedFilters(options);
+      if (!await isShadowAiEnabled(env)) {
+        writeDisabled(stdout, options, filters);
+        return;
+      }
+
+      const data = await requestAuthenticatedJson(`/api/shadow-ai/tools?${buildShadowQuery(filters)}`, { env });
+      const tools = normalizeTools(data);
+      const output = {
+        enabled: true,
+        total: typeof data?.total === "number" ? data.total : tools.length,
+        period_days: typeof data?.period_days === "number" ? data.period_days : filters.days,
+        filters,
+        tools
+      };
+
+      if (options.json) {
+        stdout.write(`${JSON.stringify(output)}\n`);
+        return;
+      }
+
+      stdout.write(`Shadow AI tools: ${output.total} detected (${output.period_days} days)\n`);
+      if (!tools.length) {
+        stdout.write("No Shadow AI tools found.\n");
+        return;
+      }
+
+      stdout.write("\n");
+      stdout.write(`${formatTable(tools, [
+        { header: "TOOL", value: (tool) => dash(tool.tool_name || tool.tool_key) },
+        { header: "CATEGORY", value: (tool) => dash(tool.category) },
+        { header: "POLICY", value: (tool) => dash(tool.policy_status) },
+        { header: "SOURCE", value: (tool) => dash(tool.detection_source) },
+        { header: "USERS", value: (tool) => numberOrZero(tool.unique_users) },
+        { header: "CONNECTIONS", value: (tool) => numberOrZero(tool.connections) },
+        { header: "RISK", value: (tool) => numberOrZero(tool.risk_score) }
+      ])}\n`);
+    });
+}
+
+function createUsersCommand({ stdout, env }) {
+  return new Command("users")
+    .description("List users with Shadow AI tool usage")
+    .option("--days <days>", "history window: 7, 30, or 90", "30")
+    .option("--json", "print machine-readable output")
+    .action(async (options) => {
+      const days = parseAllowedInt(options.days, DAYS, "--days");
+      const filters = { days };
+      if (!await isShadowAiEnabled(env)) {
+        writeDisabled(stdout, options, filters);
+        return;
+      }
+
+      const data = await requestAuthenticatedJson(`/api/shadow-ai/users?days=${days}`, { env });
+      const users = normalizeUsers(data);
+      const output = {
+        enabled: true,
+        total: typeof data?.total === "number" ? data.total : users.length,
+        period_days: typeof data?.period_days === "number" ? data.period_days : days,
+        filters,
+        users
+      };
+
+      if (options.json) {
+        stdout.write(`${JSON.stringify(output)}\n`);
+        return;
+      }
+
+      stdout.write(`Shadow AI users: ${output.total} users (${output.period_days} days)\n`);
+      if (!users.length) {
+        stdout.write("No Shadow AI users found.\n");
+        return;
+      }
+
+      stdout.write("\n");
+      stdout.write(`${formatTable(users, [
+        { header: "USER", value: (user) => dash(user.username) },
+        { header: "DISTINCT TOOLS", value: (user) => numberOrZero(user.distinct_tools) },
+        { header: "MOST USED", value: (user) => dash(user.most_used_tool) }
+      ])}\n`);
+    });
+}
+
+async function isShadowAiEnabled(env) {
+  const org = await requestAuthenticatedJson("/api/org", { env });
+  return Boolean(org?.settings?.shadow_ai_enabled);
+}
+
+function writeDisabled(stdout, options, filters) {
+  if (options.json) {
+    stdout.write(`${JSON.stringify({
+      enabled: false,
+      message: DISABLED_MESSAGE,
+      filters
+    })}\n`);
+    return;
+  }
+  stdout.write(`${DISABLED_MESSAGE}\n`);
+}
+
+function parseSharedFilters(options) {
+  return {
+    days: parseAllowedInt(options.days, DAYS, "--days"),
+    source: parseOptionalChoice(options.source, SOURCES, "--source") || "all",
+    status: parseOptionalChoice(options.status, STATUSES, "--status") || "all",
+    category: parseOptionalChoice(options.category, CATEGORIES, "--category") || "all"
+  };
+}
+
+function buildShadowQuery(filters) {
+  const params = new URLSearchParams();
+  params.set("days", String(filters.days));
+  if (filters.source !== "all") {
+    params.set("source", filters.source);
+  }
+  if (filters.status !== "all") {
+    params.set("status", filters.status);
+  }
+  if (filters.category !== "all") {
+    params.set("category", filters.category);
+  }
+  return params.toString();
+}
+
+function parseAllowedInt(value, allowed, optionName) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || !allowed.includes(number)) {
+    throw new Error(`Invalid ${optionName}. Allowed values: ${allowed.join(", ")}.`);
+  }
+  return number;
+}
+
+function parseOptionalChoice(value, allowed, optionName) {
+  if (value === undefined || value === null || value === "") {
+    return null;
+  }
+  const normalized = String(value).trim().toLowerCase();
+  if (!allowed.includes(normalized)) {
+    throw new Error(`Invalid ${optionName}. Allowed values: ${allowed.join(", ")}.`);
+  }
+  return normalized;
+}
+
+function normalizeTools(data) {
+  const tools = Array.isArray(data) ? data : (data?.tools || []);
+  return tools.map((tool) => ({
+    tool_key: tool.tool_key || "",
+    tool_name: tool.tool_name || "",
+    category: tool.category || "",
+    vendor: tool.vendor || "",
+    destination_domain: tool.destination_domain || "",
+    policy_status: tool.policy_status || "",
+    detection_source: tool.detection_source || "",
+    unique_users: numberOrZero(tool.unique_users),
+    connections: numberOrZero(tool.connections),
+    risk_score: numberOrZero(tool.risk_score)
+  }));
+}
+
+function normalizeUsers(data) {
+  const users = Array.isArray(data) ? data : (data?.users || []);
+  return users.map((user) => ({
+    username: user.username || "",
+    distinct_tools: numberOrZero(user.distinct_tools),
+    shadow_tools: numberOrZero(user.shadow_tools),
+    most_used_tool: user.most_used_tool || "",
+    connections: numberOrZero(user.connections)
+  }));
+}
+
+function formatShadowStats(stats, days) {
+  const evolution = stats?.evolution && typeof stats.evolution === "object" ? stats.evolution : {};
+  return [
+    `Shadow AI stats (${stats?.period_days || days} days)`,
+    `Tools detected: ${numberOrZero(stats?.total_tools_detected)}${formatDelta(evolution.total_tools_detected)}`,
+    `Connections: ${numberOrZero(stats?.total_connections)}${formatDelta(evolution.total_connections)}`,
+    `Shadow tools: ${numberOrZero(stats?.shadow_tools)}${formatDelta(evolution.shadow_tools)}`,
+    `Shadow users: ${numberOrZero(stats?.shadow_users)}${formatDelta(evolution.shadow_users)}`,
+    `High-risk tools: ${numberOrZero(stats?.high_risk_tools)}${formatDelta(evolution.high_risk_tools)}`,
+    ""
+  ].join("\n");
+}
+
+function formatDelta(value) {
+  const delta = Number(value || 0);
+  if (!delta) {
+    return "";
+  }
+  return ` (${delta > 0 ? "+" : ""}${delta})`;
+}
+
+function numberOrZero(value) {
+  return Number.isFinite(Number(value)) ? Number(value) : 0;
+}

package/src/commands/siem.js

@@ -0,0 +1,241 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { Command, Option } from "commander";
+
+import { requestApiKeyJson, resolveApiUrlForRequest } from "../lib/api-client.js";
+import { buildSiemCursorKey, readSiemCursor, writeSiemCursor } from "../lib/siem-cursors.js";
+
+const SEVERITIES = ["unknown", "low", "medium", "high", "critical"];
+const OUTPUT_FORMATS = ["jsonl", "json"];
+const MAX_LIMIT = 500;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export function createSiemCommand({
+  stdout = process.stdout,
+  env = process.env
+} = {}) {
+  const command = new Command("siem")
+    .description("Pull SIEM OCSF events");
+
+  command.addCommand(createSiemPullCommand({ stdout, env }));
+  command.addCommand(createSiemTailCommand({ stdout, env }));
+
+  return command;
+}
+
+function createSiemPullCommand({ stdout, env }) {
+  return new Command("pull")
+    .description("Retrieve one page of SIEM events")
+    .option("--api-key <key>", "organization API key; defaults to ZEUSLOCK_API_KEY")
+    .option("--since <cursor>", "backend cursor returned as next_cursor")
+    .option("--from <time>", "start time as ISO date/time or epoch")
+    .option("--to <time>", "end time as ISO date/time or epoch")
+    .option("--days <days>", "look back this many days; mutually exclusive with --from")
+    .option("--category <category>", "event category filter; current dashboard events use dlp")
+    .option("--severity <level>", "minimum severity: unknown, low, medium, high, or critical")
+    .option("--limit <count>", `page size: 1-${MAX_LIMIT}; backend default is 100`)
+    .option("--format <format>", "output format: jsonl or json", "jsonl")
+    .action(async (options) => {
+      const apiUrl = await resolveApiUrlForRequest(env);
+      const filters = parsePullFilters(options);
+      const data = await fetchSiemEvents({
+        apiUrl,
+        apiKey: options.apiKey,
+        env,
+        filters
+      });
+
+      writeSiemEvents(stdout, data, {
+        format: parseChoice(options.format, OUTPUT_FORMATS, "--format"),
+        filters: buildFilterMetadata(filters)
+      });
+    });
+}
+
+function createSiemTailCommand({ stdout, env }) {
+  return new Command("tail")
+    .description("Continuously poll SIEM events with a persistent cursor")
+    .option("--api-key <key>", "organization API key; defaults to ZEUSLOCK_API_KEY")
+    .option("--since <cursor>", "start from this backend cursor instead of the saved cursor")
+    .option("--category <category>", "event category filter; current dashboard events use dlp")
+    .option("--severity <level>", "minimum severity: unknown, low, medium, high, or critical")
+    .option("--limit <count>", `page size per poll: 1-${MAX_LIMIT}; backend default is 100`)
+    .option("--interval <seconds>", "poll interval in seconds", "5")
+    .option("--cursor-name <name>", "local cursor namespace", "default")
+    .option("--reset-cursor", "ignore the saved cursor for this run")
+    .addOption(new Option("--max-polls <count>", "stop after this many polling cycles").hideHelp())
+    .action(async (options) => {
+      const apiUrl = await resolveApiUrlForRequest(env);
+      const interval = parsePositiveNumber(options.interval, "--interval");
+      const maxPolls = options.maxPolls ? parsePositiveInt(options.maxPolls, "--max-polls") : null;
+      const baseFilters = parseTailFilters(options);
+      const cursorKey = buildSiemCursorKey({
+        apiUrl,
+        cursorName: options.cursorName || "default",
+        category: baseFilters.category,
+        severity: baseFilters.severity
+      });
+      let cursor = options.since || (
+        options.resetCursor ? null : await readSiemCursor(cursorKey, env)
+      );
+      let polls = 0;
+
+      for (;;) {
+        const filters = { ...baseFilters, since: cursor };
+        const data = await fetchSiemEvents({
+          apiUrl,
+          apiKey: options.apiKey,
+          env,
+          filters
+        });
+
+        writeSiemEvents(stdout, data, {
+          format: "jsonl",
+          filters: buildFilterMetadata(filters)
+        });
+
+        if (data?.next_cursor) {
+          cursor = data.next_cursor;
+          await writeSiemCursor(cursorKey, {
+            cursor,
+            apiUrl,
+            cursorName: options.cursorName || "default",
+            category: baseFilters.category || null,
+            severity: baseFilters.severity || null
+          }, env);
+        }
+
+        polls += 1;
+        if (maxPolls !== null && polls >= maxPolls) {
+          return;
+        }
+
+        await sleep(interval * 1000);
+      }
+    });
+}
+
+async function fetchSiemEvents({ apiUrl, apiKey, env, filters }) {
+  const params = new URLSearchParams();
+  addParam(params, "since", filters.since);
+  addParam(params, "category", filters.category);
+  addParam(params, "severity", filters.severity);
+  addParam(params, "start_time", filters.startTime);
+  addParam(params, "end_time", filters.endTime);
+  addParam(params, "limit", filters.limit);
+
+  const query = params.toString();
+  return requestApiKeyJson(`/api/v1/siem/events${query ? `?${query}` : ""}`, {
+    apiUrl,
+    apiKey,
+    env
+  });
+}
+
+function parsePullFilters(options) {
+  if (options.days && options.from) {
+    throw new Error("--days and --from are mutually exclusive.");
+  }
+
+  return {
+    since: normalizeOptionalString(options.since),
+    category: normalizeOptionalString(options.category)?.toLowerCase() || null,
+    severity: parseOptionalChoice(options.severity, SEVERITIES, "--severity"),
+    startTime: options.days ? daysToStartTime(options.days) : normalizeOptionalString(options.from),
+    endTime: normalizeOptionalString(options.to),
+    limit: options.limit ? parseLimit(options.limit) : null
+  };
+}
+
+function parseTailFilters(options) {
+  return {
+    since: null,
+    category: normalizeOptionalString(options.category)?.toLowerCase() || null,
+    severity: parseOptionalChoice(options.severity, SEVERITIES, "--severity"),
+    startTime: null,
+    endTime: null,
+    limit: options.limit ? parseLimit(options.limit) : null
+  };
+}
+
+function writeSiemEvents(stdout, data, { format, filters }) {
+  const events = Array.isArray(data?.events) ? data.events : [];
+  if (format === "json") {
+    stdout.write(`${JSON.stringify({
+      events,
+      next_cursor: data?.next_cursor || null,
+      filters
+    })}\n`);
+    return;
+  }
+
+  for (const event of events) {
+    stdout.write(`${JSON.stringify(event)}\n`);
+  }
+}
+
+function buildFilterMetadata(filters) {
+  return {
+    since: filters.since || null,
+    category: filters.category || null,
+    severity: filters.severity || null,
+    start_time: filters.startTime || null,
+    end_time: filters.endTime || null,
+    limit: filters.limit || null
+  };
+}
+
+function daysToStartTime(value) {
+  const days = parsePositiveInt(value, "--days");
+  return new Date(Date.now() - days * DAY_MS).toISOString();
+}
+
+function parseLimit(value) {
+  const limit = parsePositiveInt(value, "--limit");
+  if (limit > MAX_LIMIT) {
+    throw new Error(`Invalid --limit. Allowed values: 1-${MAX_LIMIT}.`);
+  }
+  return limit;
+}
+
+function parsePositiveInt(value, optionName) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 1) {
+    throw new Error(`Invalid ${optionName}. Value must be a positive integer.`);
+  }
+  return number;
+}
+
+function parsePositiveNumber(value, optionName) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) {
+    throw new Error(`Invalid ${optionName}. Value must be a positive number.`);
+  }
+  return number;
+}
+
+function parseOptionalChoice(value, allowed, optionName) {
+  const normalized = normalizeOptionalString(value)?.toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  return parseChoice(normalized, allowed, optionName);
+}
+
+function parseChoice(value, allowed, optionName) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!allowed.includes(normalized)) {
+    throw new Error(`Invalid ${optionName}. Allowed values: ${allowed.join(", ")}.`);
+  }
+  return normalized;
+}
+
+function normalizeOptionalString(value) {
+  const normalized = String(value || "").trim();
+  return normalized || null;
+}
+
+function addParam(params, key, value) {
+  if (value !== null && value !== undefined && value !== "") {
+    params.set(key, String(value));
+  }
+}

package/src/commands/status.js

@@ -0,0 +1,170 @@
+import { Command } from "commander";
+
+import { requestApiKeyJson, requestJson, resolveApiUrlForRequest } from "../lib/api-client.js";
+import { readApiKeyStore } from "../lib/api-key-store.js";
+import { readAuthStore } from "../lib/auth-store.js";
+import { readEnvConfig } from "../lib/config.js";
+import { getPackageInfo } from "../lib/package-info.js";
+
+const DEFAULT_STATUS_TIMEOUT_MS = 1500;
+
+export function createStatusCommand({ stdout = process.stdout, env = process.env } = {}) {
+  return new Command("status")
+    .description("Print local CLI configuration status")
+    .option("--api-key <key>", "organization API key for license validation; defaults to ZEUSLOCK_API_KEY")
+    .option("--require-license", "return a failing exit code unless backend health and license validation pass")
+    .option("--json", "print machine-readable output")
+    .action(async (options) => {
+      const config = readEnvConfig(env);
+      const auth = await readAuthStore(env);
+      const storedApiKey = await readApiKeyStore(env);
+      const packageInfo = getPackageInfo();
+      const apiUrl = await resolveApiUrlForRequest(env);
+      const apiKey = resolveApiKey(options.apiKey, env, storedApiKey);
+      const [health, readiness, license] = await Promise.all([
+        checkBackendEndpoint(apiUrl, "/healthz", "ok", env),
+        checkBackendEndpoint(apiUrl, "/readyz", "ready", env),
+        checkLicense({ apiUrl, apiKey, env, required: Boolean(options.requireLicense) })
+      ]);
+      const status = {
+        name: packageInfo.name,
+        version: packageInfo.version,
+        node: process.version,
+        apiUrl,
+        authenticated: config.hasApiToken || Boolean(auth?.accessToken),
+        apiKeyConfigured: Boolean(apiKey),
+        backend: {
+          health,
+          readiness
+        },
+        license
+      };
+
+      if (options.json) {
+        stdout.write(`${JSON.stringify(status)}\n`);
+      } else {
+        stdout.write(`ZeusLock CLI ${status.version}\n`);
+        stdout.write(`Node: ${status.node}\n`);
+        stdout.write(`API URL: ${status.apiUrl ?? "not configured"}\n`);
+        stdout.write(`Auth token: ${status.authenticated ? "configured" : "not configured"}\n`);
+        stdout.write(`Org API key: ${status.apiKeyConfigured ? "configured" : "not configured"}\n`);
+        stdout.write(`Backend health: ${formatBackendCheck(health)}\n`);
+        stdout.write(`Backend readiness: ${formatBackendCheck(readiness)}\n`);
+        stdout.write(`License: ${formatLicenseCheck(license)}\n`);
+      }
+
+      if (options.requireLicense && shouldFailRequiredStatus(status)) {
+        process.exitCode = 1;
+      }
+    });
+}
+
+async function checkBackendEndpoint(apiUrl, endpoint, expectedStatus, env) {
+  try {
+    const data = await requestJson(apiUrl, endpoint, {
+      signal: buildTimeoutSignal(env)
+    });
+    const status = data?.status || expectedStatus;
+    const ok = status === expectedStatus;
+    return {
+      ok,
+      status,
+      error: ok ? null : `Expected status ${expectedStatus}`
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      status: "error",
+      httpStatus: error?.status ?? null,
+      error: error?.message || "Backend check failed"
+    };
+  }
+}
+
+async function checkLicense({ apiUrl, apiKey, env, required }) {
+  if (!apiKey) {
+    return {
+      status: required ? "missing_api_key" : "skipped",
+      valid: false,
+      checked: false,
+      error: required ? "API key is required for license validation." : null
+    };
+  }
+
+  try {
+    const data = await requestApiKeyJson("/api/v1/validate-license", {
+      apiUrl,
+      apiKey,
+      env,
+      method: "POST",
+      signal: buildTimeoutSignal(env),
+      body: {
+        source: "desktop_agent"
+      }
+    });
+    const valid = data?.valid === true || data?.ok === true;
+    return {
+      status: valid ? "valid" : "invalid",
+      valid,
+      checked: true,
+      organization: data?.organization || null,
+      features: Array.isArray(data?.features) ? data.features : [],
+      limits: data?.limits && typeof data.limits === "object" ? data.limits : {},
+      error: data?.error || null
+    };
+  } catch (error) {
+    return {
+      status: "error",
+      valid: false,
+      checked: true,
+      error: error?.message || "License validation failed"
+    };
+  }
+}
+
+function buildTimeoutSignal(env) {
+  const timeoutMs = Number(env.ZEUSLOCK_STATUS_TIMEOUT_MS) || DEFAULT_STATUS_TIMEOUT_MS;
+  if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") {
+    return AbortSignal.timeout(timeoutMs);
+  }
+
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), timeoutMs).unref?.();
+  return controller.signal;
+}
+
+function resolveApiKey(optionValue, env, storedApiKey) {
+  return String(optionValue || env.ZEUSLOCK_API_KEY || storedApiKey?.apiKey || "").trim();
+}
+
+function formatBackendCheck(check) {
+  if (check.ok) {
+    return check.status;
+  }
+  return `error (${check.error})`;
+}
+
+function formatLicenseCheck(license) {
+  if (license.status === "skipped") {
+    return "skipped (API key not configured)";
+  }
+  if (license.status === "missing_api_key") {
+    return "missing API key";
+  }
+  if (license.status === "valid") {
+    const org = license.organization?.name || license.organization?.org_id;
+    return org ? `valid (${org})` : "valid";
+  }
+  if (license.status === "invalid") {
+    return `invalid${license.error ? ` (${license.error})` : ""}`;
+  }
+  return `error (${license.error || "license validation failed"})`;
+}
+
+function shouldFailRequiredStatus(status) {
+  return (
+    status.backend.health.ok !== true ||
+    status.backend.readiness.ok !== true ||
+    status.license.valid !== true
+  );
+}