From a6427706e78d58df76506311b639c555ecd9b6d7 Mon Sep 17 00:00:00 2001 From: Alban Diquet Date: Sat, 9 Nov 2013 22:43:12 +0800 Subject: [PATCH] Update the README --- README.md | 72 ++++++++++++++++++++++--------------------------------- 1 file changed, 29 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index f392da5..0645d11 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ 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. +See http://isecpartners.github.io/introspy/ for a quick introduction. Introspy Tracer --------------- @@ -64,14 +65,14 @@ Introspy Analyzer The analyzer requires Python 2.6 or 2.7. -### Usage +### 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. 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. +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 mobile@192.168.1.127's password: @@ -86,30 +87,6 @@ application within the newly created "e-bank" directory (specified by the 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. -#### 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/Signatures.py` and can be -easily extended. The following example adds a signature to identify NSData file -writes that don't include data protection values. Beyond simply identifying -method calls, argument matching and argument existence filters can also be -applied. - - signature_list.append(Signature( - title = 'Lack of File Data Protection With NSData', - description = 'A file was written without any data protection options.', - severity = Signature.SEVERITY_MEDIUM, - filter = MethodsFilter( - classes_to_match = ['NSData'], - methods_to_match = ['writeToFile:atomically:', 'writeToURL:atomically:']))) - -### Command-line Usage - #### Reporting While the HTML formatted report is the most digestable format, the analysis tool @@ -121,10 +98,10 @@ 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 + 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 @@ -139,21 +116,19 @@ not recommended. 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 (http), all files accessed (fileio), as well as +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 + token = MGJiNzg1NGRkNzBkNGMyZTExNzc4NTA3OTdjNjNkNjFiY2Q1 + consumerKey = YzAwNzE4ZDZlYjYzOTM4NGM2NTc56j + consumerSecret = NmUzYmNjNmQ2YjJjNWU1MDE0Zjk3NGI4MzU4ZWRl ### Programmatic Usage - >>> from argparse import Namespace - >>> import introspy - >>> spy = introspy.Introspy(Namespace(db='introspy-com.isecpartners.e-bank.db', group='IPC', sub_group='Schemes', list=None)) - >>> for call in spy.analyzer.tracedCalls: - ... print call.json_encode() + >>> from analyzer import DBAnalyzer + >>> analyzedDB = DBAnalyzer.DBAnalyzer('introspy-com.isecpartners.e-bank.db') + >>> print analyzedDB.get_findings_as_JSON() ... {"class": "CFBundleURLTypes", "method": "CFBundleURLSchemes"}, @@ -163,6 +138,17 @@ Keychain items that were added or modified (keys). "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 -----------------