From b2914393650f8d23db1a5ff46409b5de1416e851 Mon Sep 17 00:00:00 2001 From: Caleb Stewart Date: Sun, 20 Jun 2021 01:08:29 -0400 Subject: [PATCH] updated documentation for pypi upload --- README.md | 84 +++++++++++++----------------------- docs/source/installation.rst | 23 +++++----- 2 files changed, 41 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 233d758..fce8ec1 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/source/installation.rst b/docs/source/installation.rst index f683151..f76e8a5 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -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