{"id":13642185,"url":"https://github.com/calebstewart/pwncat","last_synced_at":"2025-05-14T06:13:18.546Z","repository":{"id":37477851,"uuid":"261925766","full_name":"calebstewart/pwncat","owner":"calebstewart","description":"Fancy reverse and bind shell handler","archived":false,"fork":false,"pushed_at":"2024-08-09T15:57:48.000Z","size":3713,"stargazers_count":2740,"open_issues_count":66,"forks_count":271,"subscribers_count":60,"default_branch":"master","last_synced_at":"2025-05-09T20:51:12.674Z","etag":null,"topics":["enumeration","implant-deployment","linux","persistance","privilege-escalation","pty","pwncat","windows"],"latest_commit_sha":null,"homepage":"https://pwncat.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/calebstewart.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-07T02:02:40.000Z","updated_at":"2025-05-09T10:52:36.000Z","dependencies_parsed_at":"2024-01-18T13:32:49.363Z","dependency_job_id":"d72ba544-4809-4d95-b187-05a5d7dc9dcf","html_url":"https://github.com/calebstewart/pwncat","commit_stats":{"total_commits":598,"total_committers":16,"mean_commits":37.375,"dds":"0.24749163879598657","last_synced_commit":"37f04d4e16ff47c7fd70e95162f9fccd327cca7e"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calebstewart%2Fpwncat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calebstewart%2Fpwncat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calebstewart%2Fpwncat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calebstewart%2Fpwncat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/calebstewart","download_url":"https://codeload.github.com/calebstewart/pwncat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254081670,"owners_count":22011662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["enumeration","implant-deployment","linux","persistance","privilege-escalation","pty","pwncat","windows"],"created_at":"2024-08-02T01:01:28.275Z","updated_at":"2025-05-14T06:13:18.508Z","avatar_url":"https://github.com/calebstewart.png","language":"Python","funding_links":[],"categories":["Tools","Python"],"sub_categories":["Posts from Hacker101 members on how to get started hacking"],"readme":"# pwncat\n\n[![asciicast](https://asciinema.org/a/417930.svg)](https://asciinema.org/a/417930)\n\npwncat is a post-exploitation platform ~~for Linux targets~~. It started out as a\nwrapper around basic bind and reverse shells and has grown from there. It\nstreamlines common red team operations while staging code from your attacker\nmachine, not the target.\n\npwncat used to only support Linux, but there has been a lot of work recently\nto support multiple platforms. Currently, there is alpha support for Windows\ntargets. Please see the latest [documentation] for details on how to use\npwncat with a Windows target.\n\npwncat intercepts the raw communication with a remote shell and allows the\nuser to perform automated actions on the remote host including enumeration,\nimplant installation and even privilege escalation.\n\nAfter receiving a connection, pwncat will setup some common configurations\nfor working with remote shells.\n\n- Disable history in the remote shell\n- Normalize shell prompt\n- Locate useful binaries (using `which`)\n- Attempt to spawn a pseudo-terminal (pty) for a full interactive session\n\n`pwncat` knows how to spawn pty's with a few different methods and will\ncross-reference the methods with the executables previously enumerated. After\nspawning a pty, it will setup the controlling terminal in raw mode, so you can\ninteract in a similar fashion to `ssh`.\n\n`pwncat` will also synchronize the remote pty settings (such as rows, columns,\n`TERM` environment variable) with your local settings to ensure the shell\nbehaves correctly with interactive applications such as `vim` or `nano`.\n\nJohn Hammond and I presented `pwncat` at GRIMMCon. Our presentation, which\ncan be found on YouTube [here](https://www.youtube.com/watch?v=CISzI9klRkw).\nThis video demonstrates an early version of the API and interface. Please\nrefer to the documentation for up to date usage and API documentation!\n\npwncat [documentation] is being built out on Read the Docs. Head there for\nthe latest usage and development documentation!\n\n**pwncat requires Python 3.9+ on Linux**\n\n## Installation\n\n`pwncat` only depends on a working Python development environment running on Linux.\nIn order to install some of the packages required with `pip`, you will likely need\nyour distribution's \"Python Development\" package. On Debian based systems,\nthis is `python-dev`. For Arch, the development files are shipped with the\nmain Python repository. For Enterprise Linux, the package is named\n`python-devel`.\n\n`pwncat` is pushed to PyPI under the name `pwncat-cs`, and can be installed with\n`pip` like so:\n\n``` shell\npip install pwncat-cs\n```\n\nHowever, it is recommended to install pwncat from a virtual environment.\n\n```shell script\npython3 -m venv pwncat-env\nsource pwncat-env/bin/activate\npip install pwncat-cs\n```\n\nFor a development environment, `pwncat` usage Python Poetry. You can clone the\nrepository locally and use poetry to setup a development environment.\n\n``` shell\n# Setup pwncat inside a poetry-managed virtual environment\ngit clone git@github.com:calebstewart/pwncat.git\ncd pwncat\npoetry install\n\n# Enter the virtual environment\npoetry shell\n```\n\n## Naming Changes\n\nDue to the naming conflict with [Cytopia's pwncat](https://pwncat.org/), I have\ndecided to rename the package to `pwncat-cs`. This includes renaming the\nentrypoint so that there are no direct conflicts with Cytopia's project. If you\nare updating from `v0.4.*`, the command name will now have changed, and the `pcat`\nand `pc` varianst have been removed. See the most recent release notes for more\ndetails.\n\nThe added benefit of this move is that the project is now pushed to PyPI for\neasier installation/updating in the future.\n\n## Windows Support\n\n`pwncat` now supports connections from Windows targets starting at `v0.4.0a1`. The Windows\nplatform utilizes a .Net-based C2 library which is loaded automatically. Windows\ntargets should connect with either a `cmd.exe` or `powershell.exe` shell, and\npwncat will take care of the rest.\n\nThe libraries implementing the C2 are implemented at [pwncat-windows-c2].\nThe DLLs for the C2 will be automatically downloaded from the targeted release\nfor you. If you do not have internet connectivity on your target machine,\nyou can tell pwncat to pre-stage the DLLs using the `--download-plugins`\nargument. If you are running a release version of pwncat, you can also download\na tarball of all built-in plugins from the releases page.\n\nThe plugins are stored by default in `~/.local/share/pwncat`, however this is\nconfigurable with the `plugin_path` configuration. If you download the packaged\nset of plugins from the releases page, you should extract it to the path pointed\nto by `plugin_path`.\n\nAside from the main C2 DLLs, other plugins may also be available. Currently,\nthe only provided default plugins are the C2 and an implementation of [BadPotato].\npwncat can reflectively load .Net binaries to be used a plugins for the C2.\nFor more information on Windows C2 plugins, please see the [documentation].\n\n## Modules\n\nRecently, the architecture of the pwncat framework was redesigned to\nincorporate a generic \"module\" structure. All functionality is now\nimplemented as modules. This includes enumeration, persistence and\nprivilege escalation. Interacting with modules is similar to most other\npost-exploitation platforms. You can utilize the familiar `run`, `search`\nand `info` commands and enter module contexts with the `use` command.\nRefer to the documentation for more information.\n\n## BlackArch Packaging\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/pwncat-caleb.svg)](https://repology.org/project/pwncat-caleb/versions)\n\nInstallation on BlackArch is as simple as:\n\n``` shell\npacman -Syu pwncat-caleb\n```\n\n### Connecting to a Victim\n\nThe command line parameters for pwncat attempt to be flexible and accept\na variety of common connection syntax. Specifically, it will try to accept\ncommon netcat and ssh like syntax. The following are all valid:\n\n```sh\n# Connect to a bind shell\npwncat-cs connect://10.10.10.10:4444\npwncat-cs 10.10.10.10:4444\npwncat-cs 10.10.10.10 4444\n# Listen for reverse shell\npwncat-cs bind://0.0.0.0:4444\npwncat-cs 0.0.0.0:4444\npwncat-cs :4444\npwncat-cs -lp 4444\n# Connect via ssh\npwncat-cs ssh://user:password@10.10.10.10\npwncat-cs user@10.10.10.10\npwncat-cs user:password@10.10.10.10\npwncat-cs -i id_rsa user@10.10.10.10\n# SSH w/ non-standard port\npwncat-cs -p 2222 user@10.10.10.10\npwncat-cs user@10.10.10.10:2222\n# Reconnect utilizing installed persistence\n#   If reconnection fails and no protocol is specified,\n#   SSH is used as a fallback.\npwncat-cs reconnect://user@10.10.10.10\npwncat-cs reconnect://user@c228fc49e515628a0c13bdc4759a12bf\npwncat-cs user@10.10.10.10\npwncat-cs c228fc49e515628a0c13bdc4759a12bf\npwncat-cs 10.10.10.10\n```\n\nBy default, pwncat **assumes the target platform is Linux**. In order to\nconnect to a Windows reverse or bind shell, you must pass the `--platform/-m`\nargument:\n\n``` shell\npwncat-cs -m windows 10.10.10.10 4444\npwncat-cs -m windows -lp 4444\n```\n\nFor more information on the syntax and argument handling, see the\nhelp information with ``pwncat-cs --help`` or visit the [documentation].\n\n## Docker Image\n\nThe recommended installation method is a Python virtual environment. This\nprovides the easiest day-to-day usage of `pwncat`. However, there has been\ninterest in using `pwncat` from a docker image, so I have provided a\nDockerfile which provides a working `pwncat` installation. To build the image\nuse:\n\n``` shell\ndocker build -t pwncat .\n```\n\nThis will build the `pwncat` docker image with the tag \"pwncat\". The working\ndirectory within the container is `/work`. The entrypoint for the container\nis the `pwncat` binary. It can be used like so:\n\n``` shell\n# Connect to a bind shell at 10.0.0.1:4444\ndocker run -v \"/some/directory\":/work -t pwncat 10.0.0.1 4444\n```\n\nIn this example, only the files in `/some/directory` are exposed to the container.\nObviously, for upload/download, the container will only be able to see the files\nexposed through any mounted directories.\n\n## Features and Functionality\n\n`pwncat` provides two main features. At it's core, it's goal is to automatically\nsetup a remote PseudoTerminal (pty) which allows interaction with the remote\nhost much like a full SSH session. When operating in a pty, you can use common\nfeatures of your remote shell such as history, line editing, and graphical\nterminal applications.\n\nThe other half of `pwncat` is a framework which utilizes your remote shell to\nperform automated enumeration, persistence and privilege escalation tasks. The\nlocal `pwncat` prompt provides a number of useful features for standard\npenetration tests including:\n\n* File upload and download\n* Automated privilege escalation enumeration\n* Automated privilege escalation execution\n* Automated persistence installation/removal\n* Automated tracking of modified/created files\n    * `pwncat` also offers the ability to revert these remote \"tampers\" automatically\n\nThe underlying framework for interacting with the remote host aims to abstract\naway the underlying shell and connection method as much as possible, allowing\ncommands and plugins to interact seamlessly with the remote host.\n\nYou can learn more about interacting with `pwncat` and about the underlying framework\nin the [documentation]. If you have an idea for a new privilege escalation method\nor persistence method, please take a look at the API documentation specifically.\nPull requests are welcome!\n\n## Planned Features\n\n**pwncat** would like to be come a red team swiss army knife. Hopefully soon,\nmore features will be added.\n\n* More privilege escalation methods (sudo -u#-1 CVE, LXD containers, etc.)\n* Persistence methods (bind shell, cronjobs, SSH access, PAM abuse, etc.)\n* Aggression methods (spam randomness to terminals, flush firewall, etc.)\n* Meme methods (terminal-parrot, cowsay, wall, etc.)\n* Network methods (port forward, internet access through host, etc.)\n\n## Known Issues\n\nBecause `pwncat` is trying to abstractly interact with any shell with minimal remote system\ndependencies, there are some edge cases we have found. Where we find them, we do\neverything we can to account for them and hide them from the user. However, some have\nslipped through the cracks and been observed in the wild. When this happens, `pwncat`\nwill do whatever it can to preserve your terminal, but you may be greeted with some\npeculiar output or command failures.\n\n### BSD Support\n\nWhile BSD is a Unix-based kernel, in practice it's userland tools are noticeably\ndifferent from their Linux counterparts. Due to this, many of the automated\nfeatures of `pwncat` will not work or outright fail when running against a BSD\nbased target. I have tried to catch all errors or edge cases, however there are\nlikely some hiccups which haven't been fully tested against BSD. In any case,\nthe stabilized shell should function within a BSD environment, but I don't\nprovide any guarantees.\n\nIf I find some time later down the road, I may try to stabilize `pwncat` on BSD,\nbut for now my focus is on Linux-based distributions. If you'd like to\ncontribute to making `pwncat` behave better on BSD, you are more then welcome to\nreach out or just fork the repo. As always, pull requests are welcome!\n\n[documentation]: https://pwncat.readthedocs.io/en/latest\n[pwncat-windows-c2]: https://github.com/calebstewart/pwncat-windows-c2\n[BadPotato]: https://github.com/calebstewart/pwncat-badpotato\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalebstewart%2Fpwncat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcalebstewart%2Fpwncat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalebstewart%2Fpwncat/lists"}