First off, thanks for taking the time to contribute!
The following is a set of guidelines for contributing to Needle, which is hosted in the MWRLabs Organization on GitHub.
These are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request.
Needle is an open source project, designed to be highly-modular. Needle is indeed easily extensible and new modules can be added in the form of python scripts.
When you initially consider contributing to it, you might be unsure about which of those components implements the functionality you want to change or report a bug for. This section should help you with that.
To get a sense for the components that compose Needle, here’s a list that explains each one’s task:
needle |-- core | |-- device | | |-- app.py [wrapper for managing installed apps] | | |-- device.py [manage connection with the device & basic commands] | | |-- installer.py [install all the tools/dependencies needed on the device] | | `-- remote_operations.py [APIs to interact with the remote OS] | |-- framework | | |-- cli.py [command line interface for Needle, the UI] | | |-- framework.py [init and manage all the other components] | | |-- local_operations.py [APIs to interact with the local OS] | | |-- module.py [base class, inherited by module's implementations] | | `-- options.py [wrapper for the global/local options] | `-- utils | |-- constants.py [global constants for the framework] | |-- __init__.py | |-- menu.py [show menus to the user] | |-- printer.py [provides logging] | `-- utils.py [various utils (path manipulation, escaping, etc)] |-- libs [dependencies that needs to be bundled within Needle] `-- modules [collection of features, in the form of python scripts]
As mentioned in the section above, the framework core exposes APIs to interact with the local and remote OS. These APIs wraps common functionalities, like file and data access, command execution, networking.
A high-level view of the design is shown in the following image:
Needle supports multiple kinds of modules, each type developed for a particular use case. Templates for each type of module are provided in the
| ||Standard module|
| ||To be used for background processes (jobs)|
| ||To be used for modules relying on LLDB|
| ||To be used for modules relying on Frida|
| ||To be used for modules that just needs to execute a JS payload|
| ||To be used for modules that do not require a connection with the device|
This section guides you through submitting a bug report for Needle. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
Explain the problem and include additional details to help maintainers reproduce the problem:
## Issue ### Expected behaviour Tell us what should happen. ### Actual behaviour Tell us what happens instead. ### Steps to reproduce 1. 2. 3. ### needle error logs Ensure verbose and debug mode are enabled: [needle] > set VERBOSE True VERBOSE => True [needle] > set DEBUG True DEBUG => True ## Environment #### Workstation Operating System #### Python Version #### Python Packages (`pip freeze`) #### Device iOS Version
This section guides you through submitting an enhancement suggestion for Needle, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.
## Enhancement ### Expected behaviour Tell us what should happen. ### Actual behaviour Tell us what happens instead. ### Steps which explain the enhancement 1. 2. 3.
Unsure where to begin contributing? You can start by looking through:
developas target branch.
Python code should adhere (as much as possible) to PEP 8.