Skip to content
1337skills 1337skills

Needle

Needle is a Python-based framework for iOS security testing and mobile penetration testing. It provides modules for analyzing iOS applications, examining binaries, accessing app storage, intercepting network traffic, and testing various security aspects of iOS systems.

Installation

macOS Requirements

# Install Xcode Command Line Tools
xcode-select --install

# Install Python 3 and dependencies
brew install python3 libimobiledevice

# Clone Needle repository
git clone https://github.com/mwrlabs/needle.git
cd needle

# Install requirements
pip3 install -r requirements.txt

# Install Needle
python3 setup.py install

# Verify installation
needle --version

Setup iOS Device

# Connect iPhone/iPad via USB
# Install Cydia (if on jailbroken device)
# Install required packages via Cydia:
# - OpenSSH
# - Darwin CC Tools

# Install Needle dependencies on device
sudo apt-get install python libssl-dev

Basic Usage

# Show help
needle --help
needle -h

# List available modules
needle --list-modules
needle -l

# Interactive mode
needle

# Run specific module
needle -m module_name

Device Connection

Establish Device Connection

# List connected devices
needle -i

# Check device details
instruments -s devices

# Test connectivity to jailbroken device
ssh root@<device_ip>

# Default password (common)
alpine

# Change default password
ssh root@<device_ip>
passwd

Device Communication

# Install dependencies via SSH
ssh root@<device_ip> 'apt-get update && apt-get install -y apt-utils'

# Check iOS version
ssh root@<device_ip> 'uname -a'

# Access application directory
ssh root@<device_ip> 'ls -la /var/mobile/Containers/Bundle/Application/'

Binary Analysis

Extract and Analyze Binaries

# List modules for binary analysis
needle --list-modules | grep -i binary

# Module: dumpdecrypted
# Decrypt iOS application binary
needle -m binary/dump_binary -p com.example.app

# Module: strings
# Extract strings from binary
needle -m binary/strings -p com.example.app

# Module: class dump
# Dump Objective-C class information
needle -m binary/class_dump -p com.example.app

# Manual extraction via SSH
ssh root@<device_ip> 'find /var/containers -name "*.app" -type d'

Binary Inspection

# Check binary architecture
file <binary_path>

# List shared libraries
otool -L <binary_path>

# Extract symbols
nm <binary_path>

# Display strings
strings <binary_path>

# Analyze with class-dump
class-dump <binary_path>

Application Storage Analysis

Access App Data

# List app containers
needle -m storage/list_applications

# Module: UserDefaults
# Access app preferences/defaults
needle -m storage/userdefaults -p com.example.app

# Module: Keychain
# Access stored credentials
needle -m storage/keychain -p com.example.app

# Module: Plist Files
# Analyze configuration files
needle -m storage/plist -p com.example.app

# Module: SQLite Databases
# Extract and analyze databases
needle -m storage/sql_databases -p com.example.app

Manual Storage Access

# SSH into device
ssh root@<device_ip>

# Navigate to app container
cd /var/mobile/Containers/Data/Application/<APP_UUID>

# List files
find . -type f

# Extract databases
find . -name "*.db" -o -name "*.sqlite"

