diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 142 |
1 files changed, 142 insertions, 0 deletions
@@ -0,0 +1,142 @@ + ░█▀█░█▀▀░█▀█░█░░░█▀█░▀█▀░▀█▀ + ░█░█░▀▀█░█▀▀░█░░░█░█░░█░░░█░ + ░▀░▀░▀▀▀░▀░░░▀▀▀░▀▀▀░▀▀▀░░▀░ + +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 |