Repository files navigation

pwncat is a post-exploitation platformfor Linux targets. It started out as awrapper around basic bind and reverse shells and has grown from there. Itstreamlines common red team operations while staging code from your attackermachine, not the target.

pwncat used to only support Linux, but there has been a lot of work recentlyto support multiple platforms. Currently, there is alpha support for Windowstargets. Please see the latestdocumentation for details on how to usepwncat with a Windows target.

pwncat intercepts the raw communication with a remote shell and allows theuser to perform automated actions on the remote host including enumeration,implant installation and even privilege escalation.

After receiving a connection, pwncat will setup some common configurationsfor working with remote shells.

• Disable history in the remote shell
• Normalize shell prompt
• Locate useful binaries (usingwhich)
• Attempt to spawn a pseudo-terminal (pty) for a full interactive session

pwncat knows how to spawn pty's with a few different methods and willcross-reference the methods with the executables previously enumerated. Afterspawning a pty, it will setup the controlling terminal in raw mode, so you caninteract in a similar fashion tossh.

pwncat will also synchronize the remote pty settings (such as rows, columns,TERM environment variable) with your local settings to ensure the shellbehaves correctly with interactive applications such asvim ornano.

John Hammond and I presentedpwncat at GRIMMCon. Our presentation, whichcan be found on YouTubehere.This video demonstrates an early version of the API and interface. Pleaserefer to the documentation for up to date usage and API documentation!

pwncatdocumentation is being built out on Read the Docs. Head there forthe latest usage and development documentation!

pwncat requires Python 3.9+ on Linux

pwncat only depends on a working Python development environment running on Linux.In order to install some of the packages required withpip, you will likely needyour distribution's "Python Development" package. On Debian based systems,this ispython-dev. For Arch, the development files are shipped with themain Python repository. For Enterprise Linux, the package is namedpython-devel.

pwncat is pushed to PyPI under the namepwncat-cs, and can be installed withpip like so:

pip install pwncat-cs

However, it is recommended to install pwncat from a virtual environment.

python3 -m venv pwncat-envsource pwncat-env/bin/activatepip install pwncat-cs

For a development environment,pwncat usage Python Poetry. You can clone therepository locally and use poetry to setup a development environment.

# Setup pwncat inside a poetry-managed virtual environmentgit clone git@github.com:calebstewart/pwncat.gitcd pwncatpoetry install# Enter the virtual environmentpoetry shell

Due to the naming conflict withCytopia's pwncat, I havedecided to rename the package topwncat-cs. This includes renaming theentrypoint so that there are no direct conflicts with Cytopia's project. If youare updating fromv0.4.*, the command name will now have changed, and thepcatandpc varianst have been removed. See the most recent release notes for moredetails.

The added benefit of this move is that the project is now pushed to PyPI foreasier installation/updating in the future.

pwncat now supports connections from Windows targets starting atv0.4.0a1. The Windowsplatform utilizes a .Net-based C2 library which is loaded automatically. Windowstargets should connect with either acmd.exe orpowershell.exe shell, andpwncat will take care of the rest.

The libraries implementing the C2 are implemented atpwncat-windows-c2.The DLLs for the C2 will be automatically downloaded from the targeted releasefor you. If you do not have internet connectivity on your target machine,you can tell pwncat to pre-stage the DLLs using the--download-pluginsargument. If you are running a release version of pwncat, you can also downloada tarball of all built-in plugins from the releases page.

The plugins are stored by default in~/.local/share/pwncat, however this isconfigurable with theplugin_path configuration. If you download the packagedset of plugins from the releases page, you should extract it to the path pointedto byplugin_path.

Aside from the main C2 DLLs, other plugins may also be available. Currently,the only provided default plugins are the C2 and an implementation ofBadPotato.pwncat can reflectively load .Net binaries to be used a plugins for the C2.For more information on Windows C2 plugins, please see thedocumentation.

Recently, the architecture of the pwncat framework was redesigned toincorporate a generic "module" structure. All functionality is nowimplemented as modules. This includes enumeration, persistence andprivilege escalation. Interacting with modules is similar to most otherpost-exploitation platforms. You can utilize the familiarrun,searchandinfo commands and enter module contexts with theuse command.Refer to the documentation for more information.

Installation on BlackArch is as simple as:

pacman -Syu pwncat-caleb

The command line parameters for pwncat attempt to be flexible and accepta variety of common connection syntax. Specifically, it will try to acceptcommon netcat and ssh like syntax. The following are all valid:

# Connect to a bind shellpwncat-cs connect://10.10.10.10:4444pwncat-cs 10.10.10.10:4444pwncat-cs 10.10.10.10 4444# Listen for reverse shellpwncat-cs bind://0.0.0.0:4444pwncat-cs 0.0.0.0:4444pwncat-cs :4444pwncat-cs -lp 4444# Connect via sshpwncat-cs ssh://user:password@10.10.10.10pwncat-cs user@10.10.10.10pwncat-cs user:password@10.10.10.10pwncat-cs -i id_rsa user@10.10.10.10# SSH w/ non-standard portpwncat-cs -p 2222 user@10.10.10.10pwncat-cs user@10.10.10.10:2222# Reconnect utilizing installed persistence#   If reconnection fails and no protocol is specified,#   SSH is used as a fallback.pwncat-cs reconnect://user@10.10.10.10pwncat-cs reconnect://user@c228fc49e515628a0c13bdc4759a12bfpwncat-cs user@10.10.10.10pwncat-cs c228fc49e515628a0c13bdc4759a12bfpwncat-cs 10.10.10.10

By default, pwncatassumes the target platform is Linux. In order toconnect to a Windows reverse or bind shell, you must pass the--platform/-margument:

pwncat-cs -m windows 10.10.10.10 4444pwncat-cs -m windows -lp 4444

For more information on the syntax and argument handling, see thehelp information withpwncat-cs --help or visit thedocumentation.

The recommended installation method is a Python virtual environment. Thisprovides the easiest day-to-day usage ofpwncat. However, there has beeninterest in usingpwncat from a docker image, so I have provided aDockerfile which provides a workingpwncat installation. To build the imageuse:

docker build -t pwncat.

This will build thepwncat docker image with the tag "pwncat". The workingdirectory within the container is/work. The entrypoint for the containeris thepwncat binary. It can be used like so:

# Connect to a bind shell at 10.0.0.1:4444docker run -v"/some/directory":/work -t pwncat 10.0.0.1 4444

In this example, only the files in/some/directory are exposed to the container.Obviously, for upload/download, the container will only be able to see the filesexposed through any mounted directories.

pwncat provides two main features. At it's core, it's goal is to automaticallysetup a remote PseudoTerminal (pty) which allows interaction with the remotehost much like a full SSH session. When operating in a pty, you can use commonfeatures of your remote shell such as history, line editing, and graphicalterminal applications.

The other half ofpwncat is a framework which utilizes your remote shell toperform automated enumeration, persistence and privilege escalation tasks. Thelocalpwncat prompt provides a number of useful features for standardpenetration tests including:

• File upload and download
• Automated privilege escalation enumeration
• Automated privilege escalation execution
• Automated persistence installation/removal
• Automated tracking of modified/created files
  • pwncat also offers the ability to revert these remote "tampers" automatically

The underlying framework for interacting with the remote host aims to abstractaway the underlying shell and connection method as much as possible, allowingcommands and plugins to interact seamlessly with the remote host.

You can learn more about interacting withpwncat and about the underlying frameworkin thedocumentation. If you have an idea for a new privilege escalation methodor persistence method, please take a look at the API documentation specifically.Pull requests are welcome!

pwncat would like to be come a red team swiss army knife. Hopefully soon,more features will be added.

• More privilege escalation methods (sudo -u#-1 CVE, LXD containers, etc.)
• Persistence methods (bind shell, cronjobs, SSH access, PAM abuse, etc.)
• Aggression methods (spam randomness to terminals, flush firewall, etc.)
• Meme methods (terminal-parrot, cowsay, wall, etc.)
• Network methods (port forward, internet access through host, etc.)

Becausepwncat is trying to abstractly interact with any shell with minimal remote systemdependencies, there are some edge cases we have found. Where we find them, we doeverything we can to account for them and hide them from the user. However, some haveslipped through the cracks and been observed in the wild. When this happens,pwncatwill do whatever it can to preserve your terminal, but you may be greeted with somepeculiar output or command failures.

While BSD is a Unix-based kernel, in practice it's userland tools are noticeablydifferent from their Linux counterparts. Due to this, many of the automatedfeatures ofpwncat will not work or outright fail when running against a BSDbased target. I have tried to catch all errors or edge cases, however there arelikely some hiccups which haven't been fully tested against BSD. In any case,the stabilized shell should function within a BSD environment, but I don'tprovide any guarantees.

If I find some time later down the road, I may try to stabilizepwncat on BSD,but for now my focus is on Linux-based distributions. If you'd like tocontribute to makingpwncat behave better on BSD, you are more then welcome toreach out or just fork the repo. As always, pull requests are welcome!