Merge pull request #25 from iSECPartners/dev

push it

CHANGELOG.md

@@ -0,0 +1,11 @@
+Introspy-iOS Changelog
+======================
+
+## v 0.4
+* Added support for iOS 7, including fixes to accommodate with seatbelt profile changes for System and AppStore apps in iOS 7.
+* Clarified output for arguments and return values Introspy-iOS cannot serialize (such as NSError).
+* Various bug fixes.
+
+
+## v 0.3
+Initial public release.

README.md

@@ -1,33 +1,36 @@
-Introspy
-========
+Introspy-iOS
+============
 
 Blackbox tool to help understand what an iOS application is doing at runtime
 and assist in the identification of potential security issues.
 
+See http://isecpartners.github.io/Introspy-iOS/ for a quick introduction.
+
 
 Description
 -----------
 
-Introspy comprises two separate modules: a tracer and an analyzer.
+This is the repository for the Introspy-iOS tracer.
 
-The tracer component can be installed on a jailbroken device and dynamically
-configured to hook security-sensitive iOS APIs at run-time. The tool records
-details of relevant API calls made by the application, including function
-calls, arguments and return values and persists them in a database.
-Additionally, the calls can optionally be sent to the Console for real-time
-analysis.
+The tracer can be installed on a jailbroken device to hook and log
+security-sensitive iOS APIs called by applications running on the device. The
+tool records details of relevant API calls, including arguments and return
+values and persists them in a database.
+Additionally, the calls are also sent to the Console for real-time analysis.
 
-The Introspy analyzer can then be used to analyze a database generated by the
-tracer, and generate HTML reports containing the list of logged function calls
-as well as a list of potential vulnerabilities affecting the application.
+The database can then be fed to Introspy-Analyzer, a Python script to generate
+HTML reports containing the list of logged function calls as well as a list of
+potential vulnerabilities affecting the application. Introspy-Analyzer is hosted
+on a separate repository:
+https://github.com/iSECPartners/Introspy-Analyzer
 
-See http://isecpartners.github.io/Introspy-iOS/ for a quick introduction.
 
-Introspy Tracer
----------------
+Installation
+------------
 
-Users should first download the right pre-compiled Debian package:
-- https://www.dropbox.com/s/z5cwqk5wti3zsvd/com.isecpartners.introspy-v0.3-iOS_6.1.deb?dl=1
+Users should first download the latest pre-compiled Debian package available
+in the release section of the project page at:
+https://github.com/iSECPartners/Introspy-iOS/releases
 
 ### Dependencies
 
@@ -60,132 +63,50 @@ Finally, kill and restart the App you want to monitor.
 
     dpkg -r com.isecpartners.introspy
 
