Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Quick Start Guide
- Open the
NeedleAgentapp on your device.
- Then, tap on
Listenin the top left corner and it will start listening on port
4444by default. This can be changed using the field in the top right.
To launch Needle, just open a console and type:
$ python needle.py __ _ _______ _______ ______ ______ | \ | |______ |______ | \ | |______ | \_| |______ |______ |_____/ |_____ |______ Needle v1.0 [mwr.to/needle] [MWR InfoSecurity (@MWRLabs) - Marco Lancini (@LanciniMarco)] [needle] > help Commands (type [help|?] <topic>): --------------------------------- back exit info kill pull reload search shell show use exec_command help jobs load push resource set shell_local unset [needle] > show options Name Current Value Required Description ------------------------ ------------- -------- ----------- AGENT_PORT 4444 yes Port on which the Needle Agent is listening APP no Bundle ID of the target application (e.g., com.example.app). Leave empty to launch wizard DEBUG False yes Enable debugging output HIDE_SYSTEM_APPS False yes If set to True, only 3rd party apps will be shown IP 127.0.0.1 yes IP address of the testing device (set to localhost to use USB) OUTPUT_FOLDER /root/.needle/output yes Full path of the output folder, where to store the output of the modules PASSWORD ******** yes SSH Password of the testing device PORT 2222 yes Port of the SSH agent on the testing device (needs to be != 22 to use USB) PUB_KEY_AUTH True yes Use public key auth to authenticate to the device. Key must be present in the ssh-agent if a passphrase is used SAVE_HISTORY True yes Persists command history across sessions SKIP_OUTPUT_FOLDER_CHECK False no Skip the check that ensures the output folder does not already contain other files. It will automatically overwrite any file USERNAME root yes SSH Username of the testing device VERBOSE True yes Enable verbose output [needle] >
You will be presented with Needle's command line interface.
The tool has some global options (listed with the "
show options" command, and set with the "
set <option> <value>" command):
- USERNAME, PASSWORD: SSH credentials of the testing device (set by default to "root" and "alpine", respectively)
- PUB_KEY_AUTH: Use public key authentication to authenticate to the device. Key must be present in the ssh-agent if a passphrase is used
- IP, PORT: the session manager embedded in the core of Needle is able to handle SSH connections over Wi-Fi or USB. If SSH-over-USB is the chosen method, the IP option must be set to localhost ("set IP 127.0.0.1"), and PORT set to anything different from 22 ("set PORT 2222")
- AGENT_PORT: Port on which the NeedleAgent installed on the device is listening to
- APP: this is the bundle identifier of the app to analyse (e.g., "com.example.app"). If it is not known beforehand, this field can be left empty. In this case, Needle will launch a wizard which prompts the user to select an app among those already installed on the device
- OUTPUT_FOLDER: this is the full path of the output folder, where Needle will store the output of the modules
- SKIP_OUTPUT_FOLDER_CHECK: if set to True, it will skip the check that ensures the output folder does not already contain other files
- HIDE_SYSTEM_APPS: if set to True, only 3rd party apps will be shown
- SAVE_HISTORY: if set to True, the command history will be persisted across sessions
- VERBOSE, DEBUG: if set to True, they will enable verbose and debug logging, respectively
Needle relies on some dependencies that needs to be installed on the device prior to its use: the
device/dependency_installer module can be used to automatically configure the testing device.
Automated, using a resource file
Configuration of the global options can also be automated, using a resource file. First, create a resource file with the commands you want to have automatically executed. For example:
$ cat config.txt # This is a comment, it won't be executed set DEBUG False set VERBOSE False set IP 192.168.0.10 set PORT 5555 set APP com.example.app use binary/info/metadata
Then, launch Needle and instruct it to load the resource file:
python needle.py -r config.txt
Non-interactive mode (CLI)
Please refer to the relevant page.