Security Detection Rule Management

#!/usr/bin/env node
/**
 * Add an exception item to the Endpoint Security Exception List.
 *
 * Endpoint exceptions are stored in the Endpoint Security Exception List
 * (Security → Exceptions → Endpoint Security Exception List, /app/security/exceptions).
 * They are separate from SIEM/detection rule exceptions. This script uses
 * POST /api/endpoint_list/items to add an item directly to that list.
 *
 * See: https://www.elastic.co/docs/solutions/security/detect-and-alert/add-manage-exceptions#endpoint-rule-exceptions
 * API: https://www.elastic.co/docs/api/doc/kibana/operation/operation-createexceptionlistitem
 */

import { kibanaPost, kibanaDelete as kibanaDeleteReq } from "./kibana-client.js";
import { createInterface } from "readline";

const ENDPOINT_LIST_ITEMS_API = "/api/endpoint_list/items";

function promptConfirm(message) {
  const rl = createInterface({ input: process.stdin, output: process.stderr });
  return new Promise((resolve) => {
    rl.question(`${message} [y/N] `, (answer) => {
      rl.close();
      resolve(answer.trim().toLowerCase() === "y");
    });
  });
}

const OP_MAP = {
  is: ["match", "included"],
  is_not: ["match", "excluded"],
  is_one_of: ["match_any", "included"],
  is_not_one_of: ["match_any", "excluded"],
  exists: ["exists", "included"],
  does_not_exist: ["exists", "excluded"],
  matches: ["wildcard", "included"],
  does_not_match: ["wildcard", "excluded"],
};

function parseEntry(entryStr) {
  const parts = entryStr.split(":");
  let field, operator, value;

  if (parts.length >= 3) {
    field = parts[0];
    operator = parts[1];
    value = parts.slice(2).join(":");
  } else if (parts.length === 2) {
    [field, value] = parts;
    operator = "is";
  } else {
    throw new Error(`Invalid entry format '${entryStr}'. Use field:operator:value or field:value`);
  }

  const mapped = OP_MAP[operator];
  if (!mapped) {
    throw new Error(`Unknown operator '${operator}'. Use: ${Object.keys(OP_MAP).join(", ")}`);
  }

  const [entryType, listOperator] = mapped;
  const entry = { field, type: entryType, operator: listOperator };
  if (entryType === "match") entry.value = value;
  else if (entryType === "match_any") entry.value = value.split(",").map((v) => v.trim());
  else if (entryType === "wildcard") entry.value = value;
  return entry;
}

function makeItemId(name) {
  const slug = name
    .toLowerCase()
    .replace(/[^\w-]/g, "-")
    .replace(/^-+|-+$/g, "")
    .slice(0, 40);
  const rand = crypto.randomUUID().slice(0, 8);
  return slug ? `${slug}-${rand}` : `endpoint-exception-${rand}`;
}

function parseArgs(argv) {
  const result = {};
  for (let i = 0; i < argv.length; i++) {
    const arg = argv[i];
    if (arg === "-y") {
      result.yes = true;
    } else if (arg.startsWith("--")) {
      const key = arg.slice(2).replace(/-/g, "_");
      const values = [];
      let j = i + 1;
      while (j < argv.length && !argv[j].startsWith("--") && argv[j] !== "-y") {
        values.push(argv[j]);
        j++;
      }
      result[key] = values.length === 0 ? true : values.length === 1 ? values[0] : values;
      i = j - 1;
    }
  }
  return result;
}

async function main() {
  const args = parseArgs(process.argv.slice(2));
  const yes = args.yes === true;

  if (args.delete) {
    if (!args.item_id && !args.id) {
      console.error("Error: provide --item-id or --id to delete");
      process.exit(1);
    }
    if (!yes) {
      const ok = await promptConfirm(`Delete endpoint exception ${args.item_id || args.id}? This cannot be undone.`);
      if (!ok) {
        console.log("Aborted.");
        process.exit(0);
      }
    }
    const qs = args.item_id ? `?item_id=${args.item_id}` : `?id=${args.id}`;
    const result = await kibanaDeleteReq(`${ENDPOINT_LIST_ITEMS_API}${qs}`, args.space);
    console.log(JSON.stringify(result, null, 2));
    return;
  }

  if (!args.name || !args.entries) {
    console.error("Error: --name and --entries are required when adding an exception");
    console.error("");
    console.error('Usage: node add-endpoint-exception.js --name "Exception name" --entries field:operator:value ...');
    console.error("");
    console.error("IMPORTANT: To limit the exception to a specific rule, always include rule.id or rule.name");
    console.error("as one of the entries: rule.id:is:<uuid> or rule.name:is:<exact rule name>.");
    console.error("");
    console.error("Operators: is, is_not, is_one_of, is_not_one_of, matches, does_not_match, exists, does_not_exist");
    process.exit(1);
  }

  const entryStrs = Array.isArray(args.entries) ? args.entries : [args.entries];
  const parsed = entryStrs.map(parseEntry);

  let desc = args.description || "";
  if (args.comment) {
    desc = desc ? `${desc}\nComment: ${args.comment}` : args.comment;
  }

  const item = {
    name: args.name,
    item_id: args.item_id || makeItemId(args.name),
    description: desc,
    type: "simple",
    entries: parsed,
    namespace_type: "agnostic",
    list_id: "endpoint_list",
  };

  if (args.tags) {
    item.tags = Array.isArray(args.tags) ? args.tags : [args.tags];
  }
  if (args.os_types) {
    const types = Array.isArray(args.os_types) ? args.os_types : [args.os_types];
    item.os_types = types.map((t) => t.trim().toLowerCase());
  }

  if (!yes) {
    const ok = await promptConfirm(`Add endpoint exception "${args.name}"?`);
    if (!ok) {
      console.log("Aborted.");
      process.exit(0);
    }
  }

  const result = await kibanaPost(ENDPOINT_LIST_ITEMS_API, item, args.space);
  console.log(JSON.stringify(result, null, 2));
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
  process.exit(1);
});

