REMnux MCP Server

Instructions

Implementation Reference

• src/handlers/download-file.ts:37-177 (handler)

  Main handler function `handleDownloadFile` that implements the download_file tool. It validates file paths, checks file size (200MB limit), optionally creates password-protected archives (zip/7z/rar), transfers files from REMnux to the host filesystem, and returns formatted responses with file metadata (path, size, SHA256, archive info).

  export async function handleDownloadFile(
    deps: HandlerDeps,
    args: DownloadFileArgs
  ) {
    const startTime = Date.now();
    const { connector, config } = deps;
    const shouldArchive = args.archive !== false;
  
    // Validate file path (skip unless --sandbox)
    if (!config.noSandbox) {
      const validation = validateFilePath(args.file_path, config.outputDir);
      if (!validation.safe) {
        return formatError("download_file", new REMnuxError(
          validation.error || "Invalid file path",
          "INVALID_PATH",
          "validation",
          "Use a relative path within the output directory",
        ), startTime);
      }
    }
  
    // Validate outputPath
    const pathValidation = validateHostPath(args.output_path);
    if (!pathValidation.valid) {
      return formatError("download_file", new REMnuxError(
        pathValidation.error || "Invalid output path",
        "INVALID_PATH",
        "validation",
        "Provide an absolute path to a directory on the host filesystem",
      ), startTime);
    }
  
    // Verify output directory exists and is a directory
    if (!existsSync(args.output_path) || !statSync(args.output_path).isDirectory()) {
      return formatError("download_file", new REMnuxError(
        `Output path does not exist or is not a directory: ${args.output_path}`,
        "INVALID_PATH",
        "validation",
        "Provide an absolute path to an existing directory",
      ), startTime);
    }
  
    const fullPath = `${config.outputDir}/${args.file_path}`;
  
    try {
      // Get file size and hash (separate calls to avoid shell interpolation)
      const statResult = await connector.execute(
        ["stat", "-c", "%s", fullPath],
        { timeout: 30000 }
      );
      const hashResult = await connector.execute(
        ["sha256sum", fullPath],
        { timeout: 30000 }
      );
  
      const sizeBytes = parseInt((statResult.stdout || "0").trim(), 10);
  
      // Guard against oversized downloads
      if (sizeBytes > MAX_DOWNLOAD_SIZE) {
        return formatError("download_file", new REMnuxError(
          `File exceeds ${MAX_DOWNLOAD_SIZE / 1024 / 1024}MB download limit (got ${(sizeBytes / 1024 / 1024).toFixed(2)}MB)`,
          "FILE_TOO_LARGE",
          "validation",
          "Use run_tool with 'split' to break the file into smaller parts first",
        ), startTime);
      }
  
      const sha256 = (hashResult.stdout || "").trim().split(/\s+/)[0] || "unknown";
      const filename = basename(args.file_path);
  
      if (shouldArchive) {
        // Determine archive format and password from session state
        const archiveMeta = deps.sessionState.getArchiveInfo(filename);
        const archiveFormat = archiveMeta?.format ?? DEFAULT_ARCHIVE_FORMAT;
        const archivePassword = archiveMeta?.password ?? DEFAULT_ARCHIVE_PASSWORD;
  
        // Defense-in-depth: reject passwords with shell metacharacters
        if (/[;&|`$\n\r'"\\]/.test(archivePassword)) {
          return formatError("download_file", new REMnuxError(
            "Archive password contains unsafe characters",
            "INVALID_PASSWORD",
            "validation",
            "Try downloading with archive: false",
          ), startTime);
        }
  
        // Create temp archive path inside REMnux
        const timestamp = Date.now();
        const archiveName = `${filename}${archiveExtension(archiveFormat)}`;
        const remoteTmpArchive = `/tmp/dl_${timestamp}_${archiveName}`;
  
        // Create password-protected archive
        const archiveCmd = getArchiveCommand(archiveFormat, remoteTmpArchive, fullPath, archivePassword);
        const archiveResult = await connector.execute(archiveCmd, {
          timeout: Math.max(60000, sizeBytes / 1024),
        });
  
        if (archiveResult.exitCode !== 0) {
          return formatError("download_file", new REMnuxError(
            `Failed to create archive: ${archiveResult.stderr || archiveResult.stdout}`,
            "ARCHIVE_FAILED",
            "tool_failure",
            "Try downloading with archive: false",
          ), startTime);
        }
  
        // Transfer archive to host
        const hostPath = join(args.output_path, archiveName);
        try {
          await connector.readFileToPath(remoteTmpArchive, hostPath);
        } finally {
          // Clean up temp archive inside REMnux
          await connector.execute(["rm", "-f", remoteTmpArchive], { timeout: 10000 }).catch(() => {});
        }
  
        return formatResponse("download_file", {
          file_path: args.file_path,
          size_bytes: sizeBytes,
          sha256,
          host_path: hostPath,
          archived: true,
          archive_format: archiveFormat,
          archive_password: archivePassword,
        }, startTime);
      }
  
      // No archiving — transfer raw file
      const hostPath = join(args.output_path, filename);
      await connector.readFileToPath(fullPath, hostPath);
  
      return formatResponse("download_file", {
        file_path: args.file_path,
        size_bytes: sizeBytes,
        sha256,
        host_path: hostPath,
        archived: false,
      }, startTime);
    } catch (error) {
      return formatError("download_file", toREMnuxError(error, deps.config.mode), startTime);
    }
  }

• src/schemas/tools.ts:34-42 (schema)

  Zod schema `downloadFileSchema` defining the tool's input parameters: file_path (relative path in output directory), output_path (host directory to save to), and archive (optional boolean, default true) to control password-protected archive wrapping. Also exports the TypeScript type `DownloadFileArgs`.

  export const downloadFileSchema = z.object({
    file_path: z.string().describe("File path relative to the output directory"),
    output_path: z.string().describe("Directory on host to save the downloaded file"),
    archive: z.boolean().optional().default(true).describe(
      "Wrap the file in a password-protected archive before transfer (default: true). " +
      "Protects against AV/EDR triggers on the host. Pass false for harmless files like text reports."
    ),
  });
  export type DownloadFileArgs = z.input<typeof downloadFileSchema>;

• src/index.ts:168-177 (registration)

  Tool registration where `download_file` is registered with the MCP server using `server.tool()`. Includes tool description explaining archiving behavior to prevent AV/EDR triggers, and wires up the schema and handler function.

  // Tool: download_file - Download a file from the output directory
  server.tool(
    "download_file",
    "Download a file from the output directory (returns base64-encoded content). Use this to retrieve analysis results. " +
    "Files are wrapped in a password-protected archive by default to prevent AV/EDR triggers. " +
    "Pass archive: false for harmless files like text reports. " +
    "Provide output_path to save directly to the host filesystem.",
    downloadFileSchema.shape,
    (args) => handleDownloadFile(deps, args)
  );

• src/handlers/download-file.ts:17-35 (helper)

  Helper functions for archive creation: `getArchiveCommand()` builds command-line arguments for zip/7z/rar formats with password protection, and `archiveExtension()` returns the appropriate file extension (.zip, .7z, .rar) for each format.

  function getArchiveCommand(
    format: "zip" | "7z" | "rar",
    archivePath: string,
    sourcePath: string,
    password: string
  ): string[] {
    switch (format) {
      case "zip":
        return ["zip", "-j", "-P", password, archivePath, sourcePath];
      case "7z":
        return ["7z", "a", `-p${password}`, "-mhe=on", archivePath, sourcePath];
      case "rar":
        return ["rar", "a", `-p${password}`, "-hp", archivePath, sourcePath];
    }
  }
  
  function archiveExtension(format: "zip" | "7z" | "rar"): string {
    return `.${format}`;
  }