smbclientng.core.SMBSession API documentation

SMBSession( address, domain, username, password, lmhash, nthash, use_kerberos=False, kdcHost=None, config=None) View Source

46    def __init__(self, address, domain, username, password, lmhash, nthash, use_kerberos=False, kdcHost=None, config=None):
47        super(SMBSession, self).__init__()
48        # Objects
49        self.config = config
50
51        # Target server
52        self.address = address
53
54        # Credentials
55        self.domain = domain
56        self.username = username
57        self.password = password 
58        self.lmhash = lmhash
59        self.nthash = nthash
60        self.use_kerberos = use_kerberos
61        self.kdcHost = kdcHost
62
63        self.smbClient = None
64        self.connected = False
65
66        self.available_shares = {}
67        self.smb_share = None
68        self.smb_cwd = ""
69
70        self.list_shares()

config

address

domain

username

password

lmhash

nthash

use_kerberos

kdcHost

smbClient

connected

available_shares

smb_share

smb_cwd

def init_smb_session(self): View Source

 74    def init_smb_session(self):
 75        """
 76        Initializes and establishes a session with the SMB server.
 77
 78        This method sets up the SMB connection using either Kerberos or NTLM authentication based on the configuration.
 79        It attempts to connect to the SMB server specified by the `address` attribute and authenticate using the credentials provided during the object's initialization.
 80
 81        The method will print debug information if the `debug` attribute is set to True. Upon successful connection and authentication, it sets the `connected` attribute to True.
 82
 83        Returns:
 84            bool: True if the connection and authentication are successful, False otherwise.
 85        """
 86
 87        self.connected = False
 88
 89        if self.config.debug:
 90            print("[debug] [>] Connecting to remote SMB server '%s' ... " % self.address)
 91        try:
 92            self.smbClient = impacket.smbconnection.SMBConnection(
 93                remoteName=self.address,
 94                remoteHost=self.address,
 95                sess_port=int(445)
 96            )
 97        except OSError as err:
 98            print("[!] %s" % err)
 99            self.smbClient = None
100
101        if self.smbClient is not None:
102            if self.use_kerberos:
103                if self.config.debug:
104                    print("[debug] [>] Authenticating as '%s\\%s' with kerberos ... " % (self.domain, self.username))
105                try:
106                    self.connected = self.smbClient.kerberosLogin(
107                        user=self.username,
108                        password=self.password,
109                        domain=self.domain,
110                        lmhash=self.lmhash,
111                        nthash=self.nthash,
112                        aesKey=self.aesKey,
113                        kdcHost=self.kdcHost
114                    )
115                except impacket.smbconnection.SessionError as err:
116                    if self.config.debug:
117                        traceback.print_exc()
118                    print("[!] Could not login: %s" % err)
119                    self.connected = False
120
121            else:
122                if self.config.debug:
123                    print("[debug] [>] Authenticating as '%s\\%s' with NTLM ... " % (self.domain, self.username))
124                try:
125                    self.connected = self.smbClient.login(
126                        user=self.username,
127                        password=self.password,
128                        domain=self.domain,
129                        lmhash=self.lmhash,
130                        nthash=self.nthash
131                    )
132                except impacket.smbconnection.SessionError as err:
133                    if self.config.debug:
134                        traceback.print_exc()
135                    print("[!] Could not login: %s" % err)
136                    self.connected = False
137
138            if self.connected:
139                print("[+] Successfully authenticated to '%s' as '%s\\%s'!" % (self.address, self.domain, self.username))
140            else:
141                print("[!] Failed to authenticate to '%s' as '%s\\%s'!" % (self.address, self.domain, self.username))
142
143        return self.connected

Initializes and establishes a session with the SMB server.

This method sets up the SMB connection using either Kerberos or NTLM authentication based on the configuration. It attempts to connect to the SMB server specified by the address attribute and authenticate using the credentials provided during the object's initialization.

The method will print debug information if the debug attribute is set to True. Upon successful connection and authentication, it sets the connected attribute to True.

Returns: bool: True if the connection and authentication are successful, False otherwise.

def close_smb_session(self): View Source

145    def close_smb_session(self):
146        """
147        Closes the current SMB session by disconnecting the SMB client.
148
149        This method ensures that the SMB client connection is properly closed. It checks if the client is connected
150        and if so, it closes the connection and resets the connection status.
151
152        Raises:
153            Exception: If the SMB client is not initialized or if there's an error during the disconnection process.
154        """
155
156        if self.smbClient is not None:
157            if self.connected:
158                self.smbClient.close()
159                self.connected = False
160                if self.config.debug:
161                    print("[+] SMB connection closed successfully.")
162            else:
163                if self.config.debug:
164                    print("[!] No active SMB connection to close.")
165        else:
166            raise Exception("SMB client is not initialized.")

Closes the current SMB session by disconnecting the SMB client.

This method ensures that the SMB client connection is properly closed. It checks if the client is connected and if so, it closes the connection and resets the connection status.

Raises: Exception: If the SMB client is not initialized or if there's an error during the disconnection process.

def read_file(self, path=None): View Source

170    def read_file(self, path=None):
171        if self.path_isfile(path=path):
172            tmp_file_path = self.smb_cwd + ntpath.sep + path
173            matches = self.smbClient.listPath(
174                shareName=self.smb_share, 
175                path=tmp_file_path
176            )
177
178            fh = io.BytesIO()
179            try:
180                # opening the files in streams instead of mounting shares allows 
181                # for running the script from unprivileged containers
182                self.smbClient.getFile(self.smb_share, tmp_file_path, fh.write)
183            except impacket.smbconnection.SessionError as e:
184                return None
185            rawdata = fh.getvalue()
186            fh.close()
187            return rawdata
188        else:
189            print("[!] Remote path '%s' is not a file." % path)

def find(self, paths=[], callback=None): View Source

191    def find(self, paths=[], callback=None):
192        def recurse_action(paths=[], depth=0, callback=None):
193            if callback is None:
194                return []
195            next_directories_to_explore = []
196            for path in paths:
197                remote_smb_path = ntpath.normpath(self.smb_cwd + ntpath.sep + path)
198                entries = []
199                
200                try:
201                    entries = self.smbClient.listPath(
202                        shareName=self.smb_share, 
203                        path=(remote_smb_path + ntpath.sep + '*')
204                    )
205                except impacket.smbconnection.SessionError as err:
206                    continue 
207                # Remove dot names
208                entries = [e for e in entries if e.get_longname() not in [".", ".."]]
209                # Sort the entries ignoring case
210                entries = sorted(entries, key=lambda x:x.get_longname().lower())
211                
212                for entry in entries:
213                    if entry.is_directory():
214                        callback(entry, path + entry.get_longname() + ntpath.sep, depth)
215                    else:
216                        callback(entry, path + entry.get_longname(), depth)
217
218                # Next directories to explore
219                for entry in entries:
220                    if entry.is_directory():
221                        next_directories_to_explore.append(path + entry.get_longname() + ntpath.sep)
222            
223            return next_directories_to_explore
224        # 
225        if callback is not None:
226            depth = 0
227            while len(paths) != 0:
228                paths = recurse_action(
229                    paths=paths,
230                    depth=depth,
231                    callback=callback
232                )
233                depth = depth + 1
234        else:
235            print("[!] SMBSession.find(), callback function cannot be None.")

def get_file(self, path=None, keepRemotePath=False): View Source

237    def get_file(self, path=None, keepRemotePath=False):
238        """
239        Retrieves a file from the specified path on the SMB share.
240
241        This method attempts to retrieve a file from the given path within the currently connected SMB share.
242        If the path points to a directory, it skips the retrieval. It handles file retrieval by creating a local
243        file object and writing the contents of the remote file to it using the SMB client's getFile method.
244
245        Parameters:
246            path (str): The path of the file to retrieve. If None, uses the current smb_path.
247
248        Returns:
249            None
250        """
251
252        tmp_file_path = self.smb_cwd + ntpath.sep + path
253        matches = self.smbClient.listPath(
254            shareName=self.smb_share, 
255            path=tmp_file_path
256        )
257        
258        for entry in matches:
259            if entry.is_directory():
260                print("[>] Skipping '%s' because it is a directory." % tmp_file_path)
261            else:
262                try:
263                    if ntpath.sep in path:
264                        outputfile = ntpath.dirname(path) + ntpath.sep + entry.get_longname()
265                    else:
266                        outputfile = entry.get_longname()
267                    f = LocalFileIO(
268                        mode="wb", 
269                        path=outputfile,
270                        expected_size=entry.get_filesize(), 
271                        debug=self.config.debug,
272                        keepRemotePath=keepRemotePath
273                    )
274                    self.smbClient.getFile(
275                        shareName=self.smb_share, 
276                        pathName=tmp_file_path, 
277                        callback=f.write
278                    )
279                    f.close()
280                except (BrokenPipeError, KeyboardInterrupt) as e:
281                    f.close()
282                    print("\x1b[v\x1b[o\r[!] Interrupted.")
283                    self.close_smb_session()
284                    self.init_smb_session()
285                        
286        return None

Retrieves a file from the specified path on the SMB share.

This method attempts to retrieve a file from the given path within the currently connected SMB share. If the path points to a directory, it skips the retrieval. It handles file retrieval by creating a local file object and writing the contents of the remote file to it using the SMB client's getFile method.

Parameters: path (str): The path of the file to retrieve. If None, uses the current smb_path.

Returns: None

def get_file_recursively(self, path=None): View Source

288    def get_file_recursively(self, path=None):
289        """
290        Recursively retrieves files from a specified path on the SMB share.
291
292        This method navigates through all directories starting from the given path,
293        and downloads all files found. It handles directories recursively, ensuring
294        that all nested files are retrieved. The method skips over directory entries
295        and handles errors gracefully, attempting to continue the operation where possible.
296
297        Parameters:
298            path (str): The initial directory path from which to start the recursive file retrieval.
299                        If None, it starts from the root of the configured SMB share.
300        """
301        
302        def recurse_action(base_dir="", path=[]):
303            remote_smb_path = base_dir + ntpath.sep.join(path)
304            entries = self.smbClient.listPath(
305                shareName=self.smb_share, 
306                path=remote_smb_path + '\\*'
307            )
308            if len(entries) != 0:
309                files = [entry for entry in entries if not entry.is_directory()]
310                directories = [entry for entry in entries if entry.is_directory() and entry.get_longname() not in [".", ".."]]
311
312                # Files
313                if len(files) != 0:
314                    print("[>] Retrieving files of '%s'" % remote_smb_path)
315                for entry_file in files:
316                    if not entry_file.is_directory():
317                        f = LocalFileIO(
318                            mode="wb",
319                            path=remote_smb_path + ntpath.sep + entry_file.get_longname(), 
320                            expected_size=entry_file.get_filesize(),
321                            debug=self.config.debug
322                        )
323                        try:
324                            self.smbClient.getFile(
325                                shareName=self.smb_share, 
326                                pathName=remote_smb_path + ntpath.sep + entry_file.get_longname(), 
327                                callback=f.write
328                            )
329                            f.close()
330                        except BrokenPipeError as err:
331                            f.set_error(message="[bold red]Failed downloading '%s': %s" % (f.path, err))
332                            f.close(remove=True)
333                            break
334                        except Exception as err:
335                            f.set_error(message="[bold red]Failed downloading '%s': %s" % (f.path, err))
336                            f.close(remove=True)
337                
338                # Directories
339                for entry_directory in directories:
340                    if entry_directory.is_directory():
341                        recurse_action(
342                            base_dir=self.smb_cwd, 
343                            path=path+[entry_directory.get_longname()]
344                        )                   
345        # Entrypoint
346        try:
347            recurse_action(
348                base_dir=self.smb_cwd, 
349                path=[path]
350            )
351        except (BrokenPipeError, KeyboardInterrupt) as e:
352            print("\x1b[v\x1b[o\r[!] Interrupted.")
353            self.close_smb_session()
354            self.init_smb_session()

