@ebowwa/mcp-nm 2.0.3 → 2.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ebowwa/mcp-nm",
-  "version": "2.0.3",
-  "description": "Comprehensive binary analysis MCP server - symbols (nm), hex dumps (xxd), strings, disassembly, security audit, entropy analysis, ELF/Mach-O inspection, binary patching, and macOS code signing tools",
+  "version": "2.2.0",
+  "description": "Comprehensive binary analysis MCP server - symbols (nm), hex dumps (xxd), strings, disassembly, security audit, entropy analysis, ELF/Mach-O inspection, binary patching, macOS code signing, and persistent patch management",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,7 +36,9 @@
     "otool",
     "codesign",
     "quarantine",
-    "macos"
+    "macos",
+    "patch-management",
+    "binary-persistence"
   ],
   "author": "ebowwa",
   "license": "MIT",

package/src/handlers/bin.ts

@@ -0,0 +1,558 @@
+/**
+ * @ebowwa/mcp-nm - Binary analysis handlers
+ *
+ * MCP tool handlers for extended binary analysis
+ */
+
+import { runCommand, LARGE_BUFFER, execAsync, isMacOS, isLinux } from "../utils/exec";
+import { analyzeFile, getMimeType, getFileInfo } from "../utils/file";
+import { runNm } from "../utils/nm";
+import { hexToBytes, formatBytesWithContext } from "../utils/xxd";
+import type { McpResponse } from "../types";
+
+/**
+ * Extract strings from binary
+ */
+export async function handleStrings(args: {
+  filePath: string;
+  minLength?: number;
+  encoding?: "ascii" | "unicode" | "all";
+}): Promise<McpResponse> {
+  const minLen = args.minLength ?? 4;
+  const encFlags: Record<string, string> = {
+    ascii: "-a",
+    unicode: "-e l",
+    all: "-a -e l",
+  };
+  const encFlag = encFlags[args.encoding ?? "all"];
+
+  const { stdout } = await runCommand(
+    `strings ${encFlag} -n ${minLen} "${args.filePath}"`,
+    { maxBuffer: LARGE_BUFFER }
+  );
+
+  const strings = stdout.trim().split("\n").filter(Boolean);
+
+  const summary = [
+    `Strings in: ${args.filePath}`,
+    `Encoding: ${args.encoding ?? "all"}`,
+    `Minimum length: ${minLen}`,
+    `Total strings: ${strings.length}`,
+    "",
+    "Strings:",
+    ...strings.slice(0, 200).map((s) => `  ${s}`),
+    strings.length > 200 ? `  ... and ${strings.length - 200} more` : "",
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+/**
+ * Get file type with MIME
+ */
+export async function handleFileInfo(args: { filePath: string }): Promise<McpResponse> {
+  const [mimeInfo, detailedInfo] = await Promise.all([
+    getMimeType(args.filePath),
+    getFileInfo(args.filePath),
+  ]);
+
+  const summary = [
+    `File: ${args.filePath}`,
+    "",
+    "MIME Type:",
+    `  ${mimeInfo}`,
+    "",
+    "Detailed Type:",
+    `  ${detailedInfo}`,
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+/**
+ * Get section sizes
+ */
+export async function handleSectionSizes(args: { filePath: string }): Promise<McpResponse> {
+  try {
+    const { stdout } = await runCommand(`size -A -x "${args.filePath}"`);
+    return { content: [{ type: "text", text: `Section Sizes:\n${stdout}` }] };
+  } catch {
+    try {
+      const { stdout } = await runCommand(`size -m "${args.filePath}"`);
+      return { content: [{ type: "text", text: `Section Sizes:\n${stdout}` }] };
+    } catch (error) {
+      throw new Error(`size command failed: ${error instanceof Error ? error.message : error}`);
+    }
+  }
+}
+
+/**
+ * Get section headers via objdump
+ */
+export async function handleObjdumpSections(args: { filePath: string }): Promise<McpResponse> {
+  const { stdout } = await runCommand(`objdump -h "${args.filePath}"`, {
+    maxBuffer: LARGE_BUFFER,
+  });
+
+  return { content: [{ type: "text", text: `Section Headers: ${args.filePath}\n\n${stdout}` }] };
+}
+
+/**
+ * Get program headers / DLL imports via objdump
+ */
+export async function handleObjdumpProgramHeaders(args: { filePath: string }): Promise<McpResponse> {
+  const { stdout } = await runCommand(`objdump -p "${args.filePath}"`, {
+    maxBuffer: LARGE_BUFFER,
+  });
+
+  return { content: [{ type: "text", text: `Program Headers / Imports: ${args.filePath}\n\n${stdout}` }] };
+}
+
+/**
+ * Get Mach-O dynamic libraries via otool (macOS only)
+ */
+export async function handleOtoolLibs(args: { filePath: string }): Promise<McpResponse> {
+  if (!isMacOS()) {
+    throw new Error("otool -L is only available on macOS");
+  }
+
+  const { stdout } = await runCommand(`otool -L "${args.filePath}"`);
+  const lines = stdout.trim().split("\n");
+
+  const summary = [
+    `Dynamic Library Dependencies: ${args.filePath}`,
+    "",
+    ...lines.map((l) => `  ${l}`),
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+/**
+ * Comprehensive ELF analysis via readelf (Linux only)
+ */
+export async function handleReadelf(args: {
+  filePath: string;
+  sections?: ("headers" | "sections" | "segments" | "symbols" | "dynamic" | "all")[];
+}): Promise<McpResponse> {
+  if (!isLinux()) {
+    throw new Error("readelf is only available on Linux");
+  }
+
+  const sections = args.sections ?? ["all"];
+  const flags: string[] = [];
+
+  if (sections.includes("all")) {
+    flags.push("-a");
+  } else {
+    if (sections.includes("headers")) flags.push("-h");
+    if (sections.includes("sections")) flags.push("-S");
+    if (sections.includes("segments")) flags.push("-l");
+    if (sections.includes("symbols")) flags.push("-s");
+    if (sections.includes("dynamic")) flags.push("-d");
+  }
+
+  const { stdout } = await runCommand(`readelf ${flags.join(" ")} "${args.filePath}"`, {
+    maxBuffer: 20 * 1024 * 1024,
+  });
+
+  const summary = [
+    `ELF Analysis: ${args.filePath}`,
+    `Sections: ${sections.join(", ")}`,
+    "",
+    stdout.slice(0, 50000),
+    stdout.length > 50000 ? `\n... truncated (${stdout.length - 50000} more chars)` : "",
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+/**
+ * Get shared library dependencies via ldd (Linux only)
+ */
+export async function handleLdd(args: { filePath: string }): Promise<McpResponse> {
+  if (!isLinux()) {
+    throw new Error("ldd is only available on Linux");
+  }
+
+  const { stdout } = await runCommand(`ldd "${args.filePath}"`);
+  const lines = stdout.trim().split("\n").filter(Boolean);
+
+  const summary = [
+    `Shared Library Dependencies: ${args.filePath}`,
+    "",
+    ...lines.map((l) => `  ${l}`),
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+/**
+ * Disassemble via objdump -d
+ */
+export async function handleDisassembly(args: {
+  filePath: string;
+  symbol?: string;
+  startOffset?: number;
+  length?: number;
+}): Promise<McpResponse> {
+  let cmd = "objdump -d";
+
+  if (args.symbol) {
+    cmd += ` --disassemble="${args.symbol}"`;
+  }
+
+  cmd += ` "${args.filePath}"`;
+
+  const { stdout } = await runCommand(cmd, { maxBuffer: LARGE_BUFFER });
+
+  let output = stdout;
+  if (args.startOffset !== undefined || args.length !== undefined) {
+    const lines = stdout.split("\n");
+    const start = args.startOffset ?? 0;
+    const len = args.length ?? 500;
+    output = lines.slice(start, start + len).join("\n");
+  }
+
+  const summary = [
+    `Disassembly: ${args.filePath}`,
+    args.symbol ? `Symbol: ${args.symbol}` : "",
+    "",
+    output.slice(0, 100000),
+    output.length > 100000 ? `\n... truncated (${output.length - 100000} more chars)` : "",
+  ].filter(Boolean).join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+/**
+ * Security audit (ASLR, PIE, RELRO, stack canary, NX)
+ */
+export async function handleSecurityAudit(args: { filePath: string }): Promise<McpResponse> {
+  const results: { check: string; status: string; details: string }[] = [];
+
+  try {
+    const { stdout: fileInfo } = await runCommand(`file "${args.filePath}"`);
+    const info = fileInfo.toLowerCase();
+
+    // PIE
+    if (info.includes("pie") || info.includes("position independent")) {
+      results.push({ check: "PIE", status: "ENABLED", details: "Position Independent Executable" });
+    } else if (info.includes("executable")) {
+      results.push({ check: "PIE", status: "DISABLED", details: "Not a PIE binary" });
+    }
+
+    // RELRO (Linux)
+    if (isLinux()) {
+      try {
+        const { stdout: relro } = await runCommand(
+          `readelf -l "${args.filePath}" 2>/dev/null | grep -i gnu_relro`
+        );
+        if (relro.trim()) {
+          results.push({ check: "RELRO", status: "ENABLED", details: "Read-Only relocations" });
+        }
+      } catch {
+        // Not applicable
+      }
+    }
+
+    // Stack canary
+    try {
+      const { stdout: canary } = await runCommand(
+        `nm "${args.filePath}" 2>/dev/null | grep -i "__stack_chk_fail"`
+      );
+      if (canary.trim()) {
+        results.push({ check: "Stack Canary", status: "ENABLED", details: "Stack smashing detected symbol found" });
+      } else {
+        results.push({ check: "Stack Canary", status: "UNKNOWN", details: "No stack canary symbol found" });
+      }
+    } catch {
+      results.push({ check: "Stack Canary", status: "UNKNOWN", details: "Could not check" });
+    }
+
+    // NX bit
+    if (isLinux()) {
+      try {
+        const { stdout: nx } = await runCommand(
+          `readelf -l "${args.filePath}" 2>/dev/null | grep -i "gnu_stack"`
+        );
+        if (nx.toLowerCase().includes("rwe")) {
+          results.push({ check: "NX", status: "DISABLED", details: "Stack is executable (RWE)" });
+        } else if (nx.trim()) {
+          results.push({ check: "NX", status: "ENABLED", details: "Non-executable stack" });
+        }
+      } catch {
+        // Not Linux
+      }
+    }
+
+    // FORTIFY_SOURCE
+    try {
+      const { stdout: fortify } = await runCommand(
+        `nm "${args.filePath}" 2>/dev/null | grep -i "_chk@"`
+      );
+      if (fortify.trim()) {
+        results.push({ check: "FORTIFY", status: "ENABLED", details: "Fortified functions detected" });
+      }
+    } catch {
+      // Not applicable
+    }
+
+    // macOS specific
+    if (info.includes("mach-o")) {
+      try {
+        const { stdout: loadCmds } = await runCommand(`otool -l "${args.filePath}"`);
+        if (loadCmds.toLowerCase().includes("lc_main")) {
+          results.push({ check: "PIE", status: "ENABLED", details: "Mach-O with LC_MAIN (likely PIE)" });
+        }
+      } catch {
+        // Ignore
+      }
+    }
+  } catch (error) {
+    results.push({ check: "Error", status: "FAILED", details: error instanceof Error ? error.message : String(error) });
+  }
+
+  const summary = [
+    `Security Audit: ${args.filePath}`,
+    "",
+    "Security Features:",
+    ...results.map((r) => `  ${r.check}: ${r.status} - ${r.details}`),
+    "",
+    "Recommendations:",
+    ...results
+      .filter((r) => r.status === "DISABLED" || r.status === "UNKNOWN")
+      .map((r) => `  - Consider enabling ${r.check}`),
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+/**
+ * Entropy analysis (detect packed/encrypted sections)
+ */
+export async function handleEntropyAnalysis(args: {
+  filePath: string;
+  blockSize?: number;
+}): Promise<McpResponse> {
+  const blockSize = args.blockSize ?? 1024;
+
+  const { stdout: hexData } = await runCommand(`xxd -p "${args.filePath}" | tr -d '\\n'`);
+  const bytes = hexData.match(/.{2}/g)?.map((h) => parseInt(h, 16)) ?? [];
+
+  const results: { section: string; offset: number; entropy: number; status: string }[] = [];
+
+  for (let i = 0; i < bytes.length; i += blockSize) {
+    const block = bytes.slice(i, i + blockSize);
+    if (block.length === 0) continue;
+
+    // Calculate Shannon entropy
+    const freq: Record<number, number> = {};
+    for (const byte of block) {
+      freq[byte] = (freq[byte] ?? 0) + 1;
+    }
+
+    let entropy = 0;
+    for (const count of Object.values(freq)) {
+      const p = count / block.length;
+      entropy -= p * Math.log2(p);
+    }
+
+    const normalizedEntropy = entropy / 8;
+    let status = "normal";
+    if (normalizedEntropy > 0.95) status = "high (possibly encrypted/compressed)";
+    else if (normalizedEntropy < 0.3) status = "low (possibly padding/zeros)";
+
+    results.push({
+      section: `Block ${Math.floor(i / blockSize)}`,
+      offset: i,
+      entropy: Math.round(entropy * 100) / 100,
+      status,
+    });
+  }
+
+  const avgEntropy = results.reduce((a, b) => a + b.entropy, 0) / results.length;
+
+  const summary = [
+    `Entropy Analysis: ${args.filePath}`,
+    `Block size: ${blockSize} bytes`,
+    `Total blocks: ${results.length}`,
+    `Average entropy: ${((avgEntropy / 8) * 100).toFixed(1)}% of max`,
+    "",
+    "Blocks with unusual entropy:",
+    ...results
+      .filter((r) => r.status !== "normal")
+      .slice(0, 50)
+      .map((r) => `  ${r.section} (offset ${r.offset}): ${r.entropy}/8 bits - ${r.status}`),
+    results.filter((r) => r.status !== "normal").length > 50
+      ? `  ... and ${results.filter((r) => r.status !== "normal").length - 50} more`
+      : "",
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+/**
+ * Import/export table analysis
+ */
+export async function handleImportExport(args: { filePath: string }): Promise<McpResponse> {
+  const analysis = await analyzeFile(args.filePath);
+  const imports: string[] = [];
+  const exports: string[] = [];
+
+  try {
+    if (analysis.format.toLowerCase().includes("mach-o")) {
+      // macOS
+      const { stdout: importSyms } = await runCommand(
+        `nm -u "${args.filePath}" 2>/dev/null | awk '{print $2}'`
+      );
+      imports.push(...importSyms.trim().split("\n").filter(Boolean));
+
+      const { stdout: exportSyms } = await runCommand(
+        `nm -g "${args.filePath}" 2>/dev/null | grep -v "U " | awk '{print $3}'`
+      );
+      exports.push(...exportSyms.trim().split("\n").filter(Boolean));
+    } else {
+      // Linux ELF
+      const { stdout: importSyms } = await runCommand(
+        `nm -D -u "${args.filePath}" 2>/dev/null | awk '{print $2}'`
+      );
+      imports.push(...importSyms.trim().split("\n").filter(Boolean));
+
+      const { stdout: exportSyms } = await runCommand(
+        `nm -D --defined-only "${args.filePath}" 2>/dev/null | awk '{print $3}'`
+      );
+      exports.push(...exportSyms.trim().split("\n").filter(Boolean));
+    }
+  } catch {
+    // Fallback to regular nm
+    try {
+      const { stdout: allSyms } = await runCommand(`nm "${args.filePath}" 2>/dev/null`);
+      for (const line of allSyms.split("\n")) {
+        const match = line.match(/^\s*([0-9a-fA-F]+)?\s+([UTDDBRC])\s+(.+)/);
+        if (match) {
+          if (match[2] === "U") imports.push(match[3]);
+          else if (match[1] && match[2] === match[2].toUpperCase()) exports.push(match[3]);
+        }
+      }
+    } catch {
+      // Ignore
+    }
+  }
+
+  const summary = [
+    `Import/Export Analysis: ${args.filePath}`,
+    `File type: ${analysis.format}`,
+    "",
+    `Imports (${imports.length}):`,
+    ...imports.slice(0, 100).map((s) => `  - ${s}`),
+    imports.length > 100 ? `  ... and ${imports.length - 100} more` : "",
+    "",
+    `Exports (${exports.length}):`,
+    ...exports.slice(0, 100).map((s) => `  + ${s}`),
+    exports.length > 100 ? `  ... and ${exports.length - 100} more` : "",
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+/**
+ * Binary diff (byte-level comparison)
+ */
+export async function handleBinaryDiff(args: {
+  file1: string;
+  file2: string;
+  contextBytes?: number;
+}): Promise<McpResponse> {
+  const contextBytes = args.contextBytes ?? 32;
+
+  const [{ stdout: hex1 }, { stdout: hex2 }] = await Promise.all([
+    runCommand(`xxd -p "${args.file1}" | tr -d '\\n'`),
+    runCommand(`xxd -p "${args.file2}" | tr -d '\\n'`),
+  ]);
+
+  const bytes1 = hex1.match(/.{2}/g) ?? [];
+  const bytes2 = hex2.match(/.{2}/g) ?? [];
+
+  const maxLen = Math.max(bytes1.length, bytes2.length);
+  const diffs: { offset: number; file1: string; file2: string }[] = [];
+
+  for (let i = 0; i < maxLen; i++) {
+    const b1 = bytes1[i] ?? "??";
+    const b2 = bytes2[i] ?? "??";
+    if (b1 !== b2) {
+      diffs.push({ offset: i, file1: b1, file2: b2 });
+    }
+  }
+
+  const diffPercent = ((diffs.length / maxLen) * 100).toFixed(2);
+
+  const summary = [
+    `Binary Diff: ${args.file1} vs ${args.file2}`,
+    "",
+    `File 1 size: ${bytes1.length} bytes`,
+    `File 2 size: ${bytes2.length} bytes`,
+    `Differences: ${diffs.length} bytes (${diffPercent}%)`,
+    "",
+    "Differences (first 200):",
+    ...diffs.slice(0, 200).map((d) => {
+      const ctx1 = formatBytesWithContext(bytes1, d.offset, 4);
+      const ctx2 = formatBytesWithContext(bytes2, d.offset, 4);
+      return `  Offset 0x${d.offset.toString(16).padStart(8, "0")}: ${d.file1} -> ${d.file2}\n    Context: [${ctx1}] -> [${ctx2}]`;
+    }),
+    diffs.length > 200 ? `  ... and ${diffs.length - 200} more differences` : "",
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+/**
+ * Archive extraction (.a files)
+ */
+export async function handleArchiveExtract(args: {
+  filePath: string;
+  outputDir?: string;
+  listOnly?: boolean;
+}): Promise<McpResponse> {
+  const outputDir = args.outputDir ?? `/tmp/archive_${Date.now()}`;
+
+  const { stdout: fileInfo } = await runCommand(`file "${args.filePath}"`);
+  if (!fileInfo.toLowerCase().includes("ar archive") && !fileInfo.toLowerCase().includes("archive")) {
+    return {
+      content: [{ type: "text", text: `Error: ${args.filePath} is not an archive file.\n${fileInfo}` }],
+      isError: true,
+    };
+  }
+
+  const { stdout: contents } = await runCommand(`ar -t "${args.filePath}"`);
+  const files = contents.trim().split("\n").filter(Boolean);
+
+  if (args.listOnly) {
+    return {
+      content: [{
+        type: "text",
+        text: [
+          `Archive Contents: ${args.filePath}`,
+          `Total files: ${files.length}`,
+          "",
+          "Files:",
+          ...files.map((f) => `  - ${f}`),
+        ].join("\n"),
+      }],
+    };
+  }
+
+  await execAsync(`mkdir -p "${outputDir}"`);
+  await execAsync(`cd "${outputDir}" && ar -x "${args.filePath}"`);
+
+  const summary = [
+    `Archive Extracted: ${args.filePath}`,
+    `Output directory: ${outputDir}`,
+    `Files extracted: ${files.length}`,
+    "",
+    "Extracted files:",
+    ...files.map((f) => `  - ${f}`),
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}

package/src/handlers/index.ts

@@ -0,0 +1,72 @@
+/**
+ * @ebowwa/mcp-nm - Handlers index
+ *
+ * Export all MCP tool handlers organized by domain
+ */
+
+// Symbol analysis (nm)
+export {
+  handleListSymbols,
+  handleExternalSymbols,
+  handleUndefinedSymbols,
+  handleDefinedSymbols,
+  handleDynamicSymbols,
+  handleSearchSymbols,
+  handleCompareBinaries,
+  handleSymbolInfo,
+  handleSummary,
+} from "./nm";
+
+// Hex operations (xxd)
+export {
+  handleXxdHexdump,
+  handleXxdPlain,
+  handleXxdCInclude,
+  handleXxdBinary,
+  handleXxdReverse,
+  handleXxdExtract,
+  handleXxdFindPattern,
+} from "./xxd";
+
+// Binary analysis
+export {
+  handleStrings,
+  handleFileInfo,
+  handleSectionSizes,
+  handleObjdumpSections,
+  handleObjdumpProgramHeaders,
+  handleOtoolLibs,
+  handleReadelf,
+  handleLdd,
+  handleDisassembly,
+  handleSecurityAudit,
+  handleEntropyAnalysis,
+  handleImportExport,
+  handleBinaryDiff,
+  handleArchiveExtract,
+} from "./bin";
+
+// Binary patching
+export {
+  handlePatchBytes,
+  handleNopSled,
+  handleHexEditor,
+  handleConvertNumber,
+  handlePatchRegister,
+  handlePatchList,
+  handlePatchApply,
+  handlePatchRestore,
+  handlePatchVerify,
+  handlePatchRemove,
+} from "./patch";
+
+// macOS-specific
+export {
+  handleCodesignInfo,
+  handleCodesignRemove,
+  handleCodesignSign,
+  handleQuarantineCheck,
+  handleQuarantineRemove,
+  handleSafePatch,
+  handleBinVerify,
+} from "./macos";