Optimize the document of Quark Script CWE-295

CWE-295/README.md

@@ -1,30 +1,32 @@
-# Detect CWE-295 in Android Application (InsecureShop.apk)
+# Detect CWE-295 in Android Application
 
-This scenario seeks to find **Improper Certificate Validation**. See
-[CWE-295](https://cwe.mitre.org/data/definitions/295.html) for more
-details.
+This scenario seeks to find **Improper Certificate Validation**.
 
-Let's use this [APK](https://github.com/hax0rgb/InsecureShop) and the
-above APIs to show how the Quark script finds this vulnerability.
+## CWE-295: Improper Certificate Validation
 
-We use the API `findMethodInAPK(samplePath, targetMethod)` to locate all
-`SslErrorHandler.proceed` methods. Then we need to identify whether if
-the method `WebViewClient.onReceivedSslError` is overrode by its
-subclass.
+We analyze the definition of CWE-295 and identify its characteristics.
 
-First, we check and make sure that the `methodInstance.name` is
-`onReceivedSslError`, and the `methodInstance.descriptor` is
-`(Landroid/webkit/WebView; Landroid/webkit/SslErrorHandler; Landroid/net/http/SslError;)V`.
+See [CWE-295](https://cwe.mitre.org/data/definitions/295.html) for more details.
 
-Then we use the API `methodInstance.findSuperclassHierarchy()` to get
-the superclass list of the method's caller class.
+![image](https://imgur.com/cuZ5qPp.jpg)
 
-Finally, we check the `Landroid/webkit/WebViewClient;` is on the
-superclass list. If **YES**, that may cause CWE-295 vulnerability.
+## Code of CWE-295 in InsecureShop.apk
+
+We use the [InsecureShop.apk](https://github.com/hax0rgb/InsecureShop) sample to explain the vulnerability code of CWE-295.
+
+![image](https://imgur.com/t7Y5clb.jpg)
 
 ## Quark Script CWE-295.py
 
-``` python
+To begin with, we use the API ``findMethodInAPK(samplePath, targetMethod)`` to locate all callers of method ``SslErrorHandler.proceed``.
+
+Next, we must verify whether the caller overrides the method ``WebViewClient.onReceivedSslErroris``.
+
+Therefore, we check if the method name and descriptor of the caller match those of ``WebViewClient.onReceivedSslErroris``. After that, we use the API ``methodInstance.findSuperclassHierarchy()`` to check if the superclasses of the caller include ``Landroid/webkit/WebViewClient``.
+
+If both are **YES**, the APK will call ``SslErrorHandler.procees`` without certificate validation when an SSL error occurs, which may cause CWE-295 vulnerability.
+
+```python
 from quark.script import findMethodInAPK
 
 SAMPLE_PATH = "insecureShop.apk"
@@ -33,24 +35,25 @@ TARGET_METHOD = [
     "proceed",                           # method name
     "()V"                                # descriptor
 ]
-OVERRIDE_METHOD = [
+OVERRIDDEN_METHOD = [
     "Landroid/webkit/WebViewClient;",    # class name
     "onReceivedSslError",                # method name
-    "(Landroid/webkit/WebView;"+" Landroid/webkit/SslErrorHandler;" + \
+    "(Landroid/webkit/WebView;" + " Landroid/webkit/SslErrorHandler;" + \
     " Landroid/net/http/SslError;)V"     # descriptor
 ]
 
 for sslProceedCaller in findMethodInAPK(SAMPLE_PATH, TARGET_METHOD):
-    if (sslProceedCaller.name == OVERRIDE_METHOD[1] and
-    sslProceedCaller.descriptor == OVERRIDE_METHOD[2] and
-    OVERRIDE_METHOD[0] in sslProceedCaller.findSuperclassHierarchy()):
+    if (
+        sslProceedCaller.name == OVERRIDDEN_METHOD[1]
+        and sslProceedCaller.descriptor == OVERRIDDEN_METHOD[2]
+        and OVERRIDDEN_METHOD[0] in sslProceedCaller.findSuperclassHierarchy()
+    ):
         print(f"CWE-295 is detected in method, {sslProceedCaller.fullName}")
 ```
 
 ## Quark Script Result
 
-``` TEXT
+```TEXT
 $　python3 CWE-295.py
-Requested API level 29 is larger than maximum we have, returning API level 28 instead.
 CWE-295 is detected in method, Lcom/insecureshop/util/CustomWebViewClient; onReceivedSslError (Landroid/webkit/WebView; Landroid/webkit/SslErrorHandler; Landroid/net/http/SslError;)V
 ```