gh-127478: ftplib: prefer EPSV over PASV on IPv4 connections

makepasv() now tries EPSV (RFC 2428) before PASV when connected over
IPv4. EPSV returns only a port number without an IP address, making it
transparent to firewall FTP Application Layer Gateways (ALGs) that
intercept and often mangle PASV responses containing embedded IPs.

Falls back to PASV if the server responds with an error to EPSV.
A new class attribute FTP.prefer_epsv (default True) allows reverting
to the old PASV-first behavior when set to False.

This also fixes connectivity issues caused by the trust_server_pasv_ipv4_address
security fix (bpo-43285): when firewalls rewrite PASV responses, clients
connecting to the control channel IP on the data port often fail because
nothing is listening there. EPSV avoids this entirely since the client
always connects back to the same IP.

Author: simonepelosi

Lib/ftplib.py

@@ -105,6 +105,10 @@ class FTP:
     passiveserver = True
     # Disables https://bugs.python.org/issue43285 security if set to True.
     trust_server_pasv_ipv4_address = False
+    # Prefer EPSV (RFC 2428) over PASV on IPv4 connections.
+    # EPSV is firewall-transparent (no IP in response) and works on both
+    # IPv4 and IPv6. Falls back to PASV if server doesn't support EPSV.
+    prefer_epsv = True
 
     def __init__(self, host='', user='', passwd='', acct='',
                  timeout=_GLOBAL_DEFAULT_TIMEOUT, source_address=None, *,
@@ -322,8 +326,20 @@ def makeport(self):
         return sock
 
     def makepasv(self):
-        """Internal: Does the PASV or EPSV handshake -> (address, port)"""
+        """Internal: Does the EPSV or PASV handshake -> (address, port)
+
+        Prefers EPSV (RFC 2428) on IPv4 when prefer_epsv is True, falling
+        back to PASV if the server does not support EPSV. EPSV is always
+        used on IPv6 regardless of prefer_epsv.
+        """
         if self.af == socket.AF_INET:
+            if self.prefer_epsv:
+                try:
+                    host, port = parse229(self.sendcmd('EPSV'),
+                                          self.sock.getpeername())
+                    return host, port
+                except error_perm:
+                    pass
             untrusted_host, port = parse227(self.sendcmd('PASV'))
             if self.trust_server_pasv_ipv4_address:
                 host = untrusted_host

Lib/test/test_ftplib.py

@@ -178,7 +178,7 @@ def cmd_eprt(self, arg):
 
     def cmd_epsv(self, arg):
         with socket.create_server((self.socket.getsockname()[0], 0),
-                                  family=socket.AF_INET6) as sock:
+                                  family=self.socket.family) as sock:
             sock.settimeout(TIMEOUT)
             port = sock.getsockname()[1]
             self.push('229 entering extended passive mode (|||%d|)' %port)
@@ -724,11 +724,31 @@ def test_makepasv(self):
         host, port = self.client.makepasv()
         conn = socket.create_connection((host, port), timeout=TIMEOUT)
         conn.close()
-        # IPv4 is in use, just make sure send_epsv has not been used
+        # IPv4 with prefer_epsv=True (default) should use EPSV
+        self.assertEqual(self.server.handler_instance.last_received_cmd, 'epsv')
+
+    def test_makepasv_prefer_epsv_disabled(self):
+        self.client.prefer_epsv = False
+        host, port = self.client.makepasv()
+        conn = socket.create_connection((host, port), timeout=TIMEOUT)
+        conn.close()
         self.assertEqual(self.server.handler_instance.last_received_cmd, 'pasv')
 
+    def test_makepasv_prefer_epsv_fallback_to_pasv(self):
+        # Simulate server not supporting EPSV by monkey-patching the handler
+        original_cmd_epsv = self.server.handler.cmd_epsv
+        self.server.handler.cmd_epsv = lambda self_handler, arg: self_handler.push('500 EPSV not understood')
+        try:
+            host, port = self.client.makepasv()
+            conn = socket.create_connection((host, port), timeout=TIMEOUT)
+            conn.close()
+            self.assertEqual(self.server.handler_instance.last_received_cmd, 'pasv')
+        finally:
+            self.server.handler.cmd_epsv = original_cmd_epsv
+
     def test_makepasv_issue43285_security_disabled(self):
         """Test the opt-in to the old vulnerable behavior."""
+        self.client.prefer_epsv = False
         self.client.trust_server_pasv_ipv4_address = True
         bad_host, port = self.client.makepasv()
         self.assertEqual(
@@ -739,6 +759,7 @@ def test_makepasv_issue43285_security_disabled(self):
                                  timeout=TIMEOUT).close()
 
     def test_makepasv_issue43285_security_enabled_default(self):
+        self.client.prefer_epsv = False
         self.assertFalse(self.client.trust_server_pasv_ipv4_address)
         trusted_host, port = self.client.makepasv()
         self.assertNotEqual(

Misc/NEWS.d/next/Library/2026-05-22-12-00-00.gh-issue-127478.EpsvFtp.rst

@@ -0,0 +1,6 @@
+:mod:`ftplib`: :meth:`~ftplib.FTP.makepasv` now prefers EPSV (RFC 2428) over
+PASV on IPv4 connections, falling back to PASV if the server does not support
+EPSV. EPSV is firewall-transparent as it does not embed an IP address in the
+response, avoiding interference from firewall FTP Application Layer Gateways
+(ALGs). A new class attribute :attr:`~ftplib.FTP.prefer_epsv` (default
+``True``) controls this behavior.