Merge branch 'release-v0.5.0'

.github/workflows/publish.yml

@@ -19,16 +19,31 @@ jobs:
         uses: actions/setup-python@v2
         with:
           python-version: "3.9"
-      - name: Install pwncat Module
-        run: "python setup.py install"
+      - name: Installing Python Poetry
+        run: pip install poetry
+      - name: Install and Build pwncat-cs Package
+        run: |
+          poetry install
+          poetry build
+      - name: Publish Package to TestPyPi
+        run: |
+          # Test that package publishing is going to work with the testpypi
+          # instance first before trying to package plugins.
+          poetry config pypi-token.testpypi ${{ secrets.TEST_PYPI_TOKEN }}
+          poetry config repositories.testpypi https://test.pypi.org/legacy/
+          poetry publish --repository testpypi
       - name: Download and Archive Plugins
         run: |
           # Have pwncat download all plugins needed
-          pwncat --download-plugins
+          poetry run pwncat-cs --download-plugins
 
           # They are stored in ~/.local/share/pwncat by default
           tar czvf pwncat-plugins.tar.gz --transform='s|.*pwncat/||' ~/.local/share/pwncat/*
-
+      - name: Publish Package to PyPi
+        run: |
+          # Everything looks good, publish to pypi
+          poetry config pypi-token.pypi ${{ secrets.PYPI_TOKEN }}
+          poetry publish
       - name: Extract Release Body
         run: |
           # Grab tag name without the `v`

CHANGELOG.md

@@ -7,7 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 The Changelog starts with v0.4.1, because we did not keep one before that,
 and simply didn't have the time to go back and retroactively create one.
 
-## [Unreleased]
+## [v0.5.0] - 2021-11-28
+This is a major release mainly due to the name change, and PyPI package addition.
+The package has been renamed to `pwncat-cs` and the default entrypoint has also
+been renamed to `pwncat-cs`. These changes were made in an effort to deconflict
+with [Cytopia pwncat](https://pwncat.org/). Beyond that, some new features were
+added as seen in the release notes below.
+
+I've tried to update all references to the old `pwncat` entrypoint, but may have
+missed some throughout the documentation or code. Please open an issue if you
+notice any old references to the previous name.
+
+It's worth noting that the internal module name is still `pwncat`, as Cytopia
+does not implement an importable package (only a command line entrypoint). I may
+change this name in the future, but for now it doesn't cause any issues and would
+require a major refactor so I'm going to leave it.
+
+### Changed
+- Moved dependency management and building to [Poetry](https://python-poetry.org).
+- Changed package name to `pwncat-cs` in order to not conflict w/ cytopia/pwncat.
+### Added
+- Added `ssl-bind` and `ssl-connect` channel protocols for encrypted shells
+- Added `ncat`-style ssl arguments to entrypoint and `connect` command
+- Added query-string arguments to connection strings for both the entrypoint
+  and the `connect` command.
+- Added Enumeration States to allow session-bound enumerations
+- Added PyPi publishing to GitHub `publish` workflow.
+- Added licensing for pwncat (MIT)
+- Added background listener API and commands ([#43](https://github.com/calebstewart/pwncat/issues/43))
+- Added Windows privilege escalation via BadPotato plugin ([#106](https://github.com/calebstewart/pwncat/issues/106))
+### Removed
+- Removed `setup.py` and `requirements.txt`
 
 ## [0.4.4] - 2021-11-28
 

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Caleb Stewart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -27,7 +27,7 @@ for working with remote shells.
 `pwncat` knows how to spawn pty's with a few different methods and will
 cross-reference the methods with the executables previously enumerated. After
 spawning a pty, it will setup the controlling terminal in raw mode, so you can
-interact in a similar fashion to `ssh`. 
+interact in a similar fashion to `ssh`.
 
 `pwncat` will also synchronize the remote pty settings (such as rows, columns,
 `TERM` environment variable) with your local settings to ensure the shell
@@ -43,6 +43,48 @@ the latest usage and development documentation!
 
 **pwncat requires Python 3.9+ on Linux**
 
+## Naming Changes
+
+Due to the naming conflict with [Cytopia's pwncat](https://pwncat.org/), I have
+decided to rename the package to `pwncat-cs`. This includes renaming the
+entrypoint so that there are no direct conflicts with Cytopia's project. If you
+are updating from `v0.4.*`, the command name will now have changed, and the `pcat`
+and `pc` varianst have been removed. See the most recent release notes for more
+details.
+
+The added benefit of this move is that the project is now pushed to PyPI for
+easier installation/updating in the future.
+
+## Installation
+
+pwncat is available on PyPI as `pwncat-cs`. It exposes an entrypoints named
+`pwncat`, `pcat` and `pc`. It **does** conflict with the `pwncat` package,
+so if you need both, we recommend using a virtual environment. pwncat also
+exposes an importable module named `pwncat` with full access to the internals
+and automation. You can install from PyPi like so:
+
+``` shell
+pip install pwncat-cs
+```
+
+pwncat uses [poetry](https://python-poetry.org) for dependency and build
+management. For a development environment, install poetry as described on their
+website, and then use it to manage your environment:
+
+``` shell
+# Clone the repo
+git clone https://github.com/calebstewart/pwncat
+cd pwncat
+# Enter/create the pwncat specific virtual environment
+poetry shell
+# Install dependencies
+poetry install
+# Use pwncat
+pwncat --help
+# Use `exit` to leave the virtual environment
+exit
+```
+
 ## Windows Support
 
 `pwncat` now supports connections from Windows targets starting at `v0.4.0a1`. The Windows
@@ -67,21 +109,6 @@ the only provided default plugins are the C2 and an implementation of [BadPotato
 pwncat can reflectively load .Net binaries to be used a plugins for the C2.
 For more information on Windows C2 plugins, please see the [documentation].
 
-## Version Details
-
-Currently, there are two versions of pwncat available. The last stable
-version is `v0.3.1`. There is a tagged commit for that version. It does
-not support multiple platforms or multi-session interaction. The
-documentation for that version is still available on Read the Docs as
-the `stable` version.
-
-The current `master` branch is `v0.4.3`. This version has
-overhauled a lot of the framework to support multiple platforms and 
-multi-session environments. Documentation for this version is available
-in the `latest` version on Read the Docs.
-
-**v0.3.1 will not be updated further**
-
 ## Modules
 
 Recently, the architecture of the pwncat framework was redesigned to
@@ -98,38 +125,36 @@ Refer to the documentation for more information.
 In order to install some of the packages required with `pip`, you will likely need
 your distribution's "Python Development" package. On Debian based systems,
 this is `python-dev`. For Arch, the development files are shipped with the
-main Python repository. For Enterprise Linux, the package is named 
+main Python repository. For Enterprise Linux, the package is named
 `python-devel`.
 
-`pwncat` is configured as a standard python package with `distutils`. You
-can install `pwncat` directly from GitHub with:
-
-```shell script
-pip install git+https://github.com/calebstewart/pwncat.git
-```
-
-Or, you can install after cloning the repository with:
+`pwncat` is pushed to PyPI under the name `pwncat-cs`, and can be installed with
+`pip` like so:
 
-```shell script
-python setup.py install
+``` shell
+pip install pwncat-cs
 ```
 
-It is recommended to install pwncat from a virtual environment.
+However, it is recommended to install pwncat from a virtual environment.
 
 ```shell script
 python3 -m venv pwncat-env
 source pwncat-env/bin/activate
-python setup.py install
+pip install pwncat-cs
 ```
 
-If you would like to develop custom privilege escalation or persistence
-modules, we recommend you use the `develop` target vice the `install` target
-for `setup.py`. This allows changes to the local repository to immediately
-be observed with your installed package.
+For a development environment, `pwncat` usage Python Poetry. You can clone the
+repository locally and use poetry to setup a development environment.
 
-The setup script will install three binaries. They are all identical, but
-provide convenience aliases for pwncat. The three binaries are: `pwncat`,
-`pc` and `pcat`.
+``` shell
+# Setup pwncat inside a poetry-managed virtual environment
+git clone [email protected]:calebstewart/pwncat.git
+cd pwncat
+poetry install
+
+# Enter the virtual environment
+poetry shell
+```
 
 ## BlackArch Packaging
 
@@ -141,51 +166,52 @@ Installation on BlackArch is as simple as:
 pacman -Syu pwncat-caleb
 ```
 
+>>>>>>> master
 ### Connecting to a Victim
 
-The command line parameters for pwncat attempt to be flexible and accept 
+The command line parameters for pwncat attempt to be flexible and accept
 a variety of common connection syntax. Specifically, it will try to accept
 common netcat and ssh like syntax. The following are all valid:
 
 ```sh
 # Connect to a bind shell
-pwncat connect://10.10.10.10:4444
-pwncat 10.10.10.10:4444
-pwncat 10.10.10.10 4444
+pwncat-cs connect://10.10.10.10:4444
+pwncat-cs 10.10.10.10:4444
+pwncat-cs 10.10.10.10 4444
 # Listen for reverse shell
-pwncat bind://0.0.0.0:4444
-pwncat 0.0.0.0:4444
-pwncat :4444
-pwncat -lp 4444
+pwncat-cs bind://0.0.0.0:4444
+pwncat-cs 0.0.0.0:4444
+pwncat-cs :4444
+pwncat-cs -lp 4444
 # Connect via ssh
-pwncat ssh://user:[email protected]
-pwncat [email protected]
-pwncat user:[email protected]
-pwncat -i id_rsa [email protected]
+pwncat-cs ssh://user:[email protected]
+pwncat-cs [email protected]
+pwncat-cs user:[email protected]
+pwncat-cs -i id_rsa [email protected]
 # SSH w/ non-standard port
-pwncat -p 2222 [email protected]
-pwncat [email protected]:2222
+pwncat-cs -p 2222 [email protected]
+pwncat-cs [email protected]:2222
 # Reconnect utilizing installed persistence
 #   If reconnection fails and no protocol is specified,
 #   SSH is used as a fallback.
-pwncat reconnect://[email protected]
-pwncat reconnect://user@c228fc49e515628a0c13bdc4759a12bf
-pwncat [email protected]
-pwncat c228fc49e515628a0c13bdc4759a12bf
-pwncat 10.10.10.10
+pwncat-cs reconnect://[email protected]
+pwncat-cs reconnect://user@c228fc49e515628a0c13bdc4759a12bf
+pwncat-cs [email protected]
+pwncat-cs c228fc49e515628a0c13bdc4759a12bf
+pwncat-cs 10.10.10.10
 ```
 
 By default, pwncat **assumes the target platform is Linux**. In order to
 connect to a Windows reverse or bind shell, you must pass the `--platform/-m`
 argument:
 
 ``` shell
-pwncat -m windows 10.10.10.10 4444
-pwncat -m windows -lp 4444
+pwncat-cs -m windows 10.10.10.10 4444
+pwncat-cs -m windows -lp 4444
 ```
 
-For more information on the syntax and argument handling, see the 
-help information with ``pwncat --help`` or visit the [documentation].
+For more information on the syntax and argument handling, see the
+help information with ``pwncat-cs --help`` or visit the [documentation].
 
 ## Docker Image
 
@@ -215,7 +241,7 @@ exposed through any mounted directories.
 ## Features and Functionality
 
 `pwncat` provides two main features. At it's core, it's goal is to automatically
-setup a remote PseudoTerminal (pty) which allows interaction with the remote 
+setup a remote PseudoTerminal (pty) which allows interaction with the remote
 host much like a full SSH session. When operating in a pty, you can use common
 features of your remote shell such as history, line editing, and graphical
 terminal applications.
@@ -254,16 +280,16 @@ more features will be added.
 
 ## Known Issues
 
-Because `pwncat` is trying to abstractly interact with any shell with minimal remote system 
+Because `pwncat` is trying to abstractly interact with any shell with minimal remote system
 dependencies, there are some edge cases we have found. Where we find them, we do
 everything we can to account for them and hide them from the user. However, some have
 slipped through the cracks and been observed in the wild. When this happens, `pwncat`
-will do whatever it can to preserve your terminal, but you may be greeted with some 
-peculiar output or command failures. 
+will do whatever it can to preserve your terminal, but you may be greeted with some
+peculiar output or command failures.
 
 ### BSD Support
 
-While BSD is a Unix-based kernel, in practice it's userland tools are noticeably 
+While BSD is a Unix-based kernel, in practice it's userland tools are noticeably
 different from their Linux counterparts. Due to this, many of the automated
 features of `pwncat` will not work or outright fail when running against a BSD
 based target. I have tried to catch all errors or edge cases, however there are

docs/source/api/pwncat.facts.rst

@@ -13,7 +13,6 @@ Modules and Packages
    :maxdepth: -1
 
    pwncat.facts.ability
-   pwncat.facts.escalate
    pwncat.facts.implant
    pwncat.facts.linux
    pwncat.facts.tamper

docs/source/commands/index.rst

@@ -12,6 +12,8 @@ Command index
     escalate.rst
     lcd.rst
     load.rst
+    listen.rst
+    listeners.rst
     lpwd.rst
     run.rst
     info.rst

docs/source/commands/listen.rst

@@ -0,0 +1,21 @@
+Listen
+======
+
+Create a new background listener to asynchronously establish sessions via a reverse shell payload. Background listeners can operate in two different modes: with a platform and without. If a platform type is not specified when creating a listener, channels will be queued within the listener until you initialize them with the ``listeners`` command.
+
+Using the ``--drop-duplicate`` option will cause pwncat to drop any new sessions which duplicate both the target host and user of an existing session. This could be useful when using an infinite reverse shell implant.
+
+Currently, listeners can only be used with the ``socket`` protocol, however listeners are capable of wrapping the socket server in an SSL context. A background listener can effectively replace the ``bind://`` and ``ssl-bind://`` protocols.
+
+The ``--count`` option can be used to restrict background listeners to a set number of active sessions. After reaching the number specified by ``--count``, the listener will automatically be stopped.
+
+.. code-block:: bash
+
+    # Create a basic listener for linux sessions on port 9999
+    listen -m linux 9999
+    # Create an SSL listener for linux sessions on port 6666
+    listen -m linux --ssl 9999
+    # Create a listener with no platform which caches channels until initialization
+    listen 8888
+    # Create a listener which automatically exits after 4 established sessions
+    listen --count 4 --platform windows 5555