# Pull files locally
scp -r root@<device_ip>:/var/mobile/Containers/Data/Application/<UUID>/Documents/* ./

# Analyze plist files
plutil -p <file.plist>

Network Traffic Analysis

Intercept Network Traffic

# Module: Traffic Capture
needle -m network/traffic_capture

# Module: SSL Bypass
needle -m network/ssl_bypass

# Module: SSL Pinning
# Test SSL pinning implementation
needle -m network/ssl_pinning -p com.example.app

# Module: Proxy Configuration
needle -m network/proxy_config

Setup Proxy Interception

# Configure device proxy
# Settings > WiFi > <Network> > HTTP Proxy > Manual

# Set proxy to computer running Burp/Mitmproxy
# IP: <computer_ip>
# Port: 8080

# Install Burp CA certificate
# Download and install via Safari

# Or use mitmproxy
mitmproxy --mode transparent --listen-host 0.0.0.0 --listen-port 8080

Module Categories

Authentication

# Module: Authentication bypass
needle -m code/authentication

# Module: Touch ID/Face ID
needle -m code/biometric

# Module: Session management
needle -m code/session_management

# List all code modules
needle --list-modules | grep 'code/'

Code Analysis

# Module: Static Analysis
needle -m code/static_analysis -p com.example.app

# Module: Hardcoded Data
needle -m code/hardcoded_data -p com.example.app

# Module: Method Hooking
needle -m code/method_hooking

# Module: Frida Gadget
needle -m code/frida_gadget

Filesystem

# Module: File Permissions
needle -m filesystem/permissions

# Module: File Accessible Outside App
needle -m filesystem/shared_files

# Module: Backupable Files
needle -m filesystem/backupable

# Module: Data Storage
needle -m filesystem/data_storage_protection

Complete Testing Workflow

#!/bin/bash
# Complete iOS application security assessment with Needle

OUTPUT_DIR="needle_assessment_$(date +%Y%m%d_%H%M%S)"
APP_BUNDLE="com.example.app"
DEVICE_IP="192.168.1.100"

mkdir -p "$OUTPUT_DIR"

echo "[*] Starting iOS Security Assessment"
echo "[*] Target App: $APP_BUNDLE"

# 1. Device enumeration
echo "[*] Enumerating device..."
needle -m device/list_apps > "$OUTPUT_DIR/apps_list.txt"

# 2. Binary analysis
echo "[*] Analyzing application binary..."
needle -m binary/dump_binary -p "$APP_BUNDLE" > "$OUTPUT_DIR/binary_dump.txt"
needle -m binary/class_dump -p "$APP_BUNDLE" > "$OUTPUT_DIR/class_dump.txt"

# 3. Storage analysis
echo "[*] Analyzing application storage..."
needle -m storage/userdefaults -p "$APP_BUNDLE" > "$OUTPUT_DIR/userdefaults.txt"
needle -m storage/keychain -p "$APP_BUNDLE" > "$OUTPUT_DIR/keychain.txt"

# 4. Network analysis
echo "[*] Setting up network traffic capture..."
needle -m network/traffic_capture > "$OUTPUT_DIR/network_traffic.txt" &
sleep 30

# 5. Code analysis
echo "[*] Analyzing code for vulnerabilities..."
needle -m code/authentication -p "$APP_BUNDLE" > "$OUTPUT_DIR/auth_analysis.txt"
needle -m code/hardcoded_data -p "$APP_BUNDLE" > "$OUTPUT_DIR/hardcoded_data.txt"

# 6. Generate assessment report
cat > "$OUTPUT_DIR/assessment_report.txt" << EOF
iOS Application Security Assessment
Target: $APP_BUNDLE
Date: $(date)
Device: $DEVICE_IP

## Summary
- Binary Analysis: $(cat "$OUTPUT_DIR/binary_dump.txt" | wc -l) lines
- Classes Found: $(grep -c 'class ' "$OUTPUT_DIR/class_dump.txt")
- Keychain Items: $(grep -c 'key:' "$OUTPUT_DIR/keychain.txt")
- UserDefaults: $(grep -c 'key:' "$OUTPUT_DIR/userdefaults.txt")

## Findings
See individual analysis files for detailed results.

## Recommendations
- Review binary for hardcoded credentials
- Audit storage mechanisms
- Test authentication bypass vectors
- Verify SSL pinning implementation
- Check data protection classes
EOF

echo "[+] Assessment complete!"
echo "[*] Results saved to: $OUTPUT_DIR"

Advanced Techniques

Manual Frida Hooking

#!/usr/bin/env python3
import frida
import sys

def on_message(message, data):
    if message['type'] == 'send':
        print("[*] {}".format(message['payload']))
    elif message['type'] == 'error':
        print("[!] {}".format(message['stack']))

# Connect to device
device = frida.get_usb_device()
pid = device.spawn(["com.example.app"])
session = device.attach(pid)

# JavaScript payload for hooking
jscode = """
Interceptor.attach(Module.findExportByName(null, "strlen"), {
    onEnter: function(args) {
        console.log("String length check: " + Memory.readUtf8String(args[0]));
    }
});
"""

script = session.create_script(jscode)
script.on('message', on_message)
script.load()
device.resume(pid)

sys.stdin.read()

Database Extraction

# Extract app databases
ssh root://<device_ip> 'tar czf - /var/mobile/Containers/Data/Application/<UUID>/Documents/*.db' | tar xz

# Analyze SQLite database
sqlite3 database.db ".dump"

# Export to CSV
sqlite3 -header -csv database.db "SELECT * FROM table_name;" > output.csv

Troubleshooting

Issue: Device not detected

# Check device connection
idevice_id -l

# Reinstall libimobiledevice
brew uninstall libimobiledevice
brew install libimobiledevice

# Reset USB connection
# Disconnect and reconnect device

Issue: SSH connection refused

# Install OpenSSH on device via Cydia
# Or via apt-get if already jailbroken

# Check SSH service
ssh -v root@<device_ip>

# Test connectivity
ping <device_ip>

Issue: Needle module not found

# Update Needle
cd needle && git pull origin master
pip3 install -r requirements.txt

# List available modules
needle --list-modules

# Check module path
ls -la needle/modules/

Best Practices

  • Always test on authorized devices only
  • Document all findings comprehensively
  • Use isolated network for testing
  • Keep device backups before testing
  • Verify SSL pinning before attempting bypass
  • Follow OWASP Mobile Testing Guide
  • Test on multiple iOS versions
  • Get written authorization before testing
  • Burp Suite Mobile - Web proxy and scanner for mobile
  • Frida - Dynamic instrumentation toolkit
  • Objection - Runtime mobile exploration
  • iProxy - iOS USB proxy
  • Cycript - JavaScript bridge to iOS runtime

Last updated: 2026-03-30 | Needle v1.0