Recursively retrieves files from a specified path on the SMB share.

This method navigates through all directories starting from the given path, and downloads all files found. It handles directories recursively, ensuring that all nested files are retrieved. The method skips over directory entries and handles errors gracefully, attempting to continue the operation where possible.

Parameters: path (str): The initial directory path from which to start the recursive file retrieval. If None, it starts from the root of the configured SMB share.

def info(self, share=True, server=True): View Source

356    def info(self, share=True, server=True):
357        """
358        Displays information about the server and optionally the shares.
359
360        This method prints detailed information about the server's characteristics such as NetBIOS names, DNS details, OS information, and SMB capabilities. If the `share` parameter is set to True and a share is currently set, it will also attempt to display information about the share.
361
362        Parameters:
363            share (bool): If True, display information about the current share.
364            server (bool): If True, display information about the server.
365
366        Returns:
367            None
368        """
369
370        if server:
371            if self.config.no_colors:
372                print("[+] Server:")
373                print("  ├─NetBIOS:")
374                print("  │ ├─ NetBIOS Hostname ──────── : %s" % (self.smbClient.getServerName()))
375                print("  │ └─ NetBIOS Domain ────────── : %s" % (self.smbClient.getServerDomain()))
376                print("  ├─DNS:")
377                print("  │ ├─ DNS Hostname ──────────── : %s" % (self.smbClient.getServerDNSHostName()))
378                print("  │ └─ DNS Domain ────────────── : %s" % (self.smbClient.getServerDNSDomainName()))
379                print("  ├─OS:")
380                print("  │ ├─ OS Name ───────────────── : %s" % (self.smbClient.getServerOS()))
381                print("  │ └─ OS Version ────────────── : %s.%s.%s" % (self.smbClient.getServerOSMajor(), self.smbClient.getServerOSMinor(), self.smbClient.getServerOSBuild()))
382                print("  ├─Server:")
383                print("  │ ├─ Signing Required ──────── : %s" % (self.smbClient.isSigningRequired()))
384                print("  │ ├─ Login Required ────────── : %s" % (self.smbClient.isLoginRequired()))
385                print("  │ ├─ Supports NTLMv2 ───────── : %s" % (self.smbClient.doesSupportNTLMv2()))
386                MaxReadSize = self.smbClient.getIOCapabilities()["MaxReadSize"]
387                print("  │ ├─ Max size of read chunk ── : %d bytes (%s)" % (MaxReadSize, b_filesize(MaxReadSize)))
388                MaxWriteSize = self.smbClient.getIOCapabilities()["MaxWriteSize"]
389                print("  │ └─ Max size of write chunk ─ : %d bytes (%s)" % (MaxWriteSize, b_filesize(MaxWriteSize)))
390                print("  └─")
391            else:
392                print("[+] Server:")
393                print("  ├─NetBIOS:")
394                print("  │ ├─ \x1b[94mNetBIOS Hostname\x1b[0m \x1b[90m────────\x1b[0m : \x1b[93m%s\x1b[0m" % (self.smbClient.getServerName()))
395                print("  │ └─ \x1b[94mNetBIOS Domain\x1b[0m \x1b[90m──────────\x1b[0m : \x1b[93m%s\x1b[0m" % (self.smbClient.getServerDomain()))
396                print("  ├─DNS:")
397                print("  │ ├─ \x1b[94mDNS Hostname\x1b[0m \x1b[90m────────────\x1b[0m : \x1b[93m%s\x1b[0m" % (self.smbClient.getServerDNSHostName()))
398                print("  │ └─ \x1b[94mDNS Domain\x1b[0m \x1b[90m──────────────\x1b[0m : \x1b[93m%s\x1b[0m" % (self.smbClient.getServerDNSDomainName()))
399                print("  ├─OS:")
400                print("  │ ├─ \x1b[94mOS Name\x1b[0m \x1b[90m─────────────────\x1b[0m : \x1b[93m%s\x1b[0m" % (self.smbClient.getServerOS()))
401                print("  │ └─ \x1b[94mOS Version\x1b[0m \x1b[90m──────────────\x1b[0m : \x1b[93m%s.%s.%s\x1b[0m" % (self.smbClient.getServerOSMajor(), self.smbClient.getServerOSMinor(), self.smbClient.getServerOSBuild()))
402                print("  ├─Server:")
403                print("  │ ├─ \x1b[94mSigning Required\x1b[0m \x1b[90m────────\x1b[0m : \x1b[93m%s\x1b[0m" % (self.smbClient.isSigningRequired()))
404                print("  │ ├─ \x1b[94mLogin Required\x1b[0m \x1b[90m──────────\x1b[0m : \x1b[93m%s\x1b[0m" % (self.smbClient.isLoginRequired()))
405                print("  │ ├─ \x1b[94mSupports NTLMv2\x1b[0m \x1b[90m─────────\x1b[0m : \x1b[93m%s\x1b[0m" % (self.smbClient.doesSupportNTLMv2()))
406                MaxReadSize = self.smbClient.getIOCapabilities()["MaxReadSize"]
407                print("  │ ├─ \x1b[94mMax size of read chunk\x1b[0m \x1b[90m──\x1b[0m : \x1b[93m%d bytes (%s)\x1b[0m" % (MaxReadSize, b_filesize(MaxReadSize)))
408                MaxWriteSize = self.smbClient.getIOCapabilities()["MaxWriteSize"]
409                print("  │ └─ \x1b[94mMax size of write chunk\x1b[0m \x1b[90m─\x1b[0m : \x1b[93m%d bytes (%s)\x1b[0m" % (MaxWriteSize, b_filesize(MaxWriteSize)))
410                print("  └─")
411
412        if share and self.smb_share is not None:
413            share_name = self.available_shares.get(self.smb_share.lower(), "")["name"]
414            share_comment = self.available_shares.get(self.smb_share.lower(), "")["comment"]
415            share_type = self.available_shares.get(self.smb_share.lower(), "")["type"]
416            share_type =', '.join([s.replace("STYPE_","") for s in share_type])
417            share_rawtype = self.available_shares.get(self.smb_share.lower(), "")["rawtype"]
418            if self.config.no_colors:
419                print("\n[+] Share:")
420                print("  ├─ Name ──────────── : %s" % (share_name))
421                print("  ├─ Description ───── : %s" % (share_comment))
422                print("  ├─ Type ──────────── : %s" % (share_type))
423                print("  └─ Raw type value ── : %s" % (share_rawtype))
424            else:
425                print("\n[+] Share:")
426                print("  ├─ \x1b[94mName\x1b[0m \x1b[90m────────────\x1b[0m : \x1b[93m%s\x1b[0m" % (share_name))
427                print("  ├─ \x1b[94mDescription\x1b[0m \x1b[90m─────\x1b[0m : \x1b[93m%s\x1b[0m" % (share_comment))
428                print("  ├─ \x1b[94mType\x1b[0m \x1b[90m────────────\x1b[0m : \x1b[93m%s\x1b[0m" % (share_type))
429                print("  └─ \x1b[94mRaw type value\x1b[0m \x1b[90m──\x1b[0m : \x1b[93m%s\x1b[0m" % (share_rawtype))

Displays information about the server and optionally the shares.

This method prints detailed information about the server's characteristics such as NetBIOS names, DNS details, OS information, and SMB capabilities. If the share parameter is set to True and a share is currently set, it will also attempt to display information about the share.

Parameters: share (bool): If True, display information about the current share. server (bool): If True, display information about the server.

Returns: None

def list_contents(self, path=None): View Source

431    def list_contents(self, path=None):
432        """
433        Lists the contents of a specified directory on the SMB share.
434
435        This method retrieves the contents of a directory specified by `shareName` and `path`. If `shareName` or `path`
436        is not provided, it defaults to the instance's current SMB share or path. The method returns a dictionary with
437        the long names of the files and directories as keys and their respective SMB entry objects as values.
438
439        Args:
440            shareName (str, optional): The name of the SMB share. Defaults to the current SMB share if None.
441            path (str, optional): The directory path to list contents from. Defaults to the current path if None.
442
443        Returns:
444            dict: A dictionary with file and directory names as keys and their SMB entry objects as values.
445        """
446        
447        if path is None or len(path) == 0:
448            path = self.smb_cwd
449        path = path.rstrip(ntpath.sep) + ntpath.sep + "*"
450
451        contents = {}
452        entries = self.smbClient.listPath(
453            shareName=self.smb_share, 
454            path=path
455        )
456        for entry in entries:
457            contents[entry.get_longname()] = entry
458
459        return contents

Lists the contents of a specified directory on the SMB share.

This method retrieves the contents of a directory specified by shareName and path. If shareName or path is not provided, it defaults to the instance's current SMB share or path. The method returns a dictionary with the long names of the files and directories as keys and their respective SMB entry objects as values.

Args: shareName (str, optional): The name of the SMB share. Defaults to the current SMB share if None. path (str, optional): The directory path to list contents from. Defaults to the current path if None.

Returns: dict: A dictionary with file and directory names as keys and their SMB entry objects as values.

def list_shares(self): View Source

461    def list_shares(self):
462        """
463        Lists all the shares available on the connected SMB server.
464
465        This method queries the SMB server to retrieve a list of all available shares. It populates the `shares` dictionary
466        with key-value pairs where the key is the share name and the value is a dictionary containing details about the share
467        such as its name, type, raw type, and any comments associated with the share.
468
469        Returns:
470            dict: A dictionary containing information about each share available on the server.
471        """
472
473        self.available_shares = {}
474
475        if self.connected:
476            if self.smbClient is not None:
477                resp = self.smbClient.listShares()
478
479                for share in resp:
480                    # SHARE_INFO_1 structure (lmshare.h)
481                    # https://learn.microsoft.com/en-us/windows/win32/api/lmshare/ns-lmshare-share_info_1
482                    sharename = share["shi1_netname"][:-1]
483                    sharecomment = share["shi1_remark"][:-1]
484                    sharetype = share["shi1_type"]
485
486                    self.available_shares[sharename.lower()] = {
487                        "name": sharename, 
488                        "type": STYPE_MASK(sharetype), 
489                        "rawtype": sharetype, 
490                        "comment": sharecomment
491                    }
492            else:
493                print("[!] Error: SMBSession.smbClient is None.")
494
495        return self.available_shares

Lists all the shares available on the connected SMB server.

This method queries the SMB server to retrieve a list of all available shares. It populates the shares dictionary with key-value pairs where the key is the share name and the value is a dictionary containing details about the share such as its name, type, raw type, and any comments associated with the share.

Returns: dict: A dictionary containing information about each share available on the server.

def mkdir(self, path=None): View Source

