Saverr/pwncat
1
0
Fork 0
mirror of https://github.com/calebstewart/pwncat.git synced 2024-11-27 10:54:14 +01:00
Code Projects Releases Wiki Activity

updated documentation for pypi upload

Browse Source
This commit is contained in:
Caleb Stewart 2021-06-20 01:08:29 -04:00
parent 4f0a884945
commit b291439365
2 changed files with 41 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
README.md
View File

@ -43,6 +43,36 @@ the latest usage and development documentation!
**pwncat requires Python 3.9+.**
## 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 windows starting at `v0.4.0a1`. The Windows platform
@ -67,21 +97,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 tentatively `v0.4.0a1`. This version has
overhauled a lot of the framework to support multiple platforms and
multisession 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
@ -92,45 +107,6 @@ post-exploitation platforms. You can utilize the familiar `run`, `search`
and `info` commands and enter module contexts with the `use` command.
Refer to the documentation for more information.
## Install
`pwncat` only depends on a working Python development environment. 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
`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:
```shell script
python setup.py install
```
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
```
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.
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`.
### Connecting to a Victim
The command line parameters for pwncat attempt to be flexible and accept

23
docs/source/installation.rst
View File

@ -4,20 +4,23 @@ Installation
.. toctree::
:maxdepth: -1
The only system dependency for pwncat is ``python3`` and ``pip``. For ``pip`` to install all Python dependencies,
you will likely need your distributions Python Development package (``python3-dev`` for Debian-based distributions).
Once you have a working ``pip`` installation, you can install pwncat with the provided setup script:
The only system dependency for pwncat is ``python3`` and ``pip``. For ``pip`` to install all Python dependencies, you will likely need your distributions Python Development package (``python3-dev`` for Debian-based distributions). A virtual environment is recommended, but not required.
.. code-block:: bash
:caption: Install pwncat w/ Virtual Environment
# A virtual environment is recommended
python -m venv /opt/pwncat
# Install pwncat within the virtual environment
# Replace `latest` with a versioned tag if needed (e.g. `v0.4.0`)
/opt/pwncat/bin/pip install 'git+https://github.com/calebstewart/pwncat@latest#egg=pwncat'
/opt/pwncat/bin/pip install pwncat-cs
# This allows you to use pwncat outside of the virtual environment
ln -s /opt/pwncat/bin/pwncat /usr/local/bin
.. code-block:: bash
:caption: Install pwncat without Virtual Environment
pip install pwncat-cs
After installation, you can use pwncat via the installed script:
.. code-block:: bash
@ -95,15 +98,11 @@ builtin plugins from the GitHub releases page. You can then extract it into your
Development Environment
-----------------------
If you would like to develop modules for pwncat (such as privilege escalation or persistence module), you can use
the ``setuptools`` "develop" target instead of "install". This installs pwncat via symlinks, which means any
modifications of the local code will be reflected in the installed package:
pwncat utilizes the Poetry dependency and build manager. After installing poetry, you can use it to manage a local development environment.
.. code-block:: bash
git clone https://github.com/calebstewart/pwncat.git
cd pwncat
python -m venv env
. env/bin/activate
python setup.py develop
poetry shell
poetry install