-Introspy Analyzer
------------------
-
-The analyzer requires Python 2.6 or 2.7.
-
-### Command-line Usage
-
-The Introspy tracer should be first used on the application to be tested, i.e.,
-by selecting it within the "Introspy - Apps" Settings menu on the iOS device.
-Then simply specify the device IP address when you run the analysis tool and
-select the appropriate application database. This will store a local copy of the
-database, which you can analyze again by specifying the database name as opposed
-to the device IP address.
-
-    $ python introspy.py 192.168.1.127 --outdir e-bank
-    [email protected]'s password:
-    0. ./Applications/94656731-0259-4AE9-9EEE-BADC9244AD82/introspy-com.isecpartners.e-bank.db
-    1. ./introspy-com.apple.mobilemail.db
-    2. ./introspy-com.isecpartners.introspytestapp.db
-    Select the database to analyze: 0
-
-The example above will generate an HTML report for the com.isecpartners.e-bank
-application within the newly created "e-bank" directory (specified by the
-`--outdir` option). The HTML report is intended to be the most common interface to
-the call database and allows users to browse the full call list or filter the
-list to view only those calls flagged by specific signatures.
-
-#### Reporting
-
-While the HTML formatted report is the most digestable format, the analysis tool
-can also be used directly from the command-line. Just as the HTML report allows
-you to show/hide signature groups and subgroups, you can specify groups (-g) as
-well as subgroups (-s) when running the analysis to limit the output to only
-those calls that match the filtering criteria.
-
-    $ python introspy.py introspy-com.isecpartners.e-bank.db -g IPC -s Schemes
-    Specific URL schemes are implemented by the application.
-        CFBundleURLTypes:CFBundleURLSchemes
-        arguments =>
-          CFBundleURLIsPrivate => nil
-          CFBundleURLName => transfer-money
-          CFBundleURLScheme => transfer-money
-
-This example shows analysis of a local database with filtering options to limit
-the output to only display registered URL schemes. We can see here that URL
-requests with the transfer-money:// scheme will be handled by the application.
-
-The analysis tool also allows users to print the entire call list similarly to
-the HTML report's "Traced Calls" view by specifiying the `--list` option,
-although this will print an undigestable amount of data to stdout and as such is
-not recommended.
-
-#### Enumerations
-
-The command-line tool also allows users to enumerate various data from the list
-of traced calls (via `--info`), inlcuding a list of all of the unique URLs
-accessed by the application (urls), all files accessed (files), as well as
-Keychain items that were added or modified (keys).
-
-    $ python introspy.py introspy-com.isecpartners.e-bank.db --info keys
-    token = MGJiNzg1NGRkNzBkNGMyZTExNzc4NTA3OTdjNjNkNjFiY2Q1
-    consumerKey = YzAwNzE4ZDZlYjYzOTM4NGM2NTc56j
-    consumerSecret = NmUzYmNjNmQ2YjJjNWU1MDE0Zjk3NGI4MzU4ZWRl
-
-### Programmatic Usage
-
-    >>> from analyzer import DBAnalyzer
-    >>> analyzedDB = DBAnalyzer.DBAnalyzer('introspy-com.isecpartners.e-bank.db')
-    >>> print analyzedDB.get_findings_as_JSON()
-    ...
-    {"class": "CFBundleURLTypes",
-     "method": "CFBundleURLSchemes"},
-         "arguments":
-            {"CFBundleURLName": "transfer-money",
-             "CFBundleURLScheme": "transfer-money",
-             "CFBundleURLIsPrivate": "nil"}
-    }
-
-### Signatures
-
-Beyond simply listing the calls recorded by the Introspy tracer, the analysis
-tool allows you to apply predefined signatures to the call list and flag
-potential vulnerabilities or insecure configurations. Users can browse the list
-of flagged calls simply by browsing to the "Potential Findings" view within the
-generated HTML report and expanding the desired signature group.
-
-The signatures themselves are defined in `analyzer/IOS_SIGNATURES.py` and can be
-easily extended.
-
-Doing It Yourself
------------------
-
-### Building the iOS Tracer From Source
+
+Generating HTML Reports
+-----------------------
+
+The tracer will store data about API calls made by applications in a database
+stored on the device (actually one in each application's folder). This database
+can be fed to a Python script call Introspy-Analyzer in order to generate HTML
+reports that make it a lot easier to review the data collected by the tracer.
+The script will also analyze and flag dangerous API calls in order to facilitate
+the process of identifying vulnerabilities within iOS applications.
+
+Introspy-Analyzer is hosted on a separate repository:
+https://github.com/iSECPartners/Introspy-Analyzer
+
+
+Building Introspy-iOS
+---------------------
 
 Most users should just download and install the pre-compiled Debian package.
 However, if you want to modify the library's functionality you will have to
-clone the source repository and build the debian package yourself.
+build the Debian package yourself.
 
-    git clone https://github.com/iSECPartners/introspy.git
+The build requires rpetrich's fork of the Theos suite, available at
+https://github.com/rpetrich/theos.
+For general instructions on how to install Theos, see
+http://www.iphonedevwiki.net/index.php/Theos/Getting\_Started but make sure
+you're using rpetrich's fork, not the official Theos.
 
-The build requires the Theos suite to be installed;
-see http://www.iphonedevwiki.net/index.php/Theos/Getting\_Started .
 You first have to create a symlink to your theos installation:
 
-    cd introspy/ios-tracer/
+    cd Introspy-iOS/src/
     ln -s /opt/theos/ ./theos
 
 Then, the package can be built using:
 
     make package
 
-### Installing the iOS Tracer From Source
-
-Once you've successfully created the debian package, you can use the Theos
-Makefiles to automatically install the package and respring the device:
+Once you've successfully created the debian package, you can use Theos to
+automatically install the package and re-spring the device by specifying the
+device's IP address in the THEOS_DEVICE_IP environment variable:
 
     export THEOS_DEVICE_IP=192.168.1.127
     make install
 
-Group and Subgroup Filtering
-----------------------------
-
-The groups and subgroups correlate to filtering via the Settings menu as well as
-during offline analysis using the command-line. For details on exactly which
-methods correspond to each group and subgroup, refer to the wiki
-[documentation](https://github.com/iSECPartners/introspy/wiki).
 
 License
 -------