REMnux MCP Server

Instructions

Implementation Reference

• src/handlers/run-tool.ts:78-200 (handler)

  Main handler function handleRunTool that executes commands in REMnux. Implements path validation, command security checks, discouraged pattern warnings, command execution, output truncation, auto-parsing, and advisory generation.

  export async function handleRunTool(
    deps: HandlerDeps,
    args: RunToolArgs
  ) {
    const startTime = Date.now();
    const { connector, config } = deps;
  
    // Build full command
    let fullCommand = args.command;
    if (args.input_file) {
      // Validate input file path (skip unless --sandbox)
      if (!config.noSandbox) {
        const pathValidation = validateFilePath(args.input_file, config.samplesDir);
        if (!pathValidation.safe) {
          return formatError("run_tool", new REMnuxError(
            pathValidation.error || "Invalid input file path",
            "INVALID_PATH",
            "validation",
            "Use a relative path within the samples directory",
          ), startTime);
        }
      }
      // Append quoted file path to command (single-quotes prevent shell expansion)
      // Escape any single quotes in the path as defense-in-depth (isPathSafe also rejects them)
      const escapedFile = args.input_file.replace(/'/g, "'\\''");
      const resolvedInputFile = (config.mode === "local" && args.input_file.startsWith("/")) ? escapedFile : `${config.samplesDir}/${escapedFile}`;
      fullCommand = `${args.command} '${resolvedInputFile}'`;
    }
  
    // Security: Validate command against blocklist
    const validation = isCommandSafe(fullCommand);
    if (!validation.safe) {
      return formatError("run_tool", new REMnuxError(
        validation.error || "Command blocked",
        "COMMAND_BLOCKED",
        "security",
        "This command is blocked for security reasons. Use an allowed tool instead.",
      ), startTime);
    }
  
    // Check for discouraged patterns BEFORE execution (unless acknowledged)
    // Use regex to ensure --acknowledge-raw is a flag, not part of a filename
    const hasAcknowledge = /(?:^|\s)--acknowledge-raw(?:\s|$)/.test(args.command);
    if (!hasAcknowledge) {
      const discouraged = checkDiscouragedPattern(fullCommand);
      if (discouraged) {
        return formatResponse(
          "run_tool",
          {
            warning: discouraged.warning,
            suggestion: discouraged.suggestion,
            command_blocked: true,
            note: "Command was NOT executed. Use suggested alternatives or add --acknowledge-raw to proceed.",
          },
          startTime
        );
      }
    }
  
    const MAX_STDOUT_RESPONSE = 100 * 1024; // 100KB — fits in LLM context
    const MAX_STDERR_RESPONSE = 50 * 1024;
  
    try {
      const execOptions: { timeout: number; cwd?: string } = {
        timeout: (args.timeout || config.timeout) * 1000,
      };
  
      // Only set cwd when input_file is provided (file-based analysis)
      if (args.input_file) {
        execOptions.cwd = config.samplesDir;
      }
  
      const result = await connector.executeShell(fullCommand, execOptions);
  
      let stdout = result.stdout || "";
      let stderr = result.stderr || "";
  
      stderr = filterStderrNoise(stderr);
  
      let truncated = false;
      const fullStdoutLength = stdout.length;
  
      if (stdout.length > MAX_STDOUT_RESPONSE) {
        stdout = stdout.slice(0, MAX_STDOUT_RESPONSE);
        truncated = true;
      }
      if (stderr.length > MAX_STDERR_RESPONSE) {
        stderr = stderr.slice(0, MAX_STDERR_RESPONSE);
        truncated = true;
      }
  
      // Auto-parse output if command matches a known tool with a parser
      let findings;
      let parsedMetadata;
      const toolName = detectToolName(fullCommand);
      if (toolName && hasParser(toolName) && stdout) {
        const parsed = parseToolOutput(toolName, stdout);
        if (parsed.parsed) {
          findings = parsed.findings;
          parsedMetadata = parsed.metadata;
        }
      }
  
      // Check for advisory (non-blocking guidance)
      const advisory = getCommandAdvisory(fullCommand);
  
      return formatResponse("run_tool", {
        command: fullCommand,
        stdout,
        stderr,
        exit_code: result.exitCode,
        truncated,
        ...(truncated && {
          truncation_notice: "Output exceeded response size limit. Use 'run_tool' with '| head -N' or redirect to a file for full output.",
          full_stdout_length: fullStdoutLength,
        }),
        ...(findings && { findings, parsed_metadata: parsedMetadata }),
        ...(advisory && { advisory }),
      }, startTime);
    } catch (error) {
      return formatError("run_tool", toREMnuxError(error, config.mode), startTime);
    }
  }

• src/schemas/tools.ts:3-8 (schema)

  Zod schema definition for run_tool input validation. Defines three parameters: command (required string), input_file (optional string), and timeout (optional number with default 300).

  export const runToolSchema = z.object({
    command: z.string().describe("Command to execute (can include pipes, e.g., 'strings sample.exe | grep -i password')"),
    input_file: z.string().optional().describe("Input file path (relative to samples dir, or absolute path in local mode) - appended to command"),
    timeout: z.number().optional().describe("Timeout in seconds (default: 300)"),
  });
  export type RunToolArgs = z.infer<typeof runToolSchema>;

• src/index.ts:94-101 (registration)

  MCP tool registration for run_tool. Registers the tool with name 'run_tool', description, schema validation (runToolSchema.shape), and maps to handleRunTool handler function.

  // Tool: run_tool - Execute a command in REMnux
  server.tool(
    "run_tool",
    "Execute a command in REMnux. Supports piped commands (e.g., 'oledump.py sample.doc | grep VBA'). " +
    "String extraction: For PE files use 'pestr'; for non-PE use 'strings' (ASCII) and 'strings -el' (Unicode).",
    runToolSchema.shape,
    (args) => handleRunTool(deps, args)
  );

• src/security/blocklist.ts:149-170 (helper)

  Security validation function isCommandSafe that checks commands against blocked patterns (null byte injection, catastrophic commands). Called by handleRunTool to prevent dangerous command execution.

  export function isCommandSafe(command: string): { safe: boolean; error?: string } {
    // Reject empty or whitespace-only commands
    if (!command || command.trim() === "") {
      return { safe: false, error: "Empty command" };
    }
  
    // Check against blocked patterns
    for (const { pattern, category } of BLOCKED_PATTERNS) {
      if (pattern.test(command)) {
        return { safe: false, error: `Command blocked: ${category}` };
      }
    }
  
    // Check against dangerous pipe patterns
    for (const { pattern, category } of DANGEROUS_PIPE_PATTERNS) {
      if (pattern.test(command)) {
        return { safe: false, error: `Command blocked: ${category}` };
      }
    }
  
    return { safe: true };
  }

• src/utils/stderr-filter.ts:8-19 (helper)

  Utility function filterStderrNoise that removes common non-actionable warnings from tool stderr output (Volatility progress bars, Python warnings, compatibility notices). Called by handleRunTool to clean stderr before response.

  export function filterStderrNoise(stderr: string): string {
    return stderr
      // Volatility 3 progress bars
      .replace(/^Progress:\s+[\d.]+\s+.*$/gm, "")
      // Python SyntaxWarning / DeprecationWarning lines
      .replace(/^.*(?:SyntaxWarning|DeprecationWarning):.*$/gm, "")
      // Python version compatibility notices
      .replace(/^.*(?:This version of|requires Python).*$/gm, "")
      // Python source context lines (indented code following warnings)
      .replace(/^\s+\^+\s*$/gm, "")
      .trim();
  }