From b3f41f725f124907b4cf5cac7d4f37ec8f65a42f Mon Sep 17 00:00:00 2001 From: Malfurious Date: Mon, 24 Mar 2025 01:35:23 -0400 Subject: Rename README Ditch the txt extension... Signed-off-by: Malfurious --- README | 142 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.txt | 142 --------------------------------------------------------- pyproject.toml | 2 +- 3 files changed, 143 insertions(+), 143 deletions(-) create mode 100644 README delete mode 100644 README.txt diff --git a/README b/README new file mode 100644 index 0000000..a20dc6a --- /dev/null +++ b/README @@ -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 + +The content of is treated as an external command to run, along +with its associated arguments. nsploit executes the script 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 [] + +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 +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 . 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 diff --git a/README.txt b/README.txt deleted file mode 100644 index a20dc6a..0000000 --- a/README.txt +++ /dev/null @@ -1,142 +0,0 @@ - ░█▀█░█▀▀░█▀█░█░░░█▀█░▀█▀░▀█▀ - ░█░█░▀▀█░█▀▀░█░░░█░█░░█░░░█░ - ░▀░▀░▀▀▀░▀░░░▀▀▀░▀▀▀░▀▀▀░░▀░ - -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 - -The content of is treated as an external command to run, along -with its associated arguments. nsploit executes the script 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 [] - -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 -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 . 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 diff --git a/pyproject.toml b/pyproject.toml index f6f29b3..d9d43f8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ name = "nsploit" version = "0.4.0" requires-python = ">=3.9" description = "(n)sploit is a process interaction tool with software exploitation utilities" -readme = "README.txt" +readme = "README" license = {file = "UNLICENSE"} maintainers = [{email = "nsploit-devl@normalmode.org"}] -- cgit v1.2.3