Update documentation for new release

Signed-off-by: Malfurious <m@lfurio.us>

2 files changed, 139 insertions, 123 deletions

diff --git a/CONTRIBUTING b/CONTRIBUTING
deleted file mode 100644
index 4f1846f..0000000
--- a/CONTRIBUTING
+++ /dev/null
@@ -1,36 +0,0 @@
-sploit is currently developed by a two man team and the majority of our workflow
-isn't publicly available.  We have a private issue tracker and we handle code
-integration through email between us.  If we see significant community interest
-in the project, we may create a public mailing list and maybe publicize our
-issue tracker.  For now, though, if you want to contribute to sploit, the best
-way to do so is to get in contact with one of us through email.
-
-If you see something simple that needs to be fixed, feel free to create a patch
-and email it to us!
-
-If you have an issue that you can't/won't fix yourself but think it deserves
-attention, shoot us an email!  We can give feedback on how your idea fits in
-with our vision or get an issue tracked internally.
-
-If you want to make a larger contribution, please reach out to us first so that
-we can ensure your idea fits in with our vision before you spend a lot of time
-on it.  After that, we will have you submit your work by emailing us patches.
-
-We currently have no plans of using Github's issue tracker or Pull Request
-systems.  If you submit things through them, they will likely be ignored.
-
-Any submitted patches should contain a commit message following the style of
-https://commit.style/ and including a sign-off.
-```
-$ git commit -s
-```
-
-Creating patches is easy with git send-email or git format-patch.  You can read
-more about this process here https://git-send-email.io/.
-```
-$ git send-email origin/master --to=howcansocksbereal@gmail.com --subject-prefix="PATCH sploit"
-```
-
-Please try to follow the style of the surrounding code in the rest of the file.
-If you add something new, make sure to add docstrings to the public API.  If you
-modify existing code, make sure you update the docstrings accordingly.
diff --git a/README.txt b/README.txt
index 8a0e531..a20dc6a 100644
--- a/README.txt
+++ b/README.txt
@@ -1,90 +1,142 @@
-sploit is a process interaction automation tool with software exploitation
-focused utilities.  It is designed to abstract and simplify process invocation
-to enable exploit code reuse across target sources.  It includes a limited, but
+                          ░█▀█░█▀▀░█▀█░█░░░█▀█░▀█▀░▀█▀
+                          ░█░█░▀▀█░█▀▀░█░░░█░█░░█░░░█░
+                          ░▀░▀░▀▀▀░▀░░░▀▀▀░▀▀▀░▀▀▀░░▀░
+
+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.  This enables rapid prototyping workflows.
+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
---------------
-sploit can be installed to the system with
-```
-$ pip install .
-```
-
-Once installed, sploit can be invoked from the PATH like normal
-```
-$ sploit exploit.py ./target target_args
-```
-
-Usage
-------------
-sploit has two main modes of operation: Process and Pipes.
-
-A sploit script can be run against a specific command in Process mode.  This
-will automatically connect the target's stdio into a handy io object that can
-be referenced in the sploit script.
-```
-$ sploit exploit.py ./target target_args
-```
-
-If sploit is run omitting the target, it will launch in Pipes mode.  Here, it
-will create temporary FIFOs for stdio which will be tied to the same io object
-in the sploit script.  In this way, the same script can be used in both modes
-and against any target source regardless of how it exposes its stdio.
-```
-$ sploit exploit.py
-```
-
-The pipe FIFOs are normally located in a temporary directory.  However, if a
-directory name is given, sploit will use that location instead.  A particularly
-useful way to use this is to store the pipes in the current directory for working
-with Docker.
-```
-$ sploit exploit.py .
-```
-
-When running in Pipes mode, sploit will wait for something to connect on the
-FIFOs before actually executing the exploit script.  Once it has finished, it
-will go back to waiting and run the script again the next time it connects.
-This will loop indefinitely until you give a keyboard interrupt (Ctrl+C).  The
-exploit script can be modified between each run without any problems.
-
-The main use case of Pipes mode is when you want to launch the target program
-under another program (such as gdb).  This enables a powerful workflow where you
-can keep sploit and gdb running, make small alterations to the exploit script,
-and re-run the target directly in gdb to see what happens.  This allows for
-rapid prototyping.
-
-```
-gdb> r </tmp/tmpksakkt8o/in >/tmp/tmpksakkt8o/out
-```
-
-You can also directly run sploit scripts with the following shebang
-```
-#!/usr/bin/env sploit
-```
-
-Docker Image
---------------
-In addition to a local pip install, sploit is also deployable via Docker.  Build
-the image using the supplied Dockerfile with:
-```
-$ docker build -t sploit .
-```
-
-The container runs in the style of an application, and therefore expects to be
-interactive.  Also note that it is useful to mount your working directory in the
-container, so that the running sploit instance can actually access your target
-files or expose its pipes to you (the default working dir of the container is
-/home).  Therefore a basic command to run a containerized sploit would be:
-```
-$ docker run --rm -it -v $PWD:/home sploit exploit.py ./target target_args
-```
-
-The use of Scuba (pip install scuba) is recommended to make using ephemeral,
-interactive containers more convenient.  In this case it has the added benefit
-of automatically creating and executing within an unprivileged user inside the
-container:
-```
-$ scuba --image sploit exploit.py ./target target_args
-```
+============
+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