░█▀█░█▀▀░█▀█░█░░░█▀█░▀█▀░▀█▀
                          ░█░█░▀▀█░█▀▀░█░░░█░█░░█░░░█░
                          ░▀░▀░▀▀▀░▀░░░▀▀▀░▀▀▀░▀▀▀░░▀░

nsploit is a process interaction automation tool with software exploitation
focused utilities.  nsploit is a fork of the original project "sploit" by
Dusoleil and Malfurious.  It is designed to simplify process invocation and
enable exploit code reuse across target sources.  It includes a limited, but
powerful and intuitive set of utilities and syntactic sugar which make writing
exploits quick and straightforward, enabling rapid prototyping.

nsploit is implemented as a Python library and user scripts are written in the
Python programming language.  However, instead of directly executing scripts,
most users should use nsploit's accompanying CLI interface to launch scripts as
well as targets.  This enables several advantages, as will be explored in the
following sections.



Quick Start
===========
nsploit's core functionalities depend on nothing beyond an installation of
Python, and can be run directly out of the source tree.  This allows for casual
use of nsploit, or use within limited environments.

To use nsploit in this way, simply run ./nsploit.py from the repository root
directory.  nsploit will function normally, and note that the software version
string has "-uninstalled" appended to it in this case.  See the sections on CLI
usage and exploit scripts for further assistance.

Note that nsploit has some automated reverse-engineering features - the use of
which require radare2 to be present on the system.  This is therefore an
optional dependency.



Installation
============
nsploit can be installed to the system using pip, placing the CLI binary in your
system's PATH and making the nsploit packages available for import.

    $ pip install .

Installation will also upgrade a previous version, but does not conflict with
original sploit.



Command Line Interface - Subprocess Mode
========================================
nsploit is used to launch both your target program and exploit script.

    $ nsploit <script.py> <target cmdline>

The content of <target cmdline> is treated as an external command to run, along
with its associated arguments.  nsploit executes the script <script.py> and
provides it with a communication interface object which performs IO on the
target process.  nsploit exits when both the script and the target have finished.



Command Line Interface - Pipe Mode
==================================
nsploit is used to run the exploit script only - the target is managed
externally.

    $ nsploit <script.py> [<directory>]

In this mode, instead of directly executing a target child process, nsploit will
create a pair of named pipes which the IO is directed through.  If <directory>
is given, it specifies the location to create the FIFOs.  Otherwise, they are
placed in a temporary directory.

The user is free to independently launch the target and direct its IO to the
named pipes.  This is useful if you wish to run in a different context such as
inside a docker container or under control of a debugger.

nsploit will wait for the target to open the other side of the pipes before
executing the script <script.py>.  As before, the script is provided with a
communication interface object - connected to the pipes in this case.  After the
script completes, nsploit returns to wait for another target, allowing for
multiple consecutive runs.  During this time, the script may be modified and
will be hot-loaded on the next run.  This loop can be exited with a
KeyboardInterrupt (CTRL+C).



User Exploit Script
===================
The nsploit CLI is used to run scripts, since it performs setup work, manages
the target and comms, and provides various resources to the script's global
scope.

Some common nsploit library modules are pre-imported into the script's namespace
and a target communication object (named "io") is defined.  This allows the
script to avoid code boilerplate involving opening sockets or launching
processes.  Some replacements for Python built-in functions are also defined, to
provide a more streamlined UX with the CLI logic - though this should be of
little impact to users.

"io" is an instance of `nsploit.comm.Comm` and defines several methods for
reading and writing bytes.  io.interact() can be used to give your terminal
direct interactive control over communication with the target.

By default, all data read from the target is automatically printed to the
terminal running nsploit, so there is no need to do so manually.  This can be
changed at runtime, as well as enabling the printing of written data.

Explore the rest of the nsploit code modules for tools to aid with target
analysis, payload generation, and more!



Recommended Debugging Workflow
==============================
Test your exploit as you develop it by running the target in your favorite
debugger.  Using nsploit in pipe mode, you can keep a persistent debug session
running while you make incremental modifications to the script.  This allows you
to retain breakpoints, symbols, and other state between runs, and also benefits
from short-term caching in various nsploit operations.  Each new run seamlessly
picks up the changes you've made to your exploit script.

When it's time to run the exploit on a live system, there's no need to change
anything about your script, simply switch nsploit over to subprocess mode.

nsploit doesn't directly implement support for remote sockets, however the
flexibility of this mode allows you to plug in any applicable userspace tool
such as netcat, socat, ssh, or telnet.  Of course, you can just invoke the
target binary to execute locally as well.



Support and Contributing
========================
Get in touch on the mailing list to ask questions, report suspected problems,
submit patches, or otherwise discuss the nsploit project!

    nsploit-devl@normalmode.org

For information about the list, send a message to:

    nsploit-devl+help@normalmode.org