497    def mkdir(self, path=None):
498        """
499        Creates a directory at the specified path on the SMB share.
500
501        This method takes a path and attempts to create the directory structure on the SMB share. If the path includes
502        nested directories, it will create each directory in the sequence. If a directory already exists, it will skip
503        the creation for that directory without raising an error.
504
505        Args:
506            path (str, optional): The full path of the directory to create on the SMB share. Defaults to None.
507
508        Note:
509            The path should use forward slashes ('/') which will be converted to backslashes (ntpath.sep) for SMB compatibility.
510        """
511
512        if path is not None:
513            # Prepare path
514            path = path.replace('/',ntpath.sep)
515            if ntpath.sep in path:
516                path = path.strip(ntpath.sep).split(ntpath.sep)
517            else:
518                path = [path]
519
520            # Create each dir in the path
521            for depth in range(1, len(path)+1):
522                tmp_path = ntpath.sep.join(path[:depth])
523                try:
524                    self.smbClient.createDirectory(
525                        shareName=self.smb_share, 
526                        pathName=ntpath.normpath(self.smb_cwd + ntpath.sep + tmp_path + ntpath.sep)
527                    )
528                except impacket.smbconnection.SessionError as err:
529                    if err.getErrorCode() == 0xc0000035:
530                        # STATUS_OBJECT_NAME_COLLISION
531                        # Remote directory already created, this is normal
532                        # Src: https://github.com/fortra/impacket/blob/269ce69872f0e8f2188a80addb0c39fedfa6dcb8/impacket/nt_errors.py#L268C9-L268C19
533                        pass
534                    else:
535                        print("[!] Failed to create directory '%s': %s" % (tmp_path, err))
536                        if self.config.debug:
537                            traceback.print_exc()
538        else:
539            pass

Creates a directory at the specified path on the SMB share.

This method takes a path and attempts to create the directory structure on the SMB share. If the path includes nested directories, it will create each directory in the sequence. If a directory already exists, it will skip the creation for that directory without raising an error.

Args: path (str, optional): The full path of the directory to create on the SMB share. Defaults to None.

Note: The path should use forward slashes ('/') which will be converted to backslashes (ntpath.sep) for SMB compatibility.

def path_exists(self, path=None): View Source

541    def path_exists(self, path=None):
542        """
543        Checks if the specified path exists on the SMB share.
544
545        This method determines if a given path exists on the SMB share by attempting to list the contents of the path.
546        If the path listing is successful and returns one or more entries, the path is considered to exist.
547
548        Args:
549            path (str, optional): The path to check on the SMB share. Defaults to None.
550
551        Returns:
552            bool: True if the path exists, False otherwise or if an error occurs.
553        """
554
555        if path is not None:
556            path = path.replace('*','')
557            try:
558                contents = self.smbClient.listPath(
559                    shareName=self.smb_share,
560                    path=ntpath.normpath(self.smb_cwd + ntpath.sep + path + ntpath.sep)
561                )
562                return (len(contents) != 0)
563            except Exception as e:
564                return False
565        else:
566            return False

Checks if the specified path exists on the SMB share.

This method determines if a given path exists on the SMB share by attempting to list the contents of the path. If the path listing is successful and returns one or more entries, the path is considered to exist.

Args: path (str, optional): The path to check on the SMB share. Defaults to None.

Returns: bool: True if the path exists, False otherwise or if an error occurs.

def path_isdir(self, pathFromRoot=None): View Source

568    def path_isdir(self, pathFromRoot=None):
569        """
570        Checks if the specified path is a directory on the SMB share.
571
572        This method determines if a given path corresponds to a directory on the SMB share. It does this by listing the
573        contents of the path and filtering for entries that match the basename of the path and are marked as directories.
574
575        Args:
576            path (str, optional): The path to check on the SMB share. Defaults to None.
577
578        Returns:
579            bool: True if the path is a directory, False otherwise or if an error occurs.
580        """
581
582        if pathFromRoot is not None:
583            # Replace slashes if any
584            path = pathFromRoot.replace('/', ntpath.sep)
585            
586            # Strip wildcards to avoid injections
587            path = path.replace('*','')
588
589            # Normalize path and strip leading backslash
590            path = ntpath.normpath(path + ntpath.sep).lstrip(ntpath.sep)
591
592            if path.strip() in ['', '.', '..']:
593                # By defininition they exist on the filesystem
594                return True
595            else:
596                try:
597                    contents = self.smbClient.listPath(
598                        shareName=self.smb_share,
599                        path=path+'*'
600                    )
601                    # Filter on directories
602                    contents = [
603                        c for c in contents
604                        if c.get_longname() == ntpath.basename(path) and c.is_directory()
605                    ]
606                    return (len(contents) != 0)
607                except Exception as e:
608                    return False
609        else:
610            return False

Checks if the specified path is a directory on the SMB share.

This method determines if a given path corresponds to a directory on the SMB share. It does this by listing the contents of the path and filtering for entries that match the basename of the path and are marked as directories.

Args: path (str, optional): The path to check on the SMB share. Defaults to None.

Returns: bool: True if the path is a directory, False otherwise or if an error occurs.

def path_isfile(self, path=None): View Source

612    def path_isfile(self, path=None):
613        """
614        Checks if the specified path is a file on the SMB share.
615
616        This method determines if a given path corresponds to a file on the SMB share. It does this by listing the
617        contents of the path and filtering for entries that match the basename of the path and are not marked as directories.
618
619        Args:
620            path (str, optional): The path to check on the SMB share. Defaults to None.
621
622        Returns:
623            bool: True if the path is a file, False otherwise or if an error occurs.
624        """
625
626        if path is not None:
627            path = path.replace('*','')
628            search_dir = ntpath.normpath(self.smb_cwd + ntpath.sep + path)
629            search_dir = ntpath.dirname(search_dir) + ntpath.sep + '*'
630            try:
631                contents = self.smbClient.listPath(
632                    shareName=self.smb_share,
633                    path=search_dir
634                )
635                # Filter on files
636                contents = [
637                    c for c in contents
638                    if c.get_longname() == ntpath.basename(path) and not c.is_directory()
639                ]
640                return (len(contents) != 0)
641            except Exception as e:
642                return False
643        else:
644            return False

