ubuntu_ufw_firewall

Instructions

Implementation Reference

• src/ubuntu-website-tools.ts:421-512 (handler)

  The main execution handler for the 'ubuntu_ufw_firewall' tool. It handles various UFW actions like enable, disable, status, allow, deny, delete, reset by executing corresponding SSH commands.

  async ubuntu_ufw_firewall(params) {
    const { connectionId, action, port, protocol, from, sudo = true } = params;
    
    try {
      const conn = getConnection(connectionMap, connectionId);
      const sudoPrefix = sudo ? 'sudo ' : '';
      
      // Validate action
      const validActions = ['enable', 'disable', 'status', 'allow', 'deny', 'delete', 'reset'];
      if (!validActions.includes(action)) {
        throw new Error(`Invalid action: ${action}. Valid actions are: ${validActions.join(', ')}`);
      }
      
      // Ensure UFW is installed
      const checkUfw = await executeSSHCommand(conn, 'which ufw || echo "not-found"');
      if (checkUfw.stdout === 'not-found') {
        const installUfw = await executeSSHCommand(conn, `${sudoPrefix}apt-get update && ${sudoPrefix}apt-get install -y ufw`);
        if (installUfw.code !== 0) {
          throw new Error(`Failed to install ufw: ${installUfw.stderr}`);
        }
      }
      
      let command = '';
      
      switch (action) {
        case 'enable':
          command = `${sudoPrefix}ufw --force enable`;
          break;
        case 'disable':
          command = `${sudoPrefix}ufw disable`;
          break;
        case 'status':
          command = `${sudoPrefix}ufw status verbose`;
          break;
        case 'reset':
          command = `${sudoPrefix}ufw --force reset`;
          break;
        case 'allow':
        case 'deny':
          // Check if port is provided
          if (!port) {
            throw new Error('Port or service name is required for allow/deny actions');
          }
          
          let ruleCommand = `${sudoPrefix}ufw ${action} `;
          
          // Add protocol if specified
          if (protocol) {
            ruleCommand += `${port}/${protocol} `;
          } else {
            ruleCommand += `${port} `;
          }
          
          // Add source IP/network if specified
          if (from) {
            ruleCommand += `from ${from}`;
          }
          
          command = ruleCommand;
          break;
        case 'delete':
          if (!port) {
            throw new Error('Port or service name is required for delete action');
          }
          
          let deleteCommand = `${sudoPrefix}ufw delete allow `;
          
          if (protocol) {
            deleteCommand += `${port}/${protocol}`;
          } else {
            deleteCommand += port;
          }
          
          command = deleteCommand;
          break;
      }
      
      const result = await executeSSHCommand(conn, command);
      
      return {
        content: [{
          type: 'text',
          text: `Firewall ${action} result:\n\n${result.stdout || result.stderr}`
        }]
      };
    } catch (error: any) {
      return {
        content: [{ type: 'text', text: `Firewall error: ${error.message}` }],
        isError: true
      };
    }
  }

• src/ubuntu-website-tools.ts:637-669 (schema)

  The input schema and description definition for the 'ubuntu_ufw_firewall' tool, used for validation and listing.

  ubuntu_ufw_firewall: {
    description: 'Manage Ubuntu Uncomplicated Firewall (UFW)',
    inputSchema: {
      type: 'object',
      properties: {
        connectionId: {
          type: 'string',
          description: 'ID of an active SSH connection'
        },
        action: {
          type: 'string',
          description: 'Action to perform (enable, disable, status, allow, deny, delete, reset)'
        },
        port: {
          type: 'string',
          description: 'Port number or service name (e.g., 80, 443, ssh, http)'
        },
        protocol: {
          type: 'string',
          description: 'Protocol (tcp, udp)'
        },
        from: {
          type: 'string',
          description: 'Source IP address or network'
        },
        sudo: {
          type: 'boolean',
          description: 'Whether to run the command with sudo (default: true)'
        }
      },
      required: ['connectionId', 'action']
    }
  }

• src/index.ts:270-299 (registration)

  The central CallToolRequestSchema handler registration that dispatches calls to ubuntu_ tools, including 'ubuntu_ufw_firewall', by invoking the corresponding function from ubuntuToolHandlers.

  this.server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
    const toolName = request.params.name;
    
    // Handle core SSH tools directly
    if (toolName.startsWith('ssh_')) {
      switch (toolName) {
        case 'ssh_connect':
          return this.handleSSHConnect(request.params.arguments);
        case 'ssh_exec':
          return this.handleSSHExec(request.params.arguments);
        case 'ssh_upload_file':
          return this.handleSSHUpload(request.params.arguments);
        case 'ssh_download_file':
          return this.handleSSHDownload(request.params.arguments);
        case 'ssh_list_files':
          return this.handleSSHListFiles(request.params.arguments);
        case 'ssh_disconnect':
          return this.handleSSHDisconnect(request.params.arguments);
        default:
          throw new Error(`Unknown SSH tool: ${toolName}`);
      }
    }
    
    // Handle Ubuntu tools directly
    if (toolName.startsWith('ubuntu_') && ubuntuToolHandlers[toolName]) {
      return ubuntuToolHandlers[toolName](request.params.arguments);
    }
    
    throw new Error(`Unknown tool: ${toolName}`);
  });

• src/ubuntu-website-tools.ts:683-689 (registration)

  The ListToolsRequestSchema handler override in addUbuntuTools that includes the 'ubuntu_ufw_firewall' schema in the tools list.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    // Create array of Ubuntu tools
    const ubuntuTools = Object.entries(ubuntuToolSchemas).map(([name, schema]) => ({
      name,
      description: schema.description,
      inputSchema: schema.inputSchema
    }));

• src/ubuntu-website-tools.ts:18-58 (helper)

  Utility function executeSSHCommand used by the ubuntu_ufw_firewall handler to run UFW commands over SSH with timeout and error handling.

  async function executeSSHCommand(conn: Client, command: string, timeout = 60000): Promise<{
    code: number;
    signal: string;
    stdout: string;
    stderr: string;
  }> {
    return new Promise((resolve, reject) => {
      // Set up timeout
      const timeoutId = setTimeout(() => {
        reject(new Error(`Command execution timed out after ${timeout}ms`));
      }, timeout);
      
      conn.exec(command, {}, (err: Error | undefined, stream: any) => {
        if (err) {
          clearTimeout(timeoutId);
          return reject(new Error(`Failed to execute command: ${err.message}`));
        }
        
        let stdout = '';
        let stderr = '';
        
        stream.on('close', (code: number, signal: string) => {
          clearTimeout(timeoutId);
          resolve({
            code,
            signal,
            stdout: stdout.trim(),
            stderr: stderr.trim()
          });
        });
        
        stream.on('data', (data: Buffer) => {
          stdout += data.toString();
        });
        
        stream.stderr.on('data', (data: Buffer) => {
          stderr += data.toString();
        });
      });
    });
  }