REMnux MCP Server

Instructions

Implementation Reference

• src/handlers/suggest-tools.ts:229-367 (handler)

  Main handler function handleSuggestTools that implements the suggest_tools tool. It validates file paths, detects file type using the 'file' command, matches to a category, retrieves recommended tools from the registry, checks tool availability, queries the catalog for additional tools, and returns a formatted response with tool recommendations and expert analysis hints.

  export async function handleSuggestTools(
    deps: HandlerDeps,
    args: SuggestToolsArgs,
  ) {
    const startTime = Date.now();
    try {
    const { connector, config } = deps;
    const depth = (args.depth ?? "standard") as DepthTier;
  
    // Validate file path (skip unless --sandbox)
    if (!config.noSandbox) {
      const validation = validateFilePath(args.file, config.samplesDir);
      if (!validation.safe) {
        return formatError("suggest_tools", new REMnuxError(
          validation.error || "Invalid file path",
          "INVALID_PATH",
          "validation",
          "Use a relative path within the samples directory",
        ), startTime);
      }
    }
  
    const filePath = (config.mode === "local" && args.file.startsWith("/")) ? args.file : `${config.samplesDir}/${args.file}`;
  
    // Detect file type
    let fileOutput: string;
    try {
      const result = await connector.execute(["file", filePath], { timeout: 30000 });
      fileOutput = result.stdout?.trim() || "";
      if (!fileOutput) {
        return formatError("suggest_tools", new REMnuxError(
          "Could not determine file type (empty `file` output)",
          "EMPTY_OUTPUT",
          "tool_failure",
          "Check that the file exists and is readable",
        ), startTime);
      }
    } catch (error) {
      const msg = `Error running file command: ${error instanceof Error ? error.message : "Unknown error"}`;
      return formatError("suggest_tools", new REMnuxError(
        msg,
        "EMPTY_OUTPUT",
        "tool_failure",
        "Check that the file exists and is readable",
      ), startTime);
    }
  
    // Match category and get tools from registry
    const category = matchFileType(fileOutput, args.file);
  
    const primaryTag = CATEGORY_TAG_MAP[category.name] ?? "fallback";
    const tools = toolRegistry.byTagAndTier(primaryTag, depth);
  
    // Check tool availability (batch all unique commands in one shell call)
    const uniqueCommands = [...new Set(tools.map((t) => t.command))];
    const availableCommands = new Set<string>();
    if (uniqueCommands.length > 0) {
      try {
        // Single shell call: check all commands at once
        const checks = uniqueCommands.map((c) => `which ${c} >/dev/null 2>&1 && echo "${c}"`).join("; ");
        const check = await connector.executeShell(checks, {
          timeout: 10000,
          cwd: config.samplesDir,
        });
        for (const line of (check.stdout || "").split("\n")) {
          const cmd = line.trim();
          if (cmd) availableCommands.add(cmd);
        }
      } catch {
        // On failure, assume all available (graceful degradation)
        for (const c of uniqueCommands) availableCommands.add(c);
      }
    }
  
    const recommended = tools.map((t) => ({
      name: t.name,
      description: t.description,
      tier: t.tier,
      tags: t.tags ?? [],
      ...(availableCommands.has(t.command) ? {} : { available: false as const }),
    }));
  
    // Query catalog for additional tools not in the registry
    let additionalTools: Array<{ command: string; name: string; description: string; website: string }> = [];
    try {
      const normalize = (c: string) => c.replace(/\.py$/, '');
      const registryCommands = new Set(tools.map((t) => normalize(t.command)));
  
      // Check if a catalog tool is already covered by the registry
      const isCovered = (catalogCmd: string): boolean => {
        // Direct match (with .py normalization)
        if (registryCommands.has(normalize(catalogCmd))) return true;
        // Alias match (catalog package name → registry CLI commands)
        // Alias match: catalog package name → registry CLI commands.
        // Uses some() deliberately: if ANY tool from the package is recommended,
        // the catalog package entry is hidden to avoid confusing overlap.
        const aliases = CATALOG_ALIASES[catalogCmd];
        return aliases !== undefined && aliases.some((a) => registryCommands.has(normalize(a)));
      };
  
      const seen = new Set<string>();
      additionalTools = toolCatalog.forMcpCategory(category.name)
        .filter((ct) => !isCovered(ct.command))
        .filter((ct) => {
          if (seen.has(ct.command)) return false;
          seen.add(ct.command);
          return true;
        })
        .map((ct) => ({
          command: ct.command,
          name: ct.name,
          description: ct.description,
          website: ct.website,
        }));
    } catch (err) {
      console.error("WARNING: Catalog query failed for additional_tools:", err);
    }
  
    return formatResponse("suggest_tools", {
      file: args.file,
      detected_type: fileOutput,
      matched_category: category.name,
      depth,
      recommended_tools: recommended,
      ...(recommended.length === 0 && {
        warning: `No tools registered for category "${category.name}" at depth "${depth}". Try depth "deep" or use run_tool directly.`,
      }),
      analysis_hints: generateHints(category.name, fileOutput),
      ...(additionalTools.length > 0 && {
        additional_tools: additionalTools,
        additional_tools_note:
          "Additional tools available on REMnux for this file type. " +
          "Not auto-run by analyze_file. Use run_tool to invoke manually.",
      }),
    }, startTime);
    } catch (error) {
      return formatError("suggest_tools", toREMnuxError(error, deps.config.mode), startTime);
    }
  }

• src/schemas/tools.ts:56-62 (schema)

  Schema definition for suggest_tools input validation. Defines 'file' (required) and 'depth' (optional, defaults to 'standard') parameters using zod validation.

  export const suggestToolsSchema = z.object({
    file: z.string().describe("Filename relative to samples directory, or absolute path in local mode"),
    depth: z.enum(["quick", "standard", "deep"]).optional().default("standard").describe(
      "Filter recommendations by depth tier: 'quick' (triage only), 'standard' (default), 'deep' (all tools)"
    ),
  });
  export type SuggestToolsArgs = z.input<typeof suggestToolsSchema>;

• src/index.ts:187-195 (registration)

  MCP tool registration for suggest_tools. Registers the tool with its name, description, schema, and handler function using server.tool().

  // Tool: suggest_tools - Get tool recommendations for a file
  server.tool(
    "suggest_tools",
    "Detect file type and return recommended REMnux analysis tools without executing them. " +
    "Use this to plan an analysis strategy, then run individual tools with run_tool. " +
    "Returns tool names, descriptions, depth tiers, and expert analysis hints.",
    suggestToolsSchema.shape,
    (args) => handleSuggestTools(deps, args)
  );

• src/handlers/suggest-tools.ts:189-227 (helper)

  Helper function generateHints that creates dynamic analysis guidance by combining base hints with property-specific observations (packer detection, .NET detection, compiler detection) extracted from file command output.

  /** Generate dynamic hints by augmenting base hints with property-specific guidance. */
  function generateHints(category: string, fileOutput: string): string {
    const base = BASE_HINTS[category] ?? BASE_HINTS.Unknown;
    const props = extractFileProperties(fileOutput);
    const extras: string[] = [];
  
    if (props.packed) {
      extras.push(
        `Packer detected: ${props.packed}. ` +
        "capa and floss results may be limited on packed samples. " +
        (props.packed === "UPX"
          ? "UPX can be unpacked with the upx-decompress tool — recommend unpacking then re-analyzing."
          : "No standard unpacker available; static code analysis will be limited. " +
            "Focus on: certificate/signature artifacts (disitool.py for structure, pestr for embedded text including Unicode), " +
            "metadata masquerading (exiftool, peframe), and string patterns for C2/IOCs."),
      );
    }
  
    if (props.isDotNet) {
      extras.push("Detected .NET assembly — ilspycmd decompilation recommended for source-level analysis. monodis --presources lists embedded resources (payloads, config data).");
    }
  
    if (props.isDll) {
      extras.push("DLL detected — check exports with `pedump --exports` for entry point analysis.");
    }
  
    if (props.compiler === "AutoIt") {
      extras.push(
        "AutoIt compiled executable detected. " +
        "autoit-ripper extracts and decompiles the embedded script to .au3 source. " +
        "Review the decompiled script for C2 URLs, obfuscated strings, and DllCall APIs."
      );
    } else if (props.compiler) {
      extras.push(`Unusual compiler: ${props.compiler}. This may indicate specialized tooling or uncommon origin.`);
    }
  
    if (extras.length === 0) return base;
    return base + "\n\nAdditional notes: " + extras.join(" ");
  }

• src/handlers/suggest-tools.ts:164-187 (helper)

  Helper function extractFileProperties that parses 'file' command output to detect packers (UPX, ASPack, etc.), .NET assemblies, DLLs, and compilers (PureBasic, MASM, Delphi, AutoIt) for enhanced recommendations.

  function extractFileProperties(fileOutput: string): FileProperties {
    const lower = fileOutput.toLowerCase();
    const props: FileProperties = {};
  
    if (/upx/i.test(fileOutput)) props.packed = "UPX";
    else if (/aspack/i.test(fileOutput)) props.packed = "ASPack";
    else if (/pecompact/i.test(fileOutput)) props.packed = "PECompact";
    else if (/themida/i.test(fileOutput)) props.packed = "Themida";
  
    if (lower.includes(".net") || lower.includes("mono/") || lower.includes("msil")) {
      props.isDotNet = true;
    }
  
    if (lower.includes("(dll)") || lower.includes("dll ")) {
      props.isDll = true;
    }
  
    if (/purebasic/i.test(fileOutput)) props.compiler = "PureBasic";
    else if (/masm/i.test(fileOutput)) props.compiler = "MASM";
    else if (/delphi/i.test(fileOutput)) props.compiler = "Delphi";
    else if (/autoit/i.test(fileOutput)) props.compiler = "AutoIt";
  
    return props;
  }