Checks if the specified path is a file on the SMB share.

This method determines if a given path corresponds to a file on the SMB share. It does this by listing the contents of the path and filtering for entries that match the basename of the path and are not marked as directories.

Args: path (str, optional): The path to check on the SMB share. Defaults to None.

Returns: bool: True if the path is a file, False otherwise or if an error occurs.

def ping_smb_session(self): View Source

646    def ping_smb_session(self):
647        """
648        Tests the connectivity to the SMB server by sending an echo command.
649
650        This method attempts to send an echo command to the SMB server to check if the session is still active.
651        It updates the `connected` attribute of the class based on the success or failure of the echo command.
652
653        Returns:
654            bool: True if the echo command succeeds (indicating the session is active), False otherwise.
655        """
656
657        try:
658            self.smbClient.getSMBServer().echo()
659        except Exception as e:
660            self.connected = False
661        return self.connected

Tests the connectivity to the SMB server by sending an echo command.

This method attempts to send an echo command to the SMB server to check if the session is still active. It updates the connected attribute of the class based on the success or failure of the echo command.

Returns: bool: True if the echo command succeeds (indicating the session is active), False otherwise.

def put_file(self, localpath=None): View Source

663    def put_file(self, localpath=None):
664        """
665        Uploads a single file to the SMB share.
666
667        This method takes a local file path, opens the file, and uploads it to the SMB share at the specified path.
668        It handles exceptions such as broken pipe errors or keyboard interrupts by closing and reinitializing the SMB session.
669        General exceptions are caught and logged, with a traceback provided if debugging is enabled.
670
671        Args:
672            localpath (str, optional): The local file path of the file to be uploaded. Defaults to None.
673        """
674
675        if os.path.exists(localpath):
676            if os.path.isfile(localpath):
677                try:
678                    localfile = os.path.basename(localpath)
679                    f = LocalFileIO(
680                        mode="rb", 
681                        path=localpath, 
682                        debug=self.config.debug
683                    )
684                    self.smbClient.putFile(
685                        shareName=self.smb_share, 
686                        pathName=ntpath.normpath(self.smb_cwd + ntpath.sep + localfile + ntpath.sep), 
687                        callback=f.read
688                    )
689                    f.close()
690                except (BrokenPipeError, KeyboardInterrupt) as err:
691                    print("[!] Interrupted.")
692                    self.close_smb_session()
693                    self.init_smb_session()
694                except Exception as err:
695                    print("[!] Failed to upload '%s': %s" % (localfile, err))
696                    if self.config.debug:
697                        traceback.print_exc()
698            else:
699                print("[!] The specified localpath is a directory. Use 'put -r <directory>' instead.")
700        else:
701            print("[!] The specified localpath does not exist.")

Uploads a single file to the SMB share.

This method takes a local file path, opens the file, and uploads it to the SMB share at the specified path. It handles exceptions such as broken pipe errors or keyboard interrupts by closing and reinitializing the SMB session. General exceptions are caught and logged, with a traceback provided if debugging is enabled.

Args: localpath (str, optional): The local file path of the file to be uploaded. Defaults to None.

def put_file_recursively(self, localpath=None): View Source

703    def put_file_recursively(self, localpath=None):
704        """
705        Recursively uploads files from a specified local directory to the SMB share.
706
707        This method walks through the given local directory and all its subdirectories, uploading each file to the
708        corresponding directory structure on the SMB share. It first checks if the local path is a directory. If it is,
709        it iterates over all files and directories within the local path, creating necessary directories on the SMB share
710        and uploading files. If the local path is not a directory, it prints an error message.
711
712        Args:
713            localpath (str, optional): The local directory path from which files will be uploaded. Defaults to None.
714        """
715
716        if os.path.exists(localpath):
717            if os.path.isfile(localpath):
718                # Iterate over all files and directories within the local path
719                local_files = {}
720                for root, dirs, files in os.walk(localpath):
721                    if len(files) != 0:
722                        local_files[root] = files
723
724                # Iterate over the found files
725                for local_dir_path in sorted(local_files.keys()):
726                    print("[>] Putting files of '%s'" % local_dir_path)
727
728                    # Create remote directory
729                    remote_dir_path = local_dir_path.replace(os.path.sep, ntpath.sep)
730                    self.mkdir(
731                        path=ntpath.normpath(self.smb_cwd + ntpath.sep + remote_dir_path + ntpath.sep)
732                    )
733
734                    for local_file_path in local_files[local_dir_path]:
735                        try:
736                            f = LocalFileIO(
737                                mode="rb", 
738                                path=local_dir_path + os.path.sep + local_file_path, 
739                                debug=self.config.debug
740                            )
741                            self.smbClient.putFile(
742                                shareName=self.smb_share, 
743                                pathName=ntpath.normpath(self.smb_cwd + ntpath.sep + remote_dir_path + ntpath.sep + local_file_path), 
744                                callback=f.read
745                            )
746                            f.close()
747
748                        except BrokenPipeError as err:
749                            f.set_error(message="[bold red]Failed uploading '%s': %s" % (f.path, err))
750                            f.close(remove=True)
751                            break
752                        except Exception as err:
753                            f.set_error(message="[bold red]Failed uploading '%s': %s" % (f.path, err))
754                            f.close(remove=True)
755                else:
756                    print("[!] The specified localpath is a file. Use 'put <file>' instead.")
757        else:
758            print("[!] The specified localpath does not exist.")

Recursively uploads files from a specified local directory to the SMB share.

This method walks through the given local directory and all its subdirectories, uploading each file to the corresponding directory structure on the SMB share. It first checks if the local path is a directory. If it is, it iterates over all files and directories within the local path, creating necessary directories on the SMB share and uploading files. If the local path is not a directory, it prints an error message.

Args: localpath (str, optional): The local directory path from which files will be uploaded. Defaults to None.

def rmdir(self, path=None): View Source

760    def rmdir(self, path=None):
761        """
762        Removes a directory from the SMB share at the specified path.
763
764        This method attempts to delete a directory located at the given path on the SMB share. If the operation fails,
765        it prints an error message indicating the failure and the reason. If debugging is enabled, it also prints
766        the stack trace of the exception.
767
768        Args:
769            path (str, optional): The path of the directory to be removed on the SMB share. Defaults to None.
770        """
771        try:
772            self.smbClient.deleteDirectory(
773                shareName=self.smb_share, 
774                pathName=ntpath.normpath(self.smb_cwd + ntpath.sep + path), 
775            )
776        except Exception as err:
777            print("[!] Failed to remove directory '%s': %s" % (path, err))
778            if self.config.debug:
779                traceback.print_exc()

Removes a directory from the SMB share at the specified path.

This method attempts to delete a directory located at the given path on the SMB share. If the operation fails, it prints an error message indicating the failure and the reason. If debugging is enabled, it also prints the stack trace of the exception.

Args: path (str, optional): The path of the directory to be removed on the SMB share. Defaults to None.

def rm(self, path=None): View Source

781    def rm(self, path=None):
782        """
783        Removes a file from the SMB share at the specified path.
784
785        This method attempts to delete a file located at the given path on the SMB share. If the operation fails,
786        it prints an error message indicating the failure and the reason. If debugging is enabled, it also prints
787        the stack trace of the exception.
788
789        Args:
790            path (str, optional): The path of the file to be removed on the SMB share. Defaults to None.
791        """
792        try:
793            self.smbClient.deleteFile(
794                shareName=self.smb_share, 
795                pathName=ntpath.normpath(self.smb_cwd + ntpath.sep + path), 
796            )
797        except Exception as err:
798            print("[!] Failed to remove file '%s': %s" % (path, err))
799            if self.config.debug:
800                traceback.print_exc()

Removes a file from the SMB share at the specified path.

This method attempts to delete a file located at the given path on the SMB share. If the operation fails, it prints an error message indicating the failure and the reason. If debugging is enabled, it also prints the stack trace of the exception.

Args: path (str, optional): The path of the file to be removed on the SMB share. Defaults to None.

def tree(self, path=None): View Source

802    def tree(self, path=None):
803        """
804        Recursively lists the directory structure of the SMB share starting from the specified path.
805
806        This function prints a visual representation of the directory tree of the remote SMB share. It uses
807        recursion to navigate through directories and lists all files and subdirectories in each directory.
808        The output is color-coded and formatted to enhance readability, with directories highlighted in cyan.
809
810        Args:
811            path (str, optional): The starting path on the SMB share from which to begin listing the tree.
812                                  Defaults to the root of the current share.
813        """
814        
815        def recurse_action(base_dir="", path=[], prompt=[]):
816            bars = ["│   ", "├── ", "└── "]
817
818            remote_smb_path = ntpath.normpath(base_dir + ntpath.sep + ntpath.sep.join(path))
819
820            entries = []
821            try:
822                entries = self.smbClient.listPath(
823                    shareName=self.smb_share, 
824                    path=remote_smb_path+'\\*'
825                )
826            except impacket.smbconnection.SessionError as err:
827                code, const, text = err.getErrorCode(), err.getErrorString()[0], err.getErrorString()[1]
828                errmsg = "Error 0x%08x (%s): %s" % (code, const, text)
829                if self.config.no_colors:
830                    print("%s%s" % (''.join(prompt+[bars[2]]), errmsg))
831                else:
832                    print("%s\x1b[1;91m%s\x1b[0m" % (''.join(prompt+[bars[2]]), errmsg))
833                return 
834
835            entries = [e for e in entries if e.get_longname() not in [".", ".."]]
836            entries = sorted(entries, key=lambda x:x.get_longname())
837
838            # 
839            if len(entries) > 1:
840                index = 0
841                for entry in entries:
842                    index += 1
843                    # This is the first entry 
844                    if index == 0:
845                        if entry.is_directory():
846                            if self.config.no_colors:
847                                print("%s%s\\" % (''.join(prompt+[bars[1]]), entry.get_longname()))
848                            else:
849                                print("%s\x1b[1;96m%s\x1b[0m\\" % (''.join(prompt+[bars[1]]), entry.get_longname()))
850                            recurse_action(
851                                base_dir=base_dir, 
852                                path=path+[entry.get_longname()],
853                                prompt=prompt+["│   "]
854                            )
855                        else:
856                            if self.config.no_colors:
857                                print("%s%s" % (''.join(prompt+[bars[1]]), entry.get_longname()))
858                            else:
859                                print("%s\x1b[1m%s\x1b[0m" % (''.join(prompt+[bars[1]]), entry.get_longname()))
860
861                    # This is the last entry
862                    elif index == len(entries):
863                        if entry.is_directory():
864                            if self.config.no_colors:
865                                print("%s%s\\" % (''.join(prompt+[bars[2]]), entry.get_longname()))
866                            else:
867                                print("%s\x1b[1;96m%s\x1b[0m\\" % (''.join(prompt+[bars[2]]), entry.get_longname()))
868                            recurse_action(
869                                base_dir=base_dir, 
870                                path=path+[entry.get_longname()],
871                                prompt=prompt+["    "]
872                            )
873                        else:
874                            if self.config.no_colors:
875                                print("%s%s" % (''.join(prompt+[bars[2]]), entry.get_longname()))
876                            else:
877                                print("%s\x1b[1m%s\x1b[0m" % (''.join(prompt+[bars[2]]), entry.get_longname()))
878                        
879                    # These are entries in the middle
880                    else:
881                        if entry.is_directory():
882                            if self.config.no_colors:
883                                print("%s%s\\" % (''.join(prompt+[bars[1]]), entry.get_longname()))
884                            else:
885                                print("%s\x1b[1;96m%s\x1b[0m\\" % (''.join(prompt+[bars[1]]), entry.get_longname()))
886                            recurse_action(
887                                base_dir=base_dir, 
888                                path=path+[entry.get_longname()],
889                                prompt=prompt+["│   "]
890                            )
891                        else:
892                            if self.config.no_colors:
893                                print("%s%s" % (''.join(prompt+[bars[1]]), entry.get_longname()))
894                            else:
895                                print("%s\x1b[1m%s\x1b[0m" % (''.join(prompt+[bars[1]]), entry.get_longname()))
896
897            # 
898            elif len(entries) == 1:
899                entry = entries[0]
900                if entry.is_directory():
901                    if self.config.no_colors:
902                        print("%s%s\\" % (''.join(prompt+[bars[2]]), entry.get_longname()))
903                    else:
904                        print("%s\x1b[1;96m%s\x1b[0m\\" % (''.join(prompt+[bars[2]]), entry.get_longname()))
905                    recurse_action(
906                        base_dir=base_dir, 
907                        path=path+[entry.get_longname()],
908                        prompt=prompt+["    "]
909                    )
910                else:
911                    if self.config.no_colors:
912                        print("%s%s" % (''.join(prompt+[bars[2]]), entry.get_longname()))
913                    else:
914                        print("%s\x1b[1m%s\x1b[0m" % (''.join(prompt+[bars[2]]), entry.get_longname()))
915
916        # Entrypoint
917        try:
918            if self.config.no_colors:
919                print("%s\\" % path)
920            else:
921                print("\x1b[1;96m%s\x1b[0m\\" % path)
922            recurse_action(
923                base_dir=self.smb_cwd, 
924                path=[path],
925                prompt=[""]
926            )
927        except (BrokenPipeError, KeyboardInterrupt) as e:
928            print("[!] Interrupted.")
929            self.close_smb_session()
930            self.init_smb_session()

Recursively lists the directory structure of the SMB share starting from the specified path.

This function prints a visual representation of the directory tree of the remote SMB share. It uses recursion to navigate through directories and lists all files and subdirectories in each directory. The output is color-coded and formatted to enhance readability, with directories highlighted in cyan.

Args: path (str, optional): The starting path on the SMB share from which to begin listing the tree. Defaults to the root of the current share.

def set_share(self, shareName): View Source

934    def set_share(self, shareName):
935        """
936        Sets the current SMB share to the specified share name.
937
938        This method updates the SMB session to use the specified share name. It checks if the share name is valid
939        and updates the smb_share attribute of the SMBSession instance.
940
941        Parameters:
942            shareName (str): The name of the share to set as the current SMB share.
943
944        Raises:
945            ValueError: If the shareName is None or an empty string.
946        """
947
948        if shareName is not None:
949            self.list_shares()
950            if shareName.lower() in self.available_shares.keys():
951                # Doing this in order to keep the case of the share adevertised by the remote machine
952                self.smb_share = self.available_shares[shareName.lower()]["name"]
953            else:
954                print("[!] Could not set share '%s', it does not exist remotely." % shareName)

Sets the current SMB share to the specified share name.

This method updates the SMB session to use the specified share name. It checks if the share name is valid and updates the smb_share attribute of the SMBSession instance.

Parameters: shareName (str): The name of the share to set as the current SMB share.

Raises: ValueError: If the shareName is None or an empty string.

def set_cwd(self, path=None): View Source

956    def set_cwd(self, path=None):
957        """
958        Sets the current working directory on the SMB share to the specified path.
959
960        This method updates the current working directory (cwd) of the SMB session to the given path if it is a valid directory.
961        If the specified path is not a directory, the cwd remains unchanged.
962
963        Parameters:
964            path (str): The path to set as the current working directory.
965
966        Raises:
967            ValueError: If the specified path is not a directory.
968        """
969
970        if path is not None:
971            # Set path separators to ntpath sep 
972            if '/' in path:
973                path = path.replace('/', ntpath.sep)
974
975            if path.startswith(ntpath.sep):
976                # Absolute path
977                path = path + ntpath.sep
978            else:
979                # Relative path to the CWD
980                if len(self.smb_cwd) == 0:
981                    path = path + ntpath.sep
982                else:
983                    path = self.smb_cwd + ntpath.sep + path
984            
985            # Path normalization
986            path = ntpath.normpath(path)
987            path = re.sub(r'\\+', r'\\', path)
988
989            if path in ["", ".", ".."]:
990                self.smb_cwd = ""
991            else:
992                if self.path_isdir(pathFromRoot=path.strip(ntpath.sep)):
993                    # Path exists on the remote 
994                    self.smb_cwd = ntpath.normpath(path)
995                else:
996                    # Path does not exists or is not a directory on the remote 
997                    print("[!] Remote directory '%s' does not exist." % path)

Sets the current working directory on the SMB share to the specified path.

This method updates the current working directory (cwd) of the SMB session to the given path if it is a valid directory. If the specified path is not a directory, the cwd remains unchanged.

Parameters: path (str): The path to set as the current working directory.

Raises: ValueError: If the specified path is not a directory.