REMnux MCP Server

Instructions

Implementation Reference

• src/handlers/extract-archive.ts:9-108 (handler)

  Main handler function handleExtractArchive that validates inputs, checks archive type, validates paths for security, calls extractArchive, and formats the response with extracted files list and password used
  export async function handleExtractArchive( deps: HandlerDeps, args: ExtractArchiveArgs ) { const startTime = Date.now(); const { connector, config } = deps; // Validate archive file path (skip unless --sandbox) if (!config.noSandbox) { const validation = validateFilePath(args.archive_file, config.samplesDir); if (!validation.safe) { return formatError("extract_archive", new REMnuxError( validation.error || "Invalid archive file path", "INVALID_PATH", "validation", "Use a relative path within the samples directory", ), startTime); } } // Security: Validate output subdirectory if provided if (args.output_subdir && !config.noSandbox) { if (args.output_subdir.trim() === "") { return formatError("extract_archive", new REMnuxError( "output_subdir cannot be blank", "INVALID_SUBDIR", "validation", "Provide a non-empty subdirectory name without special characters", ), startTime); } if (args.output_subdir.includes("..") || args.output_subdir.includes("/") || args.output_subdir.includes("\\")) { return formatError("extract_archive", new REMnuxError( "Invalid output subdirectory name", "INVALID_SUBDIR", "validation", "Subdirectory must not contain path separators or '..'", ), startTime); } if (/[;&|`$\n\r'"\\]/.test(args.output_subdir)) { return formatError("extract_archive", new REMnuxError( "Output subdirectory contains invalid characters", "INVALID_SUBDIR", "validation", "Use only alphanumeric characters, hyphens, and underscores", ), startTime); } } // Verify archive type is supported const archiveType = detectArchiveType(args.archive_file); if (!archiveType) { return formatError("extract_archive", new REMnuxError( "Unsupported archive format. Supported: .zip, .7z, .rar", "UNSUPPORTED_FORMAT", "validation", "Rename the file with a supported extension or use a different tool", ), startTime); } // Build full archive path const archivePath = `${config.samplesDir}/${args.archive_file}`; try { const result = await extractArchive( connector, archivePath, config.samplesDir, args.password, args.output_subdir ); if (result.success) { // Store archive metadata for download_file to reuse if (result.password && archiveType) { deps.sessionState.storeArchiveInfo( args.archive_file, result.files, archiveType, result.password ); } return formatResponse("extract_archive", { extracted_to: result.outputDir, files: result.files, file_count: result.files.length, password_used: result.password || "(none - archive was not encrypted)", }, startTime); } else { return formatError("extract_archive", new REMnuxError( result.error || "Extraction failed", "EXTRACTION_FAILED", "tool_failure", "Check that the archive is valid and not corrupted", ), startTime); } } catch (error) { return formatError("extract_archive", toREMnuxError(error, deps.config.mode), startTime); } }
• src/schemas/tools.ts:20-25 (schema)

  Input schema definition for extract_archive tool using Zod validation, defining archive_file, password (optional), and output_subdir (optional) parameters
  export const extractArchiveSchema = z.object({ archive_file: z.string().describe("Path to archive file relative to samples directory (e.g., 'sample.zip')"), password: z.string().optional().describe("Optional password to try first. If not provided, tries common passwords from built-in list."), output_subdir: z.string().optional().describe("Optional subdirectory name for extracted files. Defaults to archive filename without extension."), }); export type ExtractArchiveArgs = z.infer<typeof extractArchiveSchema>;
• src/index.ts:119-125 (registration)

  Tool registration in MCP server, registering extract_archive with its description, schema, and handler function
  // Tool: extract_archive - Extract files from compressed archives server.tool( "extract_archive", "Extract files from a compressed archive (.zip, .7z, .rar). Automatically tries common malware passwords if the archive is password-protected. Returns list of extracted files.", extractArchiveSchema.shape, (args) => handleExtractArchive(deps, args) );
• src/archive-extractor.ts:278-400 (helper)

  Core extraction logic in extractArchive function that supports .zip, .7z, and .rar formats with automatic password detection, zip-slip protection, and pre-extraction validation of archive entries
  export async function extractArchive( connector: Connector, archivePath: string, samplesDir: string, customPassword?: string, outputSubdir?: string ): Promise<ExtractionResult> { // Detect archive type const archiveType = detectArchiveType(archivePath); if (!archiveType) { return { success: false, files: [], error: `Unsupported archive format: ${extname(archivePath)}`, outputDir: "", }; } // Determine output directory const archiveName = basename(archivePath, extname(archivePath)); const subdir = outputSubdir || archiveName; const outputDir = join(samplesDir, subdir); // Create output directory const mkdirResult = await connector.execute(["mkdir", "-p", outputDir], { timeout: 10000, }); if (mkdirResult.exitCode !== 0) { return { success: false, files: [], error: `Failed to create output directory: ${mkdirResult.stderr}`, outputDir, }; } // Pre-extraction zip-slip check: inspect archive entries before extracting const entries = await listArchiveEntries(connector, archivePath, archiveType); if (entries.length > 0) { const traversalEntries = checkEntriesForTraversal(entries); if (traversalEntries.length > 0) { return { success: false, files: [], error: `Archive contains path traversal entries (zip-slip): ${traversalEntries.slice(0, 3).join(", ")}${traversalEntries.length > 3 ? ` and ${traversalEntries.length - 3} more` : ""}`, outputDir, }; } } // Build password list to try const passwordsToTry: (string | undefined)[] = []; // 1. Custom password first if provided if (customPassword) { passwordsToTry.push(customPassword); } // 2. Try without password (archive might not be encrypted) passwordsToTry.push(undefined); // 3. Add passwords from config file const configPasswords = loadPasswordList(); for (const pwd of configPasswords) { if (pwd !== customPassword) { // Avoid duplicates passwordsToTry.push(pwd); } } // Try extraction with each password let lastError = ""; for (const password of passwordsToTry) { try { const cmd = getExtractionCommand(archiveType, archivePath, outputDir, password); const result = await connector.execute(cmd, { timeout: 120000 }); if (result.exitCode === 0) { // Success! List extracted files const files = await listExtractedFiles(connector, outputDir); // Validate for zip-slip attacks (path traversal in archive entries) const escapeAttempts = validateExtractedPaths(files, outputDir); if (escapeAttempts.length > 0) { // Clean up potentially malicious files await connector.execute(["rm", "-rf", outputDir], { timeout: 30000 }); return { success: false, files: [], error: `Archive contains path escape attempts (zip-slip): ${escapeAttempts.slice(0, 3).join(", ")}${escapeAttempts.length > 3 ? ` and ${escapeAttempts.length - 3} more` : ""}`, outputDir, }; } return { success: true, files, password: password, // undefined if no password was needed outputDir, }; } // Check if this is a password error if (isWrongPasswordError(result, archiveType)) { lastError = "Incorrect password"; continue; // Try next password } // Some other error - might still try other passwords for encrypted archives lastError = result.stderr || result.stdout || "Unknown extraction error"; } catch (err) { lastError = err instanceof Error ? err.message : "Extraction failed"; } } // All passwords failed return { success: false, files: [], error: `Extraction failed: ${lastError}. Tried ${passwordsToTry.length} password(s).`, outputDir, }; }
• src/archive-extractor.ts:29-41 (helper)

  Helper function detectArchiveType that identifies archive format from file extension (.zip, .7z, .rar)
  export function detectArchiveType(filename: string): ArchiveType { const ext = extname(filename).toLowerCase(); switch (ext) { case ".zip": return "zip"; case ".7z": return "7z"; case ".rar": return "rar"; default: return null; } }