updated documentation for pypi upload
This commit is contained in:
Caleb Stewart
parent
4f0a884945
commit
b291439365
84
README.md
84
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue