Improve README UX (#2061)

* add GitHub Discussions
* add slack invite
* add twitters
* improve overall UI/UX
* group badges
* improve how to contribute

.markdownlint.json

@@ -3,7 +3,7 @@
  "MD013": false,
  "MD014": false,
  "MD024": false,
- "MD033": {"allowed_elements": ["img", "br", "div"]},
+ "MD033": {"allowed_elements": ["img", "br", "div", "a"]},
  "MD036": {
  "punctuation": ".,;:!。"
  },

README.md

@@ -1,22 +1,79 @@
-<a href="https://leanpub.com/mobile-security-testing-guide"><img width=180px align="right" style="float: right;" src="Document/Images/mstg-cover-release-small.jpg" /></a>
+<img width="180px" align="right" style="float: right;" src="Document/Images/mstg-cover-release-small.jpg"/>
 
-# OWASP Mobile Security Testing Guide [![Twitter Follow](https://img.shields.io/twitter/follow/OWASP_MSTG.svg?style=social&label=Follow)](https://twitter.com/OWASP_MSTG) [![Open in Visual Studio Code](https://open.vscode.dev/badges/open-in-vscode.svg)](https://open.vscode.dev/OWASP/owasp-mstg)
-
-[![Creative Commons License](https://img.shields.io/github/license/OWASP/owasp-mstg)](https://creativecommons.org/licenses/by-sa/4.0/ "CC BY-SA 4.0")
+# OWASP Mobile Security Testing Guide (MSTG)
 
 [![OWASP Flagship](https://img.shields.io/badge/owasp-flagship%20project-48A646.svg)](https://owasp.org/projects/)
+[![Creative Commons License](https://img.shields.io/github/license/OWASP/owasp-mstg)](https://creativecommons.org/licenses/by-sa/4.0/ "CC BY-SA 4.0")
 
-[![Check Markdown Markup](https:/OWASP/owasp-mstg/workflows/Check%20Markdown%20Markup/badge.svg)](https:/OWASP/owasp-mstg/actions?query=workflow%3A%22Check+Markdown+Markup%22)
 [![Document Build](https:/OWASP/owasp-mstg/workflows/Document%20Build/badge.svg)](https:/OWASP/owasp-mstg/actions?query=workflow%3A%22Document+Build%22)
+[![Check Markdown Markup](https:/OWASP/owasp-mstg/workflows/Check%20Markdown%20Markup/badge.svg)](https:/OWASP/owasp-mstg/actions?query=workflow%3A%22Check+Markdown+Markup%22)
 [![Check Markdown Links](https:/OWASP/owasp-mstg/workflows/Check%20Markdown%20Links/badge.svg)](https:/OWASP/owasp-mstg/actions?query=workflow%3A%22Check+Markdown+Links%22)
 
 This is the official GitHub Repository of the OWASP Mobile Security Testing Guide (MSTG). The MSTG is a comprehensive manual for mobile app security testing and reverse engineering. It describes technical processes for verifying the controls listed in the [OWASP Mobile Application Verification Standard (MASVS)](https:/OWASP/owasp-masvs "MASVS").
 
 - 📖 [Read it on Gitbook](https://mobile-security.gitbook.io/mobile-security-testing-guide/)
 - ⬇️ [Download the latest PDF](https:/OWASP/owasp-mstg/releases/latest)
 - ✅ [Get the latest Mobile App Security Checklists](https:/OWASP/owasp-mstg/releases/latest)
+- ⚡ [Contribute!](#how-to-contribute)
+- 💥 [Play with our Crackmes](https:/OWASP/owasp-mstg/blob/master/Crackmes/README.md)
+
+> The MSTG and the MASVS are being adopted by many companies, standards, and various organizations. Want to find out more? Check our [users' document listing some of the adopters](Users.md).
+
+## Connect with Us
+
+<ul>
+<li><a href="https:/OWASP/owasp-mstg/discussions"><img src="Document/Images/GitHub_logo.png" width="14px"> GitHub Discussions</a></li>
+<li><a href="https://owasp.slack.com/messages/project-mobile_omtg/details/"><img src="Document/Images/slack_logo.png" width="14px"> #project-mobile_omtg</a> (<a href="https://owasp.slack.com/join/shared_invite/zt-g398htpy-AZ40HOM1WUOZguJKbblqkw#//">Get Invitation</a>)</li>
+<li><a href="https://twitter.com/OWASP_MSTG"><img src="Document/Images/twitter_logo.png" width="14px"> @OWASP_MSTG </a> (Official Account)</li>
+<li><a href="https://twitter.com/bsd_daemon"><img src="Document/Images/twitter_logo.png" width="14px"> @bsd_daemon </a> (Sven Schleier, Project Lead) <a href="https://twitter.com/grepharder"><img src="Document/Images/twitter_logo.png" width="14px"> @grepharder </a> (Carlos Holguera, Project Lead)</li>
+</ul>
+
+## How to Contribute
+
+The MSTG is an open source effort and we welcome all kinds of contributions and feedback.
+
+**Help us improve & join our community:**
+
+- 🐞 [Report an error (typos, grammar)](https:/OWASP/owasp-mstg/issues) or [fix it on a Pull Request](https:/OWASP/owasp-mstg/pulls).
+- 💬 [Give feedback](https:/OWASP/owasp-mstg/discussions/categories/general).
+- 🙏 [Ask questions](https:/OWASP/owasp-mstg/discussions/categories/q-a)
+
+**Contribute with content:**
+
+- 💡 [Propose ideas or suggest improvements](https:/OWASP/owasp-mstg/discussions/categories/ideas) (if it qualifies we'll promote it to an [Issue](https:/OWASP/owasp-mstg/issues "Github issues"))
+- 📄 [Create a Pull Request](https:/OWASP/owasp-mstg/pulls) for concrete fixes (e.g. grammar/typos) or content already approved by the core team.
+
+Before you start contributing, please check our [contribution guide](https:/OWASP/owasp-mstg/blob/master/CONTRIBUTING.md "Contribution Guide") which should get you started. If you have any doubts [please contact us](#connect-with-us).
+
+### Contribution Credit / Acknowledgments
+
+Contributors are added to the acknowledgments section based on their contributions logged by GitHub and/or by applying to a certain role and consistenly demonstrating their commitment. Acknowlegements are visible in the [official owasp.org Project Page](https://owasp.org/www-project-mobile-security-testing-guide/#div-acknowledgements), in [GitHub](https:/OWASP/owasp-mstg/blob/master/Document/0x02-Frontispiece.md#acknowledgments), [GitBook](https://mobile-security.gitbook.io/mobile-security-testing-guide/0x02-frontispiece#acknowledgments) and in the [printed versions](https://www.lulu.com/shop/sven-schleier-and-jeroen-willemsen-and-bernhard-m%C3%BCller/owasp-mobile-security-testing-guide/paperback/product-24198359.html).
+
+Contributors are categorized as follows:
+
+- **Project Leader / Author**: Manage the development of the guide continuously and write a large amount of new content. Project Leadership cannot be achieved if any violations of the Code of Conduct occurred in the past. Be aware that you'll be expected to invest lots of time over several months.
+- **Reviewer**: People that continuously monitor and review our [Pull Requests](https:/OWASP/owasp-mstg/pulls) or given useful feedback and suggesting changes.
+- **Most Helpful Discussions contributor**: actively participate in our GitHub Discussions. Contributors with the most answers marked as "The Answer" will get recognized as "Most Helpful" in our official repos.
+- **Co-Author**: Consistently contribute quality content, [at least 2,000 additions logged](https:/OWASP/owasp-mstg/graphs/contributors "Co-author").
+- **Top Contributor**: Consistently contribute quality content, [at least 500 additions logged](https:/OWASP/owasp-mstg/graphs/contributors "Top Contributor").
+- **Contributor**: Any form of contribution, [at least 50 additions logged](https:/OWASP/owasp-mstg/graphs/contributors "Contributor").
+- **Mini-contributor**: Everything below 50 additions, e.g. committing a single word or sentence.
+
+[Contact us](#connect-with-us) (Sven Schleier (Slack: *Sven*) or Carlos Holguera (Slack: *Carlos*)) if you are planning to become an Author/Co-Author/Reviewer, are missing from the acknowledgements (note that we make updates frequently, but not in realtime).
+
+## MSTG Translations
+
+The MSTG is a living document that changes and adapts to the most recent security recommendations every day. While we do want to reach the maximum audience possible, our past experience shows that **maintaining translations has proven to be an extremely challenging task**. Therefore, please understand that **any PRs containing MSTG translations will be declined**, but you're free to do them on your own forks.
+
+> 🇯🇵 A translation of the MSTG into Japanese is available on Github: <https:/coky-t/owasp-mstg-ja>. Thanks to @coky-t for pushing this forward!
+
+That said, we **strongly encourage [further translations of the MASVS](https:/OWASP/owasp-masvs/blob/master/README.md#masvs-translations)** as it is much easier to maintain and you'll get a translated [Mobile App Security Checklists](https:/OWASP/owasp-mstg/releases/latest) mapping to the MSTG for free.
+
+## Other Formats
 
-The MSTG and the MASVS are being adopted by many companies, standards, and various organizations. Want to find out more? Check our [users' document listing some of the adopters](Users.md).
+- Get the [printed version via lulu.com](https://www.lulu.com/shop/sven-schleier-and-jeroen-willemsen-and-bernhard-m%C3%BCller/owasp-mobile-security-testing-guide/paperback/product-24198359.html)
+- Get the [e-book on leanpub.com](https://leanpub.com/mobile-security-testing-guide-preview) (please consider purchasing it to support our project or [make a donation](https://owasp.org/www-project-mobile-security-testing-guide/#div-donate))
+- Check our [Document generation scripts](tools/docker/README.md)
 
 ## Table-of-Contents
 
@@ -68,67 +125,6 @@ The MSTG and the MASVS are being adopted by many companies, standards, and vario
 - [Testing Tools](Document/0x08-Testing-Tools.md)
 - [Suggested Reading](Document/0x09-Suggested-Reading.md)
 
-## Reading the Mobile Security Testing Guide
-
-The release 1.0 of the MSTG was published in June 2018. You can get intermediate builds in multiple formats.
-
-1. Read it on [Gitbook](https://mobile-security.gitbook.io/mobile-security-testing-guide/ "Gitbook"). The book is automatically synchronized with the main repo.
-
-2. Check the [releases](https:/OWASP/owasp-mstg/releases "Our releases"). Here you can find a PDF, an archive containing the sources, and a DocX document for any given tagged version. Please note that the documents are generated automatically per tag.
-
-3. Get the book as a printed version. A hardcopy of the book can be ordered via [lulu.com](https://www.lulu.com/shop/sven-schleier-and-jeroen-willemsen-and-bernhard-m%C3%BCller/owasp-mobile-security-testing-guide/paperback/product-24198359.html "MSTG on Lulu.com"). This version of the book is not completely aligned with book printing standards, but we are improving each version. If you recognize any issues or mistakes, even small ones, please raise an [issue](https:/OWASP/owasp-mstg/issues "our issues section") so we can fix it in the next version.
-
-4. Get the [e-book](https://leanpub.com/mobile-security-testing-guide-preview "MSTG as an e-book"). The book is available for free, but you can choose to purchase it at a price of your choice if you wish to support our project. All funds raised through sales of the e-book go directly into the project budget and will be used to fund the production of future releases.
-
-5. Clone the repository and run the [document generator](https:/OWASP/owasp-mstg/blob/master/tools/docker/pandoc_makedocs.sh "The document generator") (requires [Docker](https://www.docker.com "Docker")). This produces the PDF, Epub, Mobi, and DOCX in the root of the MSTG folder.
-
- ```shell
- $ git clone https:/OWASP/owasp-mstg/
- $ cd owasp-mstg/
- $ ./tools/docker/pandoc_makedocs.sh Document MyVersion
- ```
-
-6. Just check the latest build of the repository at [Github actions](https:/OWASP/owasp-mstg/actions?query=workflow%3A%22Document+Build%22 "Document build"). This offers you the latest SNAPSHOT version of the document to download.
-
-## Contributions, Feature Requests, and Feedback
-
-**We are searching for additional authors, reviewers, and editors.**
-
-You can start contributing in many different ways:
-
-- [Filing or reporting issues](https:/OWASP/owasp-mstg/issues/new/choose "New Issue"),
-- [Choosing one of the existing issues and working on them](https:/OWASP/owasp-mstg/issues "our issues section") or
-- Browsing the [existing content](https://mobile-security.gitbook.io/mobile-security-testing-guide/ "existing content") and proofreading it.
-
-Please check our [Contribution Guide](https:/OWASP/owasp-mstg/blob/master/CONTRIBUTING.md "Contribution Guide") for ideas before you get started.
-
-Please let us know if you'd like to work on an existing open issue before you start working on it. To do so simply write a comment in the issue itself or drop us a line on the [Slack channel](https://owasp.slack.com/messages/project-mobile_omtg/details/ "Come to our Slack!"). This helps us to keep track of what everyone is doing and prevent conflicts.
-
-You can create an OWASP Slack account here: [https://owasp.slack.com/join/shared_invite/zt-g398htpy-AZ40HOM1WUOZguJKbblqkw#//](https://owasp.slack.com/join/shared_invite/zt-g398htpy-AZ40HOM1WUOZguJKbblqkw#// "Join OWASP Slack")
-
-> The MSTG is a living document that changes and adapts to the most recent security recommendations every day. While we do want to reach the maximum audience possible, our past experience shows that maintaining translations has proven to be an extremely challenging task. You're free to do forks for your own translations but please understand that any PRs containing them will be declined due to the previously mentioned reasons. However, we strongly encourage further translations of the MASVS as it is much easier to maintain.
->
-> A translation of the MSTG into Japanese is available on Github: <https:/coky-t/owasp-mstg-ja>. Thanks to @coky-t for pushing this forward!
-
-## Authoring Credit
-
-Contributors are added to the acknowledgments table based on their contributions logged by GitHub. The list of names is sorted by the number of lines added. Authors are categorized as follows:
-
-- Project Leader / Author: Manage the development of the guide continuously and write a large amount of new content. Project Leadership cannot be achieved if any violations of the Code of Conduct occurred in the past.
-- Co-Author: Consistently contribute quality content, [at least 2,000 additions logged](https:/OWASP/owasp-mstg/graphs/contributors "Co-author").
-- Top Contributor: Consistently contribute quality content, [at least 500 additions logged](https:/OWASP/owasp-mstg/graphs/contributors "Top Contributor").
-- Contributor: Any form of contribution, [at least 50 additions logged](https:/OWASP/owasp-mstg/graphs/contributors "Contributor").
-- Mini-contributor: Everything below 50 additions, e.g. committing a single word or sentence.
-- Reviewer: People that haven't submitted their own pull requests, but have created issues or given useful feedback in other ways.
-
-Please ping us or create a pull request if you are missing from the table or in the wrong column (note that we update the table frequently, but not in realtime).
-
-If you are willing to write a large portion of the guide and help consistently drive the project forward, you can join as an author. Be aware that you'll be expected to invest lots of time over several months. Contact Sven Schleier (Slack: *Sven*) or Carlos Holguera (Slack: *Carlos*) for more information.
-
-## Crackmes
-
-In the [Crackmes folder](https:/OWASP/owasp-mstg/blob/master/Crackmes "Crackmes folder"), you can find a set of mobile apps to hack. Are you able to find the secrets? For more details check the [Crackmes README file](https:/OWASP/owasp-mstg/blob/master/Crackmes/README.md "Crackmes readme").
-
 ## About Hybrid Apps
 
 Please note that the MSTG focuses primarily on native apps. These are apps built with Java or Kotlin using the Android SDK for Android or built with Swift or Objective-C using the Apple SDKs for iOS. Apps using frameworks such as Nativescript, React-native, Xamarin, Cordova, etc. are not within the main focus of the MSTG. However, some essential controls, such as certificate pinning, have been explained already for some of these platforms.