mirror of
https://github.com/calebstewart/pwncat.git
synced 2024-11-30 20:34:15 +01:00
bcb1f77606
- Added some last touches to module system. - Modified connect syntax to allow more flexible parameters - Still need to update enumeration API docs and connect command docs
97 lines
4.2 KiB
ReStructuredText
97 lines
4.2 KiB
ReStructuredText
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
python setup.py --user install
|
|
|
|
It is recommended to use a virtual environment, however. This can be done easily with the Python3 ``venv`` module:
|
|
|
|
.. code-block:: bash
|
|
|
|
python -m venv env
|
|
source env/bin/activate
|
|
python setup.py install
|
|
|
|
When updating ``pwncat`` is it recommended to setup and update the virtual environment again.
|
|
|
|
After installation, you can use ``pwncat`` via the installed script:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ pwncat --help
|
|
usage: pwncat [-h] [--config CONFIG] [--identity IDENTITY] [--listen] [--port PORT]
|
|
[[protocol://][user[:password]@][host][:port]] [port]
|
|
|
|
Connect to a remote victim. This command is only valid prior to an established
|
|
connection. This command attempts to act similar to common tools such as netcat
|
|
and ssh simultaneosly. Connection strings come in two forms. Firstly, pwncat
|
|
can act like netcat. Using `connect [host] [port]` will connect to a bind shell,
|
|
while `connect -l [port]` will listen for a reverse shell on the specified port.
|
|
|
|
The second form is more explicit. A connection string can be used of the form
|
|
`[protocol://][user[:password]@][host][:port]`. If a user is specified, the
|
|
default protocol is `ssh`. If no user is specified, the default protocol is
|
|
`connect` (connect to bind shell). If no host is specified or `host` is "0.0.0.0"
|
|
then the `bind` protocol is used (listen for reverse shell). The currently available
|
|
protocols are:
|
|
|
|
- ssh
|
|
- connect
|
|
- bind
|
|
|
|
The `--identity/-i` argument is ignored unless the `ssh` protocol is used.
|
|
|
|
|
|
positional arguments:
|
|
[protocol://][user[:password]@][host][:port]
|
|
Connection string describing the victim to connect to
|
|
port Alternative port number argument supporting netcat-like syntax
|
|
|
|
optional arguments:
|
|
-h, --help show this help message and exit
|
|
--config CONFIG, -c CONFIG
|
|
Path to a configuration script to execute prior to connecting
|
|
--identity IDENTITY, -i IDENTITY
|
|
The private key for authentication for SSH connections
|
|
--listen, -l Enable the `bind` protocol (supports netcat-like syntax)
|
|
--port PORT, -p PORT Alternative port number argument supporting netcat-like syntax
|
|
|
|
SSH Connection Errors
|
|
---------------------
|
|
|
|
Due to the way that SSH channels are abstracted, a custom fork of ``paramiko`` was required to fit into ``pwncat``.
|
|
I submitted a pull request with Paramiko, but it was never merged. Therefore, ``pwncat`` is currently utilizing a
|
|
custom fork of ``paramiko`` which provides an interface which is closer to a standard socket. ``pwncat`` is smart
|
|
enough to tell you this is the problem, but for documentation's sake, this command should fix your problems:
|
|
|
|
.. code-block:: bash
|
|
|
|
# Ensure that the correct paramiko is installed
|
|
pip install -U git+https://git+https://github.com/calebstewart/paramiko
|
|
|
|
If you installed ``pwncat`` within a virtual environment, this should obviously be done inside the virtual environment.
|
|
If you did not install within a virtual environment, this change may break other python tools which depend on a later
|
|
version of paramiko (however it should not affect things which depend on an equal version).
|
|
|
|
This problem is discussed `here <https://github.com/calebstewart/pwncat/issues/60>`_.
|
|
|
|
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
python setup.py develop
|
|
|