#!/usr/bin/env node
/**
 * Print the endpoint rule exclusion best-practices checklist.
 * Use when designing Endpoint exceptions or contributing rule changes to ensure
 * evasion-resilient, performant exclusions. Full guide: references/endpoint-rule-exclusion-best-practices.md
 */

import { readFileSync, existsSync } from "fs";
import { join, dirname } from "path";
import { fileURLToPath } from "url";

const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
const REF_DIR = join(SCRIPT_DIR, "..", "references");
const BEST_PRACTICES_FILE = join(REF_DIR, "endpoint-rule-exclusion-best-practices.md");

const EMBEDDED_CHECKLIST = `\
- [ ] Paths: ?:\\\\ for drive-agnostic; : for case-insensitivity; wildcards ONLY for variable segments
- [ ] LOLBins/scripting: combine name or path WITH args or cmdline; prefer args + path over command_line wildcards
- [ ] API rules: no process-only exclusions; use call_stack_final_user_module or call_stack_summary for benign patterns
- [ ] User-writable paths: not excluded unconditionally; gate by trust/code signature when used
- [ ] No in-query comments that duplicate the PR/description
- [ ] When contributing rule changes: updated_date set; sample alerts (if ≤3–5 patterns) in description with <details>/<summary>; PII stripped`;

const fullMode = process.argv.includes("--full");

if (!existsSync(BEST_PRACTICES_FILE)) {
  console.log("Checklist (see references/endpoint-rule-exclusion-best-practices.md for full guide):\n");
  console.log(EMBEDDED_CHECKLIST);
  process.exit(0);
}

const content = readFileSync(BEST_PRACTICES_FILE, "utf8");

if (fullMode) {
  console.log(content);
  process.exit(0);
}

let inChecklist = false;
let found = false;
for (const line of content.split("\n")) {
  if (line.trim().startsWith("## Checklist")) {
    inChecklist = true;
    found = true;
    console.log(line);
    console.log();
    continue;
  }
  if (inChecklist) {
    if (line.startsWith("## ") && !line.startsWith("## Checklist")) break;
    console.log(line);
  }
}

if (!found) {
  console.log(EMBEDDED_CHECKLIST);
  console.log("\nFull guide: references/endpoint-rule-exclusion-best-practices.md");
}

/**
 * Elasticsearch client factory for SOC skills.
 * Supports Cloud ID, direct URL, API key, and basic auth.
 */

import { Client } from "@elastic/elasticsearch";

try {
  process.loadEnvFile();
} catch {}

/**
 * Create and return an Elasticsearch client using environment variables.
 */
export function createClient() {
  const cloudId = process.env.ELASTICSEARCH_CLOUD_ID;
  const apiKey = process.env.ELASTICSEARCH_API_KEY;
  const url = process.env.ELASTICSEARCH_URL;
  const username = process.env.ELASTICSEARCH_USERNAME;
  const password = process.env.ELASTICSEARCH_PASSWORD;
  const insecure = process.env.ELASTICSEARCH_INSECURE === "true";

  const config = {};

  if (cloudId) {
    config.cloud = { id: cloudId };
  } else if (url) {
    config.node = url;
  } else {
    console.error("Error: No Elasticsearch connection configured.");
    console.error("Set ELASTICSEARCH_CLOUD_ID or ELASTICSEARCH_URL environment variable.");
    process.exit(1);
  }

  if (apiKey) {
    config.auth = { apiKey };
  } else if (username && password) {
    config.auth = { username, password };
  } else if (username || password) {
    console.error("Error: Both ELASTICSEARCH_USERNAME and ELASTICSEARCH_PASSWORD must be set for basic auth.");
    process.exit(1);
  }

  if (insecure) {
    config.tls = { rejectUnauthorized: false };
  }

  config.headers = { "User-Agent": "elastic-agentic" };

  return new Client(config);
}

export async function testConnection() {
  try {
    const client = createClient();
    const info = await client.info();
    console.log(`Connected to Elasticsearch cluster: ${info.cluster_name}`);
    console.log(`Version: ${info.version.number}`);
    await client.close();
    return true;
  } catch (error) {
    console.error(`Connection failed: ${error.message}`);
    return false;
  }
}

#!/usr/bin/env node
/**
 * Fetch endpoint behavior rule content from elastic/protections-artifacts by rule_id.
 * Rule logic is not stored in Elasticsearch; the repo holds the TOML source
 * (description, EQL query with built-in exclusions, threat mapping).
 * Use this after identifying a noisy endpoint rule to understand what it detects and
 * how existing exclusions are expressed before adding an endpoint exception.
 */

import { writeFileSync } from "fs";

const REPO = "elastic/protections-artifacts";
const BRANCH = "main";
const BASE_URL = `https://raw.githubusercontent.com/${REPO}/${BRANCH}/`;
const SEARCH_URL = "https://api.github.com/search/code";
const CONTENTS_URL = `https://api.github.com/repos/${REPO}/contents`;

function headers() {
  const h = { Accept: "application/vnd.github.v3+json", "User-Agent": "elastic-agentic" };
  const token = process.env.GITHUB_TOKEN;
  if (token) h.Authorization = `Bearer ${token}`;
  return h;
}

async function apiGet(url) {
  const resp = await fetch(url, { headers: headers(), signal: AbortSignal.timeout(15000) });
  if (!resp.ok) throw new Error(`GitHub API ${resp.status}: ${resp.statusText}`);
  return resp.json();
}

async function fetchFile(path) {
  const resp = await fetch(BASE_URL + path, { headers: headers(), signal: AbortSignal.timeout(15000) });
  if (!resp.ok) throw new Error(`Failed to fetch ${path}: ${resp.status}`);
  return resp.text();
}

async function walkBehaviorRulesFind(ruleId) {
  const top = await apiGet(`${CONTENTS_URL}/behavior/rules`);
  const dirs = top.filter((x) => x?.type === "dir");

  for (const d of dirs) {
    let files;
    try {
      files = await apiGet(`${CONTENTS_URL}/${encodeURIComponent(d.path)}`);
    } catch {
      continue;
    }
    for (const f of files) {
      if (f?.type !== "file" || !f.name?.endsWith(".toml")) continue;
      const filePath = f.path || `${d.path}/${f.name}`;
      try {
        const raw = await fetchFile(filePath);
        if (raw.includes(ruleId)) return filePath;
      } catch {
        continue;
      }
    }
  }

  throw new Error(
    `No rule file found with rule_id=${ruleId} in ${REPO} behavior/rules. ` +
      "Check that the UUID is the rule's id (TOML id / rule.id in alerts), not the rule's internal id.",
  );
}

async function searchRuleFile(ruleId) {
  const q = `"${ruleId}" repo:${REPO} path:behavior/rules`;
  const url = `${SEARCH_URL}?${new URLSearchParams({ q })}`;

  let data;
  try {
    data = await apiGet(url);
  } catch (e) {
    if (e.message.includes("401") || e.message.includes("403")) {
      return walkBehaviorRulesFind(ruleId);
    }
    throw e;
  }

  const items = data.items || [];
  if (!items.length) return walkBehaviorRulesFind(ruleId);

  const path = items[0].path;
  if (!path?.endsWith(".toml")) return walkBehaviorRulesFind(ruleId);
  return path;
}

function parseArgs(argv) {
  const result = {};
  for (let i = 0; i < argv.length; i++) {
    if (argv[i].startsWith("--")) {
      const key = argv[i].slice(2).replace(/-/g, "_");
      const next = argv[i + 1];
      result[key] = next && !next.startsWith("--") ? (i++, next) : true;
    }
  }
  return result;
}

async function main() {
  const args = parseArgs(process.argv.slice(2));

  if (!args.rule_id) {
    console.error("Usage: node fetch-endpoint-rule-from-github.js --rule-id <uuid>");
    console.error("");
    console.error("For endpoint behavior rules use the rule's id (the UUID in the TOML and rule.id");
    console.error("in alerts), not kibana.alert.rule.rule_id.");
    process.exit(1);
  }

  const ruleId = args.rule_id.trim();
  const path = await searchRuleFile(ruleId);
  const content = await fetchFile(path);

  if (args.output) {
    writeFileSync(args.output, content, "utf8");
    console.error(`Written to ${args.output}`);
  } else {
    console.log(content);
  }
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
  process.exit(1);
});

/**
 * Lightweight HTTP client for the Kibana REST API.
 * Uses native fetch() with auth, retry on 429, and space support.
 */

try {
  process.loadEnvFile();
} catch {}

const RETRY_DELAYS = [5, 10, 20];

export function getKibanaConfig() {
  const url = process.env.KIBANA_URL;
  const apiKey = process.env.KIBANA_API_KEY;
  const username = process.env.KIBANA_USERNAME || process.env.ELASTICSEARCH_USERNAME;
  const password = process.env.KIBANA_PASSWORD || process.env.ELASTICSEARCH_PASSWORD;
  const spaceId = process.env.KIBANA_SPACE_ID;
  const insecure = process.env.KIBANA_INSECURE === "true";

  if (!url) {
    console.error("Error: No Kibana connection configured.");
    console.error("Set KIBANA_URL environment variable.");
    process.exit(1);
  }

  if (!apiKey && !username && !password && process.env.KIBANA_NO_AUTH !== "true") {
    console.error("Error: No Kibana authentication configured.");
    console.error("Set KIBANA_API_KEY or KIBANA_USERNAME + KIBANA_PASSWORD.");
    console.error("Or set KIBANA_NO_AUTH=true for clusters with security disabled.");
    process.exit(1);
  }

  if (!apiKey && ((username && !password) || (!username && password))) {
    console.error("Error: Both username and password must be set for basic auth.");
    console.error("Set KIBANA_USERNAME + KIBANA_PASSWORD (or ELASTICSEARCH_USERNAME + ELASTICSEARCH_PASSWORD).");
    process.exit(1);
  }

  return { url, apiKey, username, password, spaceId, insecure };
}

function getHeaders(config) {
  const headers = {
    "Content-Type": "application/json",
    "kbn-xsrf": "true",
    "User-Agent": "elastic-agentic",
  };

  if (config.apiKey) {
    headers["Authorization"] = `ApiKey ${config.apiKey}`;
  } else if (config.username && config.password) {
    const auth = Buffer.from(`${config.username}:${config.password}`).toString("base64");
    headers["Authorization"] = `Basic ${auth}`;
  }

  return headers;
}

function getBasePath(config, space) {
  let basePath = config.url.replace(/\/$/, "");
  const effectiveSpace = space || config.spaceId;
  if (effectiveSpace && effectiveSpace !== "default") {
    basePath += `/s/${effectiveSpace}`;
  }
  return basePath;
}

/**
 * Make an HTTP request to the Kibana API with automatic 429 retry.
 *
 * @param {string} path - API path (e.g. "/api/cases")
 * @param {object} [options] - fetch options (method, body, headers, params)
 * @param {string} [options.space] - Override Kibana space for this request
 * @returns {{ success: boolean, data?: any, status?: number, error?: string }}
 */
export async function kibanaFetch(path, options = {}) {
  const config = getKibanaConfig();
  const { space, params, ...fetchOpts } = options;
  const basePath = getBasePath(config, space);

  let url = `${basePath}${path}`;
  if (params) {
    const searchParams = new URLSearchParams();
    for (const [key, value] of Object.entries(params)) {
      if (value !== undefined && value !== null) {
        if (Array.isArray(value)) {
          for (const v of value) searchParams.append(key, v);
        } else {
          searchParams.append(key, String(value));
        }
      }
    }
    const qs = searchParams.toString();
    if (qs) url += `?${qs}`;
  }

  const requestOptions = {
    ...fetchOpts,
    headers: {
      ...getHeaders(config),
      ...fetchOpts.headers,
    },
  };

  if (config.insecure) {
    process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
  }

  for (let attempt = 0; attempt <= RETRY_DELAYS.length; attempt++) {
    try {
      const response = await fetch(url, requestOptions);

      if (response.status === 429 && attempt < RETRY_DELAYS.length) {
        const delay = RETRY_DELAYS[attempt];
        console.error(`Rate limited, retrying in ${delay}s (attempt ${attempt + 1}/${RETRY_DELAYS.length + 1})...`);
        await new Promise((r) => setTimeout(r, delay * 1000));
        continue;
      }

      const contentType = response.headers.get("content-type");
      let data;
      if (contentType && contentType.includes("application/json")) {
        data = await response.json();
      } else {
        data = await response.text();
      }

      if (!response.ok) {
        return {
          success: false,
          status: response.status,
          error: data?.message || data?.error || `HTTP ${response.status}`,
          details: data,
        };
      }

      return { success: true, data };
    } catch (error) {
      if (attempt < RETRY_DELAYS.length && error.message?.includes("429")) {
        const delay = RETRY_DELAYS[attempt];
        console.error(`Rate limited, retrying in ${delay}s...`);
        await new Promise((r) => setTimeout(r, delay * 1000));
        continue;
      }
      return { success: false, error: error.message, details: error };
    }
  }
}

/**
 * Convenience wrappers matching the Python KibanaClient interface.
 * These throw on HTTP errors (matching the old behavior where scripts
 * relied on exceptions for error handling).
 */
export async function kibanaGet(path, params, space) {
  const result = await kibanaFetch(path, { method: "GET", params, space });
  if (!result.success) throw new Error(result.error || `HTTP ${result.status}`);
  return result.data;
}

export async function kibanaPost(path, body, space) {
  const result = await kibanaFetch(path, {
    method: "POST",
    body: body !== undefined ? JSON.stringify(body) : undefined,
    space,
  });
  if (!result.success) throw new Error(result.error || `HTTP ${result.status}`);
  return result.data;
}

export async function kibanaPatch(path, body, space) {
  const result = await kibanaFetch(path, {
    method: "PATCH",
    body: body !== undefined ? JSON.stringify(body) : undefined,
    space,
  });
  if (!result.success) throw new Error(result.error || `HTTP ${result.status}`);
  return result.data;
}

export async function kibanaPut(path, body, space) {
  const result = await kibanaFetch(path, {
    method: "PUT",
    body: body !== undefined ? JSON.stringify(body) : undefined,
    space,
  });
  if (!result.success) throw new Error(result.error || `HTTP ${result.status}`);
  return result.data;
}

export async function kibanaDelete(path, space) {
  const result = await kibanaFetch(path, { method: "DELETE", space });
  if (!result.success) throw new Error(result.error || `HTTP ${result.status}`);
  return result.data;
}

export async function testConnection(space) {
  try {
    const status = await kibanaGet("/api/status", undefined, space);
    const version = status?.version;
    const versionStr = typeof version === "object" ? version?.number : version;
    console.log(`Connected to Kibana: ${status?.name || "unknown"}`);
    console.log(`Version: ${versionStr || "unknown"}`);
    return true;
  } catch (error) {
    console.error(`Connection failed: ${error.message}`);
    return false;
  }
}

#!/usr/bin/env node
/**
 * Detection rule management CLI wrapping the Kibana Detection Engine REST API.
 * Supports listing, searching, creating, patching, enabling/disabling rules,
 * and managing rule exceptions for false-positive tuning.
 */

import { readFileSync } from "fs";
import { createInterface } from "readline";
import { kibanaDelete, kibanaFetch, kibanaGet, kibanaPatch, kibanaPost } from "./kibana-client.js";

const RULES_API = "/api/detection_engine/rules";
const EXCEPTIONS_API = "/api/exception_lists";

function promptConfirm(message) {
  const rl = createInterface({ input: process.stdin, output: process.stderr });
  return new Promise((resolve) => {
    rl.question(`${message} [y/N] `, (answer) => {
      rl.close();
      resolve(answer.trim().toLowerCase() === "y");
    });
  });
}

function parseArgs(argv) {
  const result = {};
  for (let i = 0; i < argv.length; i++) {
    const arg = argv[i];
    if (arg === "-y") {
      result.yes = true;
    } else if (arg.startsWith("--")) {
      const key = arg.slice(2).replace(/-/g, "_");
      const next = argv[i + 1];
      if (next !== undefined && !next.startsWith("--")) {
        const values = [];
        let j = i + 1;
        while (j < argv.length && !argv[j].startsWith("--")) {
          values.push(argv[j]);
          j++;
        }
        result[key] = values.length === 1 ? values[0] : values;
        i = j - 1;
      } else {
        result[key] = true;
      }
    }
  }
  return result;
}

function parseIntArg(val, def) {
  if (val === undefined || val === null) return def;
  const n = Number(val);
  return Number.isNaN(n) ? def : n;
}

function ensureArray(val) {
  if (val === undefined || val === null) return [];
  return Array.isArray(val) ? val : [val];
}

// ---------------------------------------------------------------------------
// Query syntax validation
// ---------------------------------------------------------------------------

const KQL_SYNTAX_CHECKS = [
  {
    pattern: /\\\//,
    id: "escaped-forward-slash",
    message: "KQL does not use backslash escaping. Use plain text (e.g. */IM chrome.exe* not *\\/IM chrome.exe*).",
  },
  {
    pattern: /(?:^|\s)AND\s+AND(?:\s|$)|(?:^|\s)OR\s+OR(?:\s|$)/,
    id: "duplicate-operator",
    message: "Duplicate boolean operator (AND AND or OR OR).",
  },
  {
    pattern: /(?:^|\s)AND\s+OR(?:\s|$)|(?:^|\s)OR\s+AND(?:\s|$)/,
    id: "conflicting-operators",
    message: "Conflicting adjacent boolean operators (AND OR or OR AND).",
  },
];

const EQL_SYNTAX_CHECKS = [
  {
    pattern: /\\\//,
    id: "escaped-forward-slash",
    message:
      "Unexpected escaped forward-slash. EQL uses double-backslash (\\\\) for literal backslashes in Windows paths.",
  },
  {
    pattern: /\bwhere\b.*\bwhere\b/i,
    id: "duplicate-where",
    message: "Duplicate 'where' clause in the same event filter.",
  },
];

const ESQL_SYNTAX_CHECKS = [
  {
    pattern: /(?:^|\s)AND\s+AND(?:\s|$)|(?:^|\s)OR\s+OR(?:\s|$)/,
    id: "duplicate-operator",
    message: "Duplicate boolean operator (AND AND or OR OR).",
  },
];

function validateQuerySyntax(query, language) {
  const errors = [];

  let checks;
  if (language === "eql") {
    checks = EQL_SYNTAX_CHECKS;
  } else if (language === "esql") {
    checks = ESQL_SYNTAX_CHECKS;
  } else {
    checks = KQL_SYNTAX_CHECKS;
  }

  for (const check of checks) {
    if (check.pattern.test(query)) {
      errors.push({ id: check.id, message: check.message });
    }
  }

  const openParens = (query.match(/\(/g) || []).length;
  const closeParens = (query.match(/\)/g) || []).length;
  if (openParens !== closeParens) {
    errors.push({
      id: "mismatched-parens",
      message: `Mismatched parentheses: ${openParens} open vs ${closeParens} close.`,
    });
  }

  const quoteCount = (query.match(/"/g) || []).length;
  if (quoteCount % 2 !== 0) {
    errors.push({ id: "unbalanced-quotes", message: `Unbalanced double-quotes: ${quoteCount} found (must be even).` });
  }

  return errors;
}

async function validateQuery(args) {
  const query = args.query;
  if (!query) {
    console.error("Error: --query is required");
    process.exit(1);
  }
  const language = args.language || "kuery";
  const errors = validateQuerySyntax(query, language);
  if (errors.length === 0) {
    console.log(JSON.stringify({ valid: true, query, language, errors: [] }, null, 2));
  } else {
    console.log(JSON.stringify({ valid: false, query, language, errors }, null, 2));
    process.exit(1);
  }
}

// ---------------------------------------------------------------------------
// Rules CRUD
// ---------------------------------------------------------------------------

async function findRules(args, space) {
  const params = {
    per_page: parseIntArg(args.per_page, 20),
    page: parseIntArg(args.page, 1),
    sort_field: args.sort_field || "name",
    sort_order: args.sort_order || "asc",
  };
  if (args.filter) params.filter = args.filter;
  if (args.fields) params.fields = args.fields;

  const result = await kibanaGet(`${RULES_API}/_find`, params, space);
  if (args.brief) {
    const rules = result.data || [];
    const brief = rules.map((r) => ({
      id: r.id,
      rule_id: r.rule_id,
      name: r.name,
      type: r.type,
      enabled: r.enabled,
      severity: r.severity,
      risk_score: r.risk_score,
      tags: r.tags || [],
      immutable: r.immutable,
    }));
    console.log(JSON.stringify({ total: result.total || 0, rules: brief }, null, 2));
  } else {
    console.log(JSON.stringify(result, null, 2));
  }
  return result;
}

async function getRule(args, space) {
  const params = {};
  if (args.id) params.id = args.id;
  else if (args.rule_id) params.rule_id = args.rule_id;
  else {
    console.error("Error: provide --id or --rule-id");
    process.exit(1);
  }

  const result = await kibanaGet(RULES_API, params, space);
  console.log(JSON.stringify(result, null, 2));
  return result;
}

async function createRule(args, space) {
  let body;
  if (args.from_file) {
    body = JSON.parse(readFileSync(args.from_file, "utf8"));
  } else {
    body = {
      name: args.name,
      description: args.description || "",
      type: args.type,
      risk_score: parseIntArg(args.risk_score, 50),
      severity: args.severity || "medium",
      enabled: !args.disabled,
    };
    if (args.query) body.query = args.query;
    if (args.language) body.language = args.language;
    else if (args.type === "query" || args.type === "saved_query") body.language = "kuery";
    else if (args.type === "eql") body.language = "eql";
    else if (args.type === "esql") body.language = "esql";
    if (args.index) body.index = ensureArray(args.index);
    if (args.interval) body.interval = args.interval;
    if (args.from_time) body.from = args.from_time;
    if (args.tags) body.tags = ensureArray(args.tags);
    if (args.threat_file) body.threat = JSON.parse(readFileSync(args.threat_file, "utf8"));
    if (args.false_positives) body.false_positives = ensureArray(args.false_positives);
    if (args.references) body.references = ensureArray(args.references);
    if (args.note) body.note = args.note;
    if (args.rule_id) body.rule_id = args.rule_id;
    if (args.max_signals !== undefined) body.max_signals = parseIntArg(args.max_signals, undefined);
    if (args.type === "threshold" && args.threshold_field) {
      body.threshold = {
        field: args.threshold_field,
        value: parseIntArg(args.threshold_value, 1),
      };
    }
  }

  if (body.query && !args.skip_validation) {
    const lang = body.language || "kuery";
    const syntaxErrors = validateQuerySyntax(body.query, lang);
    if (syntaxErrors.length > 0) {
      console.error("Query syntax validation failed:");
      for (const err of syntaxErrors) {
        console.error(`  - [${err.id}] ${err.message}`);
      }
      console.error(`\nQuery: ${body.query}`);
      console.error(`Language: ${lang}`);
      console.error("\nFix the query before creating the rule. Pass --skip-validation to bypass.");
      process.exit(1);
    }
  }

  const result = await kibanaPost(RULES_API, body, space);
  console.log(JSON.stringify(result, null, 2));
  return result;
}

async function patchRule(args, space) {
  const body = {};
  if (args.id) body.id = args.id;
  else if (args.rule_id) body.rule_id = args.rule_id;
  else {
    console.error("Error: provide --id or --rule-id");
    process.exit(1);
  }

  if (args.name) body.name = args.name;
  if (args.description) body.description = args.description;
  if (args.query) body.query = args.query;
  if (args.language) body.language = args.language;
  if (args.index) body.index = ensureArray(args.index);
  if (args.interval) body.interval = args.interval;
  if (args.from_time) body.from = args.from_time;
  if (args.tags) body.tags = ensureArray(args.tags);
  if (args.severity) body.severity = args.severity;
  if (args.risk_score !== undefined) body.risk_score = parseIntArg(args.risk_score, 50);
  if (args.false_positives) body.false_positives = ensureArray(args.false_positives);
  if (args.note) body.note = args.note;
  if (args.max_signals !== undefined) body.max_signals = parseIntArg(args.max_signals, undefined);
  if (args.enabled !== undefined) body.enabled = args.enabled === "true";

  if (body.query && !args.skip_validation) {
    const lang = body.language || args.language || "kuery";
    const syntaxErrors = validateQuerySyntax(body.query, lang);
    if (syntaxErrors.length > 0) {
      console.error("Query syntax validation failed:");
      for (const err of syntaxErrors) {
        console.error(`  - [${err.id}] ${err.message}`);
      }
      console.error(`\nQuery: ${body.query}`);
      console.error(`Language: ${lang}`);
      console.error("\nFix the query before patching the rule. Pass --skip-validation to bypass.");
      process.exit(1);
    }
  }

  const result = await kibanaPatch(RULES_API, body, space);
  console.log(JSON.stringify(result, null, 2));
  return result;
}

async function toggleRule(args, space, enable) {
  const body = { enabled: enable };
  if (args.id) body.id = args.id;
  else if (args.rule_id) body.rule_id = args.rule_id;
  else {
    console.error("Error: provide --id or --rule-id");
    process.exit(1);
  }

  const result = await kibanaPatch(RULES_API, body, space);
  const state = enable ? "enabled" : "disabled";
  console.log(`Rule ${result.name || "?"} is now ${state}`);
  return result;
}

async function deleteRule(args, space) {
  const params = {};
  if (args.id) params.id = args.id;
  else if (args.rule_id) params.rule_id = args.rule_id;
  else {
    console.error("Error: provide --id or --rule-id");
    process.exit(1);
  }

  const qs = new URLSearchParams(params).toString();
  const result = await kibanaDelete(`${RULES_API}?${qs}`, space);
  console.log(JSON.stringify(result, null, 2));
  return result;
}

async function exportRules(args, space) {
  const params = { exclude_export_details: "false" };
  if (args.file_name) params.file_name = args.file_name;

  let body = undefined;
  if (args.rule_ids) {
    const ids = Array.isArray(args.rule_ids) ? args.rule_ids : [args.rule_ids];
    body = { objects: ids.map((rid) => ({ rule_id: rid })) };
  }

  const result = await kibanaFetch(`${RULES_API}/_export`, {
    method: "POST",
    body: body ? JSON.stringify(body) : undefined,
    params,
    space,
  });

  if (!result.success) {
    throw new Error(result.error || `HTTP ${result.status}`);
  }
  console.log(result.data);
  return result.data;
}

async function bulkAction(args, space) {
  const body = { action: args.action };
  if (args.ids) body.ids = Array.isArray(args.ids) ? args.ids : [args.ids];
  else if (args.query) body.query = args.query;
  else body.query = "";

  if (args.action === "edit" && args.edit_file) {
    body.edit = JSON.parse(readFileSync(args.edit_file, "utf8"));
  }

  const path = args.dry_run ? `${RULES_API}/_bulk_action?dry_run=true` : `${RULES_API}/_bulk_action`;
  const result = await kibanaPost(path, body, space);
  console.log(JSON.stringify(result, null, 2));
  return result;
}

// ---------------------------------------------------------------------------
// Rule exceptions (false-positive tuning)
// ---------------------------------------------------------------------------

const OP_MAP = {
  is: ["match", "included"],
  is_not: ["match", "excluded"],
  is_one_of: ["match_any", "included"],
  is_not_one_of: ["match_any", "excluded"],
  exists: ["exists", "included"],
  does_not_exist: ["exists", "excluded"],
  matches: ["wildcard", "included"],
  does_not_match: ["wildcard", "excluded"],
};

function parseExceptionEntry(entryStr) {
  const parts = entryStr.split(":");
  let field, operator, value;
  if (parts.length >= 3) {
    field = parts[0];
    operator = parts[1];
    value = parts.slice(2).join(":");
  } else if (parts.length === 2) {
    field = parts[0];
    value = parts[1];
    operator = "is";
  } else {
    throw new Error(`Invalid entry format '${entryStr}'. Use field:operator:value or field:value`);
  }

  const mapped = OP_MAP[operator];
  if (!mapped) {
    throw new Error(`Unknown operator '${operator}'. Use: ${Object.keys(OP_MAP).join(", ")}`);
  }

  const [entryType, listOperator] = mapped;
  const entry = { field, type: entryType, operator: listOperator };
  if (entryType === "match") entry.value = value;
  else if (entryType === "match_any") entry.value = value.split(",").map((v) => v.trim());
  else if (entryType === "wildcard") entry.value = value;
  return entry;
}

async function addException(args, space) {
  const entries = [];
  const entryStrs = Array.isArray(args.entries) ? args.entries : [args.entries];
  for (const entryStr of entryStrs) {
    entries.push(parseExceptionEntry(entryStr));
  }

  const item = {
    type: "simple",
    name: args.name || `Exception ${crypto.randomUUID().slice(0, 8)}`,
    description: args.description || "",
    entries,
  };
  if (args.tags) item.tags = ensureArray(args.tags);
  if (args.expire) item.expire_time = args.expire;
  if (args.comment) item.comments = [{ comment: args.comment }];

  const body = { items: [item] };
  const result = await kibanaPost(`${RULES_API}/${args.rule_uuid}/exceptions`, body, space);
  console.log(JSON.stringify(result, null, 2));
  return result;
}

async function listExceptions(args, space) {
  const params = {
    list_id: args.list_id,
    namespace_type: args.namespace_type || "single",
    per_page: parseIntArg(args.per_page, 20),
    page: parseIntArg(args.page, 1),
  };
  const result = await kibanaGet(`${EXCEPTIONS_API}/items/_find`, params, space);
  console.log(JSON.stringify(result, null, 2));
  return result;
}

async function createSharedExceptionList(args, space) {
  const body = {
    name: args.name,
    description: args.description || "",
  };
  if (args.tags) body.tags = ensureArray(args.tags);

  const result = await kibanaPost("/api/exceptions/shared", body, space);
  console.log(JSON.stringify(result, null, 2));
  return result;
}

// ---------------------------------------------------------------------------
// Alert volume analysis (for tuning decisions)
// ---------------------------------------------------------------------------

async function noisyRules(args) {
  const { createClient } = await import("./es-client.js");
  const es = createClient();

  const days = parseIntArg(args.days, 7);
  const size = parseIntArg(args.top, 20);

  const query = {
    bool: {
      must: [{ range: { "@timestamp": { gte: `now-${days}d` } } }],
    },
  };
  const aggs = {
    by_rule: {
      terms: {
        field: "kibana.alert.rule.name",
        size,
        order: { _count: "desc" },
      },
      aggs: {
        rule_id: { terms: { field: "kibana.alert.rule.uuid", size: 1 } },
        severity: { terms: { field: "kibana.alert.severity", size: 1 } },
        unique_agents: { cardinality: { field: "agent.id" } },
      },
    },
  };

  const result = await es.search({
    index: ".alerts-security.alerts-*",
    query,
    aggs,
    size: 0,
  });

  const buckets = result.aggregations?.by_rule?.buckets || [];
  const output = buckets.map((b) => {
    const ruleIds = b.rule_id?.buckets || [];
    const sevs = b.severity?.buckets || [];
    return {
      rule_name: b.key,
      alert_count: b.doc_count,
      rule_uuid: ruleIds[0]?.key ?? null,
      severity: sevs[0]?.key ?? null,
      unique_agents: b.unique_agents?.value ?? 0,
    };
  });

  console.log(JSON.stringify(output, null, 2));
  return output;
}

// ---------------------------------------------------------------------------
// CLI
// ---------------------------------------------------------------------------

async function main() {
  const cmd = process.argv[2];
  const rawArgs = parseArgs(process.argv.slice(3));
  const space = rawArgs.space;
  const yes = rawArgs.yes === true;

  const requireArg = (name, msg) => {
    const val = rawArgs[name];
    if (val === undefined || val === null || val === "") {
      console.error(`Error: ${msg}`);
      process.exit(1);
    }
    return val;
  };

  try {
    switch (cmd) {
      case "find":
        await findRules(rawArgs, space);
        break;
      case "get":
        if (!rawArgs.id && !rawArgs.rule_id) {
          console.error("Error: provide --id or --rule-id");
          process.exit(1);
        }
        await getRule(rawArgs, space);
        break;
      case "create":
        if (!yes) {
          const label = rawArgs.name || rawArgs.from_file || "new rule";
          const ok = await promptConfirm(`Create rule "${label}"?`);
          if (!ok) {
            console.log("Aborted.");
            process.exit(0);
          }
        }
        await createRule(rawArgs, space);
        break;
      case "patch":
        if (!rawArgs.id && !rawArgs.rule_id) {
          console.error("Error: provide --id or --rule-id");
          process.exit(1);
        }
        if (!yes) {
          const ok = await promptConfirm(`Patch rule ${rawArgs.id || rawArgs.rule_id}?`);
          if (!ok) {
            console.log("Aborted.");
            process.exit(0);
          }
        }
        await patchRule(rawArgs, space);
        break;
      case "enable":
        if (!rawArgs.id && !rawArgs.rule_id) {
          console.error("Error: provide --id or --rule-id");
          process.exit(1);
        }
        if (!yes) {
          const ok = await promptConfirm(`Enable rule ${rawArgs.id || rawArgs.rule_id}?`);
          if (!ok) {
            console.log("Aborted.");
            process.exit(0);
          }
        }
        await toggleRule(rawArgs, space, true);
        break;
      case "disable":
        if (!rawArgs.id && !rawArgs.rule_id) {
          console.error("Error: provide --id or --rule-id");
          process.exit(1);
        }
        if (!yes) {
          const ok = await promptConfirm(`Disable rule ${rawArgs.id || rawArgs.rule_id}?`);
          if (!ok) {
            console.log("Aborted.");
            process.exit(0);
          }
        }
        await toggleRule(rawArgs, space, false);
        break;
      case "delete":
        if (!rawArgs.id && !rawArgs.rule_id) {
          console.error("Error: provide --id or --rule-id");
          process.exit(1);
        }
        if (!yes) {
          const ok = await promptConfirm(`Delete rule ${rawArgs.id || rawArgs.rule_id}? This cannot be undone.`);
          if (!ok) {
            console.log("Aborted.");
            process.exit(0);
          }
        }
        await deleteRule(rawArgs, space);
        break;
      case "export":
        await exportRules(rawArgs, space);
        break;
      case "bulk-action":
        requireArg("action", "--action is required");
        if (!yes && !rawArgs.dry_run) {
          const ok = await promptConfirm(`Execute bulk ${rawArgs.action}?`);
          if (!ok) {
            console.log("Aborted.");
            process.exit(0);
          }
        }
        await bulkAction(rawArgs, space);
        break;
      case "add-exception":
        requireArg("rule_uuid", "--rule-uuid is required");
        requireArg("entries", "--entries is required");
        if (!yes) {
          const ok = await promptConfirm(`Add exception to rule ${rawArgs.rule_uuid}?`);
          if (!ok) {
            console.log("Aborted.");
            process.exit(0);
          }
        }
        await addException(rawArgs, space);
        break;
      case "list-exceptions":
        requireArg("list_id", "--list-id is required");
        await listExceptions(rawArgs, space);
        break;
      case "create-shared-list":
        requireArg("name", "--name is required");
        if (!yes) {
          const ok = await promptConfirm(`Create shared exception list "${rawArgs.name}"?`);
          if (!ok) {
            console.log("Aborted.");
            process.exit(0);
          }
        }
        await createSharedExceptionList(rawArgs, space);
        break;
      case "noisy-rules":
        await noisyRules(rawArgs);
        break;
      case "validate-query":
        await validateQuery(rawArgs);
        break;
      default:
        console.error(
          "Error: unknown command. Use: find, get, create, patch, enable, disable, delete, export, bulk-action, add-exception, list-exceptions, create-shared-list, noisy-rules, validate-query",
        );
        process.exit(1);
    }
  } catch (err) {
    console.error(`Error: ${err.message}`);
    process.exit(1);
  }
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
  process.exit(1);
});