From 006d1d4c754b7f80b6d919559eff3a2a183b4983 Mon Sep 17 00:00:00 2001
From: Takahiro Yoshimura <takahiro_y@monolithworks.co.jp>
Date: Fri, 5 Jan 2024 23:00:57 +0900
Subject: [PATCH] Re-organized sections, adding information

---
 README.md | 95 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 54 insertions(+), 41 deletions(-)

diff --git a/README.md b/README.md
index cc0bebfe..3797a0b1 100644
--- a/README.md
+++ b/README.md
@@ -1,46 +1,18 @@
 # README
 
-trueseeing is a fast, accurate and resillient vulnerabilities scanner for Android apps.  It operates on Android Packaging File (APK) and outputs a comprehensive report in HTML, JSON or a CI-friendly format.  It doesn't matter if the APK is obfuscated or not.
+trueseeing is a fast, accurate and resillient vulnerabilities scanner for Android apps.  We operate on the Dalvik VM level -- i.e. we don't care if the target app is obfuscated or not.
 
 ## Capability
 
-Currently trueseeing can detect the following class of vulnerabilities:
+Currently we can:
 
-  * Improper Platform Usage (M1)
-
-	* Debuggable
-	* Inadvent publishing of Activities, Services, ContentProviders, BroadcastReceivers
-
-  * Insecure Data (M2)
-
-	* Backupable (i.e. suspectible to the backup attack)
-	* Insecure file permissions
-	* Logging
-
-  * Insecure Commnications (M3)
-
-	* Lack of pinning (i.e. suspictible to the TLS interception attack)
-	* Use of cleartext HTTP
-	* Tamperable WebViews
-
-  * Insufficient Cryptography (M5)
-
-	* Hardcoded passphrase/secret keys
-	* Vernum ciphers with static keys
-	* Use of the ECB mode
-
-  * Client Code Quality Issues (M7)
-
-	* Reflectable WebViews (i.e. XSSs in such views should be escalatable to remote code executions via JS reflection)
-	* Usage of insecure policy on mixed contents
-
-  * Code Tampering (M8)
-
-	* Hardcoded certificates
-
-  * Reverse Engineering (M9)
-
-	* Lack of obfuscation
+* Automatically scan app for vulnerabilities, reporting in HTML/JSON/text format (see below)
+* Manipulate app for easier analysis: e.g. enabling debug bit, enabling full backup, disabling TLS pinning, manipulating target API level, etc.
+* Examine app for general information
+* Copy in/out app data through debug interface
+* Search for certain calls/consts/sput/iput
+* Deduce constants/typesets for args of op
+* etc.
 
 ## Installation
 
@@ -56,7 +28,7 @@ If you want to run statelessly you omit mounting volume onto /cache (not recomme
 
 ## Usage
 
-With trueseeing you can interactively examine/analyze/patch/etc. apks -- making it the ideal choice for manual analysis:
+With trueseeing you can interactively scan/analyze/patch/etc. apps -- making it the ideal choice for manual analysis:
 
 	$ docker run -it --rm -v $(pwd):/out -v ts2:/cache ghcr.io/alterakey/trueseeing --inspect target.apk
 	[+] trueseeing 2.1.9 [inspect mode]
@@ -71,7 +43,7 @@ With trueseeing you can interactively examine/analyze/patch/etc. apks -- making
 
 ### Non-interactive scan
 
-Alternatively, you can scan an apk with the following command line to get findings listed in stderr:
+Alternatively, you can scan apps with the following command line to get findings listed in stderr:
 
 	$ docker run --rm -v $(pwd):/out -v ts2:/cache ghcr.io/alterakey/trueseeing --scan target.apk
 
@@ -90,8 +62,7 @@ To get report generated in stdout, specify '-' as filename:
 	$ docker run --rm -v $(pwd):/out -v ts2:/cache ghcr.io/alterakey/trueseeing --scan --format=html -o - target.apk > report.html
 	$ docker run --rm -v $(pwd):/out -v ts2:/cache ghcr.io/alterakey/trueseeing --scan --format=json -o - target.apk > report.json
 
-
-## Building
+## Build
 
 To build:
 
@@ -110,3 +81,45 @@ If you are to hack it, please do something like this instead; in essence, instal
 	(.venv) $ mypy trueseeing && pflake8 trueseeing  # to validate
 	Success: no issues found in XX source files
 	(.venv) $ docker build -t trueseeing .           # to build
+
+## Details
+
+### Vulnerability Classes
+
+Currently we can detect the following class of vulnerabilities, largely ones covered in OWASP Mobile Top 10 - 2016:
+
+  * Improper Platform Usage (M1)
+
+	* Debuggable
+	* Inadvent publishing of Activities, Services, ContentProviders, BroadcastReceivers
+
+  * Insecure Data (M2)
+
+	* Backupable (i.e. suspectible to the backup attack)
+	* Insecure file permissions
+	* Logging
+
+  * Insecure Commnications (M3)
+
+	* Lack of pinning (i.e. suspictible to the TLS interception attack)
+	* Use of cleartext HTTP
+	* Tamperable WebViews
+
+  * Insufficient Cryptography (M5)
+
+	* Hardcoded passphrase/secret keys
+	* Vernum ciphers with static keys
+	* Use of the ECB mode
+
+  * Client Code Quality Issues (M7)
+
+	* Reflectable WebViews (i.e. XSSs in such views should be escalatable to remote code executions via JS reflection)
+	* Usage of insecure policy on mixed contents
+
+  * Code Tampering (M8)
+
+	* Hardcoded certificates
+
+  * Reverse Engineering (M9)
+
+x	* Lack of obfuscation