{"id":18564469,"url":"https://github.com/guardsquare/android-insecure-tls-demo","last_synced_at":"2025-04-10T04:31:49.225Z","repository":{"id":50250131,"uuid":"439062804","full_name":"Guardsquare/android-insecure-tls-demo","owner":"Guardsquare","description":"Hands-on experiments to demonstrate the exploitability of insecure TLS configurations in Android apps","archived":false,"fork":false,"pushed_at":"2022-01-18T12:58:02.000Z","size":124,"stargazers_count":15,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-24T16:11:08.601Z","etag":null,"topics":["android","appsec","docker-compose","https","man-in-the-middle","tls"],"latest_commit_sha":null,"homepage":"https://www.guardsquare.com/blog/insecure-tls-certificate-checking-in-android-apps","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Guardsquare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-16T16:49:35.000Z","updated_at":"2023-07-25T14:52:37.000Z","dependencies_parsed_at":"2022-08-25T19:02:07.901Z","dependency_job_id":null,"html_url":"https://github.com/Guardsquare/android-insecure-tls-demo","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Guardsquare%2Fandroid-insecure-tls-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Guardsquare%2Fandroid-insecure-tls-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Guardsquare%2Fandroid-insecure-tls-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Guardsquare%2Fandroid-insecure-tls-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Guardsquare","download_url":"https://codeload.github.com/Guardsquare/android-insecure-tls-demo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248157472,"owners_count":21057020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","appsec","docker-compose","https","man-in-the-middle","tls"],"created_at":"2024-11-06T22:15:18.808Z","updated_at":"2025-04-10T04:31:48.822Z","avatar_url":"https://github.com/Guardsquare.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Containerized Demo for Insecure TLS Certificate Checking in Android\n\n## Overview\n\nThis repository contains the files you need to run the demos for our blog post series\non TLS certificate checking in Android apps. The\n[first post](https://www.guardsquare.com/blog/insecure-tls-certificate-checking-in-android-apps)\ncovers common implementation errors and the\n[second one](https://guardsquare.com/blog/how-to-securely-implement-tls-certificate-checking-in-android-apps)\nthen explains how you can securely configure TLS connections even in cases when you have\nto deviate from the default behavior. There are two parts to the repo:\n\n1. **Example app:** In [app/](app/) you will find the full AndroidStudio project for the example app that showcases\n   different TLS checking implementations.\n2. **Docker setup:** By running [setup.sh](setup.sh) you prepare a Docker environment consisting of several containers:\n   An Android emulator is spawned and a web frontend to interact with it is made available on https://localhost\n   (Note that this frontend uses a self-signed certificate). Additionally, an example web server container is\n   created, which will be used as the backend for the demo scenarios. The last part of the setup is an attacker\n   container, through which you will be able to interactively intercept web traffic between backend server and\n   Android emulator.\n\n## Scenario Overview\n\nThe backend serves a simple HTML website over HTTPs. This mimicks the situation where sensitive data is provided\nover a secure connection. The catch is that the certificate it uses (see [backend/nginx-certs/](backend/nginx-certs))\nhas not been issued by a globally trusted CA but rather by a custom one.\n\nThe Android app in [app/](app/) fetches the data provided by this server and displays it to the user. In order to\nmake Android accept the custom certificate, the default certificate checking mechanism needs to be modified.\nTo showcase different insecure ways of doing so, the app consists of several tabs, where each\nfetches the data using a different workaround commonly found online. You can check out the corresponding\nsource code in [WebViewFragment.kt](app/app/src/main/kotlin/com/example/insecuretls/ui/main/WebViewFragment.kt).\n\nIn the first blog post we cover three different types of implementation errors:\n\n1. **[WebView ignores all SSL errors](https://www.guardsquare.com/blog/insecure-tls-certificate-checking-in-android-apps#webview):**\n   See [setupInsecureWebView()](app/app/src/main/kotlin/com/example/insecuretls/ui/main/WebViewFragment.kt#L58)\n2. **[Malfunctioning X509TrustManager Implementations](https://www.guardsquare.com/blog/insecure-tls-certificate-checking-in-android-apps#Malfunctioning):**\n   See [setupInsecureTrustManager()](app/app/src/main/kotlin/com/example/insecuretls/ui/main/WebViewFragment.kt#L108)\n3. **[Disabled Host Name Checks](https://www.guardsquare.com/blog/insecure-tls-certificate-checking-in-android-apps#host_name):**\n   See [setupInsecureHostnameVerifier()](app/app/src/main/kotlin/com/example/insecuretls/ui/main/WebViewFragment.kt#L82)\n\nThe second blog post explains how to configure non-standard certificate checking behaviors in a secure way:\n\n1. **[Allowing Custom Certificate Authorities](https://www.guardsquare.com/blog/how-to-securely-implement-tls-certificate-checking-in-android-apps#Allowing_Custom_Certificate_Authorities):**\n   1. **SDK 24 And Newer:** See [setupNetworkSecurityConfig()](app/app/src/main/kotlin/com/example/insecuretls/ui/main/WebViewFragment.kt#L165)\n      and [network_security_config.xml](app/app/src/main/res/xml/network_security_config.xml)\n   2. **Older Versions:** See [setupCustomCaLegacy()](app/app/src/main/kotlin/com/example/insecuretls/ui/main/WebViewFragment.kt#L211)\n      and [setupCustomCaLegacyWebview()](app/app/src/main/kotlin/com/example/insecuretls/ui/main/WebViewFragment.kt#L260)\n2. **[Certificate Pinning](https://www.guardsquare.com/blog/how-to-securely-implement-tls-certificate-checking-in-android-apps#Certificate_Pinning):**\n   1. **SDK 24 And Newer:** See [setupNetworkSecurityConfig()](app/app/src/main/kotlin/com/example/insecuretls/ui/main/WebViewFragment.kt#L165)\n      and [network_security_config.xml](app/app/src/main/res/xml/network_security_config.xml)\n   2. **Older Versions:** See [setupPinningLegacy()](app/app/src/main/kotlin/com/example/insecuretls/ui/main/WebViewFragment.kt#L323)\n      and [setupPinningLegacyWebview()](app/app/src/main/kotlin/com/example/insecuretls/ui/main/WebViewFragment.kt#L405)\n\nThis app will be installed to a containerized Android emulator that lives in the same virtual network as\nthe backend server and the attacker. Setting this network up is explained in the next section.\n\n## Prerequisites\n\nIn order to launch the demo environment, you will need to have [docker-compose](https://docs.docker.com/compose/install/)\ninstalled, as well as Python3, NodeJS and npm. Also make sure to have the Android SDK installed (SDK platform version 31).\nThe `ANDROID_SDK_ROOT` environment variable needs to point to its installation directory, usually `~/Android/Sdk`.\nAll other necessary dependencies will be downloaded automatically.\n\n## Docker Setup\n\nRunning [setup.sh](setup.sh) will get the necessary files to set up the Docker containers, which may take a while,\ndepending on your system performance and Internet speed. Afterwards you can launch the containers with [run.sh](run.sh).\nThis script takes care of several things:\n\n1. The Android emulator will be booted and a web interface to interact with it is made available on\n   https://localhost (Note that the website uses a self-signed certificate). Login with username `user` and password\n   `pass`. Then you should see the emulator screen, with which you can interact using your mouse.\n2. In the meantime, the example app is compiled and once the emulator is fully booted up it is installed\n   and launched automatically.\n3. Once the app is running, a bash shell is opened on the attacker container so that you can interactively\n   experiment with the man-in-the-middle setup. As a quick start, you can simply execute the [start.sh](eve/eve_files/start.sh)\n   script that you will find in the current working directory where the shell was spawned (`/eve_files` on the container).\n   \n   This script sets up the attacker proxy using the [mitmproxy](https://mitmproxy.org/) tool without needing\n   any user input. You can then observe intercepted traffic in the console that will show up.\n   To exit the console and stop the attack, simply press Ctrl+C and confirm. Should you want to deviate\n   from the default attacker script, feel free to inspect [start.sh](eve/eve_files/start.sh) and the associated\n   [proxy.py](eve/eve_files/proxy.py) file.\n   \n   If you would like to experiment with the certificate pinning implementations,\n   `start.sh` allows you to pass `--custom-ca`, which will instruct `mitmproxy` to use a certificate\n   that was signed by the same custom CA that the example server uses. This  mimics the situation that the\n   attacker is indeed able to get a valid certificate for your domain, which would be trusted under normal circumstances.\n   The additional certificate pinning step however is able to successfully detect the attack and refuse the connection.\n5. After you are done exploring the demos, simply exit the attacker shell as usual (Ctrl+D or typing `exit`).\n   This will automatically shut down the containers in a clean way.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguardsquare%2Fandroid-insecure-tls-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguardsquare%2Fandroid-insecure-tls-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguardsquare%2Fandroid-insecure-tls-demo/lists"}