shell_command
Execute terminal commands for malware analysis with configurable timeout and background execution capabilities.
Instructions
Execute a command in the terminal with timeout. Command will continue running in background if it doesn't complete within timeout.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The command to execute in the terminal | |
| timeout_ms | No | Optional timeout in milliseconds (default: 30000) |
Implementation Reference
- terminalManager.js:27-104 (handler)Core handler function that spawns the shell command using child_process.spawn with shell: true, captures stdout/stderr output, handles timeout by marking as blocked, tracks process in sessions map, and resolves with pid, output, and blocked status.async shellCommand(command, timeoutMs = DEF_TIMEOUT) { const process = spawn(command, [], { shell: true }); let output = ''; // Ensure process.pid is defined before proceeding if (!process.pid) { return { pid: -1, // Use -1 to indicate an error state output: 'Error: Failed to get process ID. The command could not be executed.', isBlocked: false }; } // Create a session object to track this process const session = { pid: process.pid, process, lastOutput: '', isBlocked: false, startTime: new Date() }; this.sessions.set(process.pid, session); return new Promise((resolve) => { // Handle standard output process.stdout.on('data', (data) => { const text = data.toString(); output += text; session.lastOutput += text; }); // Handle error output process.stderr.on('data', (data) => { const text = data.toString(); output += text; session.lastOutput += text; }); // Set timeout to mark process as blocked if it exceeds timeoutMs setTimeout(() => { session.isBlocked = true; resolve({ pid: process.pid, output, isBlocked: true }); }, timeoutMs); // Handle process completion process.on('exit', (code) => { if (process.pid) { // Store completed session before removing active session this.completedSessions.set(process.pid, { pid: process.pid, output: output + session.lastOutput, // Combine all output exitCode: code, startTime: session.startTime, endTime: new Date() }); // Keep only last 50 completed sessions if (this.completedSessions.size > 50) { const oldestKey = Array.from(this.completedSessions.keys())[0]; this.completedSessions.delete(oldestKey); } this.sessions.delete(process.pid); } resolve({ pid: process.pid, output, isBlocked: false }); }); }); }
- serverMCP.js:168-193 (handler)MCP tool call handler for 'shell_command' in the main server request handler. Validates arguments, calls terminalManager.shellCommand, and returns JSON result or error.case 'shell_command': try { // Type-check and validate arguments if (!args || typeof args.command !== 'string') { return { content: [{ type: "text", text: "Error: Invalid command parameter" }], isError: true, }; } console.error(`Executing command: ${args.command}`); const result = await terminalManager.shellCommand( args.command, typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined ); console.error(`Command executed with PID: ${result.pid}, blocked: ${result.isBlocked}`); return { content: [{ type: "text", text: JSON.stringify(result) }], }; } catch (error) { console.error('Error executing command:', error); return { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true, }; }
- serverMCP.js:45-48 (schema)Zod schema defining input parameters for shell_command tool: command (required string) and timeout_ms (optional number).const shellCommandSchema = z.object({ command: z.string().min(1).describe("The command to execute in the terminal"), timeout_ms: z.number().optional().describe("Optional timeout in milliseconds (default: 30000)") });
- serverMCP.js:101-104 (registration)Registration of the shell_command tool in the ListToolsRequestSchema handler, including name, description, and inputSchema converted from Zod schema.name: 'shell_command', description: 'Execute a command in the terminal with timeout. Command will continue running in background if it doesn\'t complete within timeout.', inputSchema: zodToJsonSchema(shellCommandSchema), },