zeuslock-dlp-cli 0.2.0

package/src/commands/rules.js

@@ -0,0 +1,432 @@
+import { access, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { Command } from "commander";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+import { requestAuthenticatedJson } from "../lib/api-client.js";
+
+const SCOPES = ["policies", "default", "policy"];
+const EXPORT_FORMATS = ["yaml", "json"];
+const DIFF_FORMATS = ["text", "json"];
+const DEFAULT_DIFF_FILES = [
+  "zeuslock.rules.yaml",
+  "zeuslock.rules.yml",
+  "zeuslock.rules.json"
+];
+const SCHEMA_VERSION = "zeuslock.rules.v1";
+const OMITTED_KEYS = new Set([
+  "created_at",
+  "updated_at",
+  "org_id",
+  "sk",
+  "created_by"
+]);
+
+export function createRulesCommand({
+  stdout = process.stdout,
+  env = process.env
+} = {}) {
+  const command = new Command("rules")
+    .description("Export and compare DLP policies as code");
+
+  command.addCommand(createRulesGetCommand({ stdout, env }));
+  command.addCommand(createRulesDiffCommand({ stdout, env }));
+
+  return command;
+}
+
+function createRulesGetCommand({ stdout, env }) {
+  return new Command("get")
+    .description("Export DLP rules as YAML or JSON")
+    .option("--scope <scope>", "export scope: policies, default, or policy", "policies")
+    .option("--policy-id <id>", "policy id; required with --scope policy")
+    .option("--format <format>", "export format: yaml or json", "yaml")
+    .option("--output <path>", "write export to a file instead of stdout")
+    .action(async (options) => {
+      const scope = parseChoice(options.scope, SCOPES, "--scope");
+      const format = parseChoice(options.format, EXPORT_FORMATS, "--format");
+      validateScopeOptions({ scope, policyId: options.policyId });
+
+      const document = await fetchRulesDocument({ scope, policyId: options.policyId, env });
+      const content = serializeDocument(document, format);
+
+      if (!options.output) {
+        stdout.write(content);
+        return;
+      }
+
+      const outputPath = path.resolve(options.output);
+      await writeFile(outputPath, content, "utf8");
+      stdout.write(`Exported ${scope} rules to ${outputPath}\n`);
+    });
+}
+
+function createRulesDiffCommand({ stdout, env }) {
+  return new Command("diff")
+    .description("Compare a local rules file against live DLP policy state")
+    .argument("[file]", "YAML or JSON file exported by `zeuslock rules get`")
+    .option("--scope <scope>", "diff scope: policies, default, or policy", "policies")
+    .option("--policy-id <id>", "policy id; required with --scope policy")
+    .option("--format <format>", "diff output format: text or json", "text")
+    .action(async (file, options) => {
+      const scope = parseChoice(options.scope, SCOPES, "--scope");
+      const format = parseChoice(options.format, DIFF_FORMATS, "--format");
+      validateScopeOptions({ scope, policyId: options.policyId });
+
+      const filePath = await resolveDiffFile(file);
+      const localDocument = normalizeDocumentForScope(parseDocumentFile(await readFile(filePath, "utf8"), filePath), scope);
+      const liveDocument = await fetchRulesDocument({ scope, policyId: options.policyId, env });
+      const differences = diffValues(localDocument, liveDocument);
+
+      if (format === "json") {
+        stdout.write(`${JSON.stringify({
+          different: differences.length > 0,
+          total: differences.length,
+          differences
+        })}\n`);
+      } else if (differences.length === 0) {
+        stdout.write("No differences found\n");
+      } else {
+        stdout.write(formatDiffText(differences));
+      }
+
+      if (differences.length > 0) {
+        process.exitCode = 1;
+      }
+    });
+}
+
+async function fetchRulesDocument({ scope, policyId, env }) {
+  if (scope === "default") {
+    const rules = await requestAuthenticatedJson("/api/rules", { env });
+    return normalizeDocumentForScope({ scope, rules }, scope);
+  }
+
+  if (scope === "policy") {
+    const policy = await requestAuthenticatedJson(`/api/policies/${encodeURIComponent(policyId)}`, { env });
+    return normalizeDocumentForScope({ scope, policy }, scope);
+  }
+
+  const policiesData = await requestAuthenticatedJson("/api/policies", { env });
+  const groupsData = await requestAuthenticatedJson("/api/groups", { env });
+  return normalizeDocumentForScope({
+    scope,
+    policies: Array.isArray(policiesData) ? policiesData : (policiesData.policies || []),
+    groups: Array.isArray(groupsData) ? groupsData : (groupsData.groups || [])
+  }, scope);
+}
+
+function normalizeDocumentForScope(document, scope) {
+  if (document?.scope && document.scope !== scope) {
+    throw new Error(`Rules file scope is ${document.scope}; expected ${scope}.`);
+  }
+
+  if (scope === "default") {
+    const rules = document?.rules || document || {};
+    return {
+      schema_version: SCHEMA_VERSION,
+      scope,
+      rules: normalizeRules(rules)
+    };
+  }
+
+  if (scope === "policy") {
+    const policy = document?.policy || document || {};
+    return {
+      schema_version: SCHEMA_VERSION,
+      scope,
+      policy: normalizePolicy(policy)
+    };
+  }
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    scope,
+    policies: normalizePolicies(document?.policies || []),
+    groups: normalizeGroups(document?.groups || [])
+  };
+}
+
+function normalizePolicies(policies) {
+  return policies
+    .map(normalizePolicy)
+    .sort((a, b) =>
+      Number(Boolean(b.is_default)) - Number(Boolean(a.is_default)) ||
+      numberOr(a.priority, 0) - numberOr(b.priority, 0) ||
+      String(a.name || "").localeCompare(String(b.name || "")) ||
+      String(a.policy_id || "").localeCompare(String(b.policy_id || ""))
+    );
+}
+
+function normalizePolicy(policy = {}) {
+  const normalized = {
+    policy_id: stringOrEmpty(policy.policy_id),
+    name: stringOrEmpty(policy.name),
+    description: stringOrEmpty(policy.description),
+    status: stringOrEmpty(policy.status),
+    priority: numberOr(policy.priority, 0),
+    version: numberOr(policy.version, 1),
+    is_default: Boolean(policy.is_default),
+    rules: normalizeRules(policy.rules || {})
+  };
+
+  if (policy.template_id) {
+    normalized.template_id = String(policy.template_id);
+  }
+  if (policy.template_version !== undefined && policy.template_version !== null) {
+    normalized.template_version = numberOr(policy.template_version, policy.template_version);
+  }
+
+  return stableSortObject(normalized);
+}
+
+function normalizeGroups(groups) {
+  return groups
+    .map(normalizeGroup)
+    .sort((a, b) =>
+      Number(Boolean(b.is_default)) - Number(Boolean(a.is_default)) ||
+      numberOr(a.priority, 0) - numberOr(b.priority, 0) ||
+      String(a.name || "").localeCompare(String(b.name || "")) ||
+      String(a.group_id || "").localeCompare(String(b.group_id || ""))
+    );
+}
+
+function normalizeGroup(group = {}) {
+  return stableSortObject({
+    group_id: stringOrEmpty(group.group_id),
+    name: stringOrEmpty(group.name),
+    description: stringOrEmpty(group.description),
+    policy_id: stringOrEmpty(group.policy_id),
+    priority: numberOr(group.priority, 0),
+    is_default: Boolean(group.is_default),
+    matchers: normalizeMatchers(group.matchers || [])
+  });
+}
+
+function normalizeMatchers(matchers) {
+  return matchers
+    .map((matcher) => stableSortObject({
+      type: stringOrEmpty(matcher?.type),
+      value: normalizeLooseValue(matcher?.value),
+      display: stringOrEmpty(matcher?.display),
+      match_by: matcher?.match_by ?? null,
+      enabled: matcher?.enabled !== false
+    }))
+    .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+}
+
+function normalizeRules(rules = {}) {
+  const normalized = {};
+
+  if (rules.version !== undefined && rules.version !== null) {
+    normalized.version = numberOr(rules.version, rules.version);
+  }
+
+  normalized.modes = stableSortObject(rules.modes || {});
+  normalized.customRules = normalizeCustomRules(rules.customRules || []);
+
+  const extras = {};
+  for (const [key, value] of Object.entries(rules || {})) {
+    if (key === "version" || key === "modes" || key === "customRules" || OMITTED_KEYS.has(key)) {
+      continue;
+    }
+    extras[key] = normalizeLooseValue(value);
+  }
+
+  return stableSortObject({
+    ...normalized,
+    ...stableSortObject(extras)
+  });
+}
+
+function normalizeCustomRules(customRules) {
+  return customRules
+    .map((rule) => stableSortObject(normalizeLooseObject(rule || {})))
+    .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+}
+
+function normalizeLooseValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(normalizeLooseValue);
+  }
+  if (isPlainObject(value)) {
+    return stableSortObject(normalizeLooseObject(value));
+  }
+  return value;
+}
+
+function normalizeLooseObject(value) {
+  const out = {};
+  for (const [key, entry] of Object.entries(value || {})) {
+    if (!OMITTED_KEYS.has(key)) {
+      out[key] = normalizeLooseValue(entry);
+    }
+  }
+  return out;
+}
+
+function serializeDocument(document, format) {
+  if (format === "json") {
+    return `${JSON.stringify(document, null, 2)}\n`;
+  }
+  return stringifyYaml(document, { lineWidth: 0 });
+}
+
+function parseDocumentFile(raw, filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+
+  try {
+    if (extension === ".json") {
+      return JSON.parse(raw);
+    }
+    if (extension === ".yaml" || extension === ".yml") {
+      return parseYaml(raw);
+    }
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return parseYaml(raw);
+    }
+  } catch (error) {
+    throw new Error(`Failed to parse ${filePath}: ${error.message}`);
+  }
+}
+
+async function resolveDiffFile(file) {
+  if (file) {
+    return path.resolve(file);
+  }
+
+  for (const candidate of DEFAULT_DIFF_FILES) {
+    const resolved = path.resolve(candidate);
+    try {
+      await access(resolved);
+      return resolved;
+    } catch {
+      // Try the next conventional export filename.
+    }
+  }
+
+  throw new Error(`No rules file specified and none found: ${DEFAULT_DIFF_FILES.join(", ")}.`);
+}
+
+function diffValues(fileValue, liveValue, currentPath = "$") {
+  if (Object.is(fileValue, liveValue)) {
+    return [];
+  }
+
+  if (Array.isArray(fileValue) || Array.isArray(liveValue)) {
+    if (!Array.isArray(fileValue) || !Array.isArray(liveValue)) {
+      return [difference("changed", currentPath, fileValue, liveValue)];
+    }
+
+    const diffs = [];
+    const length = Math.max(fileValue.length, liveValue.length);
+    for (let index = 0; index < length; index += 1) {
+      if (index >= fileValue.length) {
+        diffs.push(difference("only_in_live", `${currentPath}[${index}]`, undefined, liveValue[index]));
+      } else if (index >= liveValue.length) {
+        diffs.push(difference("only_in_file", `${currentPath}[${index}]`, fileValue[index], undefined));
+      } else {
+        diffs.push(...diffValues(fileValue[index], liveValue[index], `${currentPath}[${index}]`));
+      }
+    }
+    return diffs;
+  }
+
+  if (isPlainObject(fileValue) || isPlainObject(liveValue)) {
+    if (!isPlainObject(fileValue) || !isPlainObject(liveValue)) {
+      return [difference("changed", currentPath, fileValue, liveValue)];
+    }
+
+    const keys = Array.from(new Set([
+      ...Object.keys(fileValue),
+      ...Object.keys(liveValue)
+    ])).sort();
+    const diffs = [];
+    for (const key of keys) {
+      const nextPath = `${currentPath}.${key}`;
+      if (!(key in liveValue)) {
+        diffs.push(difference("only_in_file", nextPath, fileValue[key], undefined));
+      } else if (!(key in fileValue)) {
+        diffs.push(difference("only_in_live", nextPath, undefined, liveValue[key]));
+      } else {
+        diffs.push(...diffValues(fileValue[key], liveValue[key], nextPath));
+      }
+    }
+    return diffs;
+  }
+
+  return [difference("changed", currentPath, fileValue, liveValue)];
+}
+
+function difference(type, diffPath, fileValue, liveValue) {
+  return {
+    type,
+    path: diffPath,
+    file: fileValue,
+    live: liveValue
+  };
+}
+
+function formatDiffText(differences) {
+  const lines = [`Found ${differences.length} difference${differences.length === 1 ? "" : "s"}`];
+  for (const diff of differences) {
+    lines.push(`${diff.type} ${diff.path}`);
+    if (diff.type !== "only_in_live") {
+      lines.push(`  file: ${formatDiffValue(diff.file)}`);
+    }
+    if (diff.type !== "only_in_file") {
+      lines.push(`  live: ${formatDiffValue(diff.live)}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function formatDiffValue(value) {
+  if (value === undefined) {
+    return "<missing>";
+  }
+  return JSON.stringify(value);
+}
+
+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 validateScopeOptions({ scope, policyId }) {
+  if (scope === "policy" && !String(policyId || "").trim()) {
+    throw new Error("--policy-id is required with --scope policy.");
+  }
+  if (scope !== "policy" && String(policyId || "").trim()) {
+    throw new Error("--policy-id can only be used with --scope policy.");
+  }
+}
+
+function stableSortObject(value) {
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const out = {};
+  for (const key of Object.keys(value).sort()) {
+    out[key] = normalizeLooseValue(value[key]);
+  }
+  return out;
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function stringOrEmpty(value) {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function numberOr(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}

package/src/commands/scan.js

@@ -0,0 +1,178 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Command } from "commander";
+
+import {
+  analyzeDlpBatch,
+  formatDlpSummary,
+  parseFailOn,
+  shouldFailDecision,
+  summarizeDlpResponses
+} from "../lib/dlp-scan.js";
+
+const BATCH_SIZE = 5;
+
+export function createScanCommand({
+  stdin = process.stdin,
+  stdout = process.stdout,
+  env = process.env
+} = {}) {
+  return new Command("scan")
+    .description("Analyze files or stdin with the organization's DLP policy")
+    .argument("[path]", "file or directory to scan")
+    .option("--stdin", "read text from stdin")
+    .option("--api-key <key>", "organization API key; defaults to saved key or ZEUSLOCK_API_KEY")
+    .option("--fail-on <decision>", "exit nonzero on alert, block, or never", "block")
+    .option("--source <source>", "source label sent to backend", "cli")
+    .option("--platform <platform>", "platform label sent to backend", "cli")
+    .option("--hostname <hostname>", "hostname sent to backend")
+    .option("--path <path>", "destination path label sent to backend")
+    .option("--user-email <email>", "user email label sent to backend")
+    .option("--include-sensitive", "include backend anonymization maps in JSON output")
+    .option("--json", "print machine-readable output")
+    .action(async (inputPath, options) => {
+      validateInput(inputPath, options);
+      const failOn = parseFailOn(options.failOn);
+      const metadata = buildMetadata(options, inputPath);
+      let responses = [];
+      let scannedFiles = 0;
+      let scannedText = false;
+
+      if (options.stdin) {
+        const text = await readStream(stdin);
+        scannedText = true;
+        responses.push(await analyzeDlpBatch({
+          text,
+          metadata: {
+            ...metadata,
+            path: options.path || "/cli/stdin"
+          },
+          apiKey: options.apiKey,
+          env
+        }));
+      } else {
+        const files = await loadInputFiles(inputPath);
+        scannedFiles = files.length;
+        for (const batch of chunk(files, BATCH_SIZE)) {
+          responses.push(await analyzeDlpBatch({
+            files: batch,
+            metadata,
+            apiKey: options.apiKey,
+            env
+          }));
+        }
+      }
+
+      const summary = summarizeDlpResponses(responses, {
+        failOn,
+        includeSensitive: Boolean(options.includeSensitive)
+      });
+
+      if (options.json) {
+        stdout.write(`${JSON.stringify({
+          ...summary,
+          scanned: {
+            text: scannedText,
+            files: scannedFiles
+          }
+        })}\n`);
+      } else {
+        stdout.write(formatDlpSummary(summary, { scannedFiles, scannedText }));
+      }
+
+      if (summary.responses.some((response) => shouldFailDecision(response?.decision, failOn))) {
+        process.exitCode = 1;
+      }
+    });
+}
+
+function validateInput(inputPath, options) {
+  if (options.stdin && inputPath) {
+    throw new Error("Pass either --stdin or a path, not both.");
+  }
+  if (!options.stdin && !inputPath) {
+    throw new Error("A file, directory, or --stdin is required.");
+  }
+}
+
+function buildMetadata(options, inputPath) {
+  return {
+    source: options.source,
+    platform: options.platform,
+    hostname: options.hostname || os.hostname(),
+    path: options.path || defaultPathLabel(inputPath),
+    method: "CLI",
+    userEmail: options.userEmail || null
+  };
+}
+
+function defaultPathLabel(inputPath) {
+  if (!inputPath) {
+    return "/cli";
+  }
+  const resolved = path.resolve(inputPath);
+  return `/cli/${path.basename(resolved)}`;
+}
+
+async function loadInputFiles(inputPath) {
+  const resolved = path.resolve(inputPath);
+  const inputStat = await stat(resolved);
+  if (inputStat.isFile()) {
+    return [await loadFile(resolved)];
+  }
+  if (!inputStat.isDirectory()) {
+    throw new Error(`Unsupported input path: ${resolved}`);
+  }
+
+  const files = [];
+  for (const filePath of await collectDirectoryFiles(resolved)) {
+    files.push(await loadFile(filePath));
+  }
+  if (!files.length) {
+    throw new Error(`No files found in directory: ${resolved}`);
+  }
+  return files;
+}
+
+async function collectDirectoryFiles(dirPath) {
+  const entries = await readdir(dirPath, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name === ".git") {
+      continue;
+    }
+    const entryPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await collectDirectoryFiles(entryPath));
+    } else if (entry.isFile()) {
+      files.push(entryPath);
+    }
+  }
+  return files.sort();
+}
+
+async function loadFile(filePath) {
+  return {
+    filename: path.basename(filePath),
+    path: filePath,
+    contentType: "application/octet-stream",
+    data: await readFile(filePath)
+  };
+}
+
+async function readStream(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function chunk(items, size) {
+  const batches = [];
+  for (let i = 0; i < items.length; i += size) {
+    batches.push(items.slice(i, i + size));
+  }
+  return batches;
+}