Quick Start Guide

Start NeedleAgent

• Open the NeedleAgent app on your device.
• Then, tap on Listen in the top left corner and it will start listening on port 4444 by default. This can be changed using the field in the top right.

Start Needle

Standard usage

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
  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
• 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

Device Dependencies

Note that installation of dependencies on the device has now been moved to its own module (use device/dependency_installer).

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

Manage Issues

Needle now provides automatic issue detection: modules will automatically detect and keep track of issues in the target app. Just use the various modules implemented in needle and they will automatically populate the list of issues. For a full list of modules supporting this feature, please refer to the module list.

Every issue will hold the following attributes:

• app: the app in which the issue has been identified
• module: the module who identified the issue
• content: the actual issue
• `confidence level: one among ‘HIGH’, ‘MEDIUM’, ‘INVESTIGATE’, or ‘INFORMATIONAL’
• outfile: for verbose output, path of the file containing the full issue

All the issues are going to be stored in the issues.db SQLite database, contained in the chosen output directory.

New commands have also been added to the core of needle to allow you to interact with this new feature:

List issues (<issues>)

Type issues to have a list of all the issues identified printed to screen.

[needle] > issues
[+] The following issues have been identified:
[!] ISSUE #0
[!] 	                 App: uk.co.bbc.newsuk
[!] 	              Module: modules/binary/info/metadata.py
[!] 	                Name: ATS Disabled
[!] 	             Content: NSAllowsArbitraryLoads: True
[!] 	          Confidence: HIGH
[!] 	             Outfile: None


[!] ISSUE #1
[!] 	                 App: uk.co.bbc.newsuk
[!] 	              Module: modules/storage/data/keychain_dump_frida.py
[!] 	                Name: Keychain items detected (1)
[!] 	             Content: See the content of the linked file
[!] 	          Confidence: INVESTIGATE
[!] 	             Outfile: /root/.needle/output/frida_script_dump_keychain.txt

Add issue manually (add_issue)

In case you'll want to manually add an issue to the collection, you can invoke the add_issue command to start a wizard that will guide you through the process.

[needle] > add_issue
[>][QUESTION] Please insert app: uk.co.bbc.newsuk
[>][QUESTION] Please insert module: manual
[>][QUESTION] Please insert name: A new issue!
[>][QUESTION] Please insert content: This issue has been added manually
[>][QUESTION] Please insert confidence: HIGH
[>][QUESTION] Please insert outfile:
[needle] > issues
[+] The following issues have been identified:
[!] ISSUE #0
[!] 	                 App: uk.co.bbc.newsuk
[!] 	              Module: modules/binary/info/metadata.py
[!] 	                Name: ATS Disabled
[!] 	             Content: NSAllowsArbitraryLoads: True
[!] 	          Confidence: HIGH
[!] 	             Outfile: None


[!] ISSUE #1
[!] 	                 App: uk.co.bbc.newsuk
[!] 	              Module: modules/storage/data/keychain_dump_frida.py
[!] 	                Name: Keychain items detected (1)
[!] 	             Content: See the content of the linked file
[!] 	          Confidence: INVESTIGATE
[!] 	             Outfile: /Users/marco/.needle/output/frida_script_dump_keychain.txt


[!] ISSUE #2
[!] 	                 App: uk.co.bbc.newsuk
[!] 	              Module: manual
[!] 	                Name: A new issue!
[!] 	             Content: This issue has been added manually
[!] 	          Confidence: HIGH
[!] 	             Outfile: