Merge pull request #159 from mpast/mpast-update-readme

Update README for improved structure and content

Author: mpast

README.md

@@ -4,44 +4,41 @@
 
 **MobileAudit** - SAST and Malware Analysis for Android Mobile APKs
 
-- [Mobile Audit](#mobile-audit)
-  - [Components](#components)
-  - [Docker Base images](#docker-base-images)
-  - [Main features](#main-features)
-  - [Patterns](#patterns)
-  - [Models](#models)
-    - [Virus Total (API v3)](#virus-total-api-v3)
-    - [Defect Dojo (API v2)](#defect-dojo-api-v2)
-    - [MalwareDB \& Maltrail](#malwaredb--maltrail)
-  - [Installation](#installation)
-  - [API v1](#api-v1)
-    - [Usage](#usage)
-    - [Swagger](#swagger)
-    - [ReDoc](#redoc)
-    - [Endpoints](#endpoints)
-  - [TLS](#tls)
-    - [Pre-requirements](#pre-requirements)
-    - [Nginx configuration](#nginx-configuration)
-    - [Docker configuration](#docker-configuration)
-  - [Environment variables](#environment-variables)
+A Django web application to perform static analysis and detect malicious content inside Android APKs. The project extracts app metadata, scans source code for weaknesses, and aggregates results (SAST findings, best practices, certificate info, strings, databases, files, VirusTotal, and more) into a browsable dashboard and API.
+
+DeepWiki documentation: https://deepwiki.com/mpast/mobileAudit
+
+- [Components](#components)
+- [Docker Base images](#docker-base-images)
+- [Main features](#main-features)
+- [Patterns](#patterns)
+- [Models](#models)
+- [Installation](#installation)
+- [API v1](#api-v1)
+  - [Usage](#usage)
+  - [Swagger](#swagger)
+  - [ReDoc](#redoc)
+  - [Endpoints](#endpoints)
+- [TLS](#tls)
+  - [Pre-requirements](#pre-requirements)
+  - [Nginx configuration](#nginx-configuration)
+  - [Docker configuration](#docker-configuration)
+- [Environment variables](#environment-variables)
 ---------------------------------------
 
-Django Web application for performing Static Analysis and detecting malware in Android APKs
-
 ![App](app/static/app.png)
 
 In each of the scans, it would have the following information:
 
-* Application Info
-* Security Info
-* Components
-* SAST Findings
-* Best Practices Implemented
-* Virus Total Info
-* Certificate Info
-* Strings
-* Databases
-* Files
+- APK information and analysis: Application info, security info, components, certificate info, strings, databases, files
+- SAST findings categorized with CWE and Mobile Top 10 mapping
+- Pattern engine with toggleable rules
+- Malware domain checks against MalwareDB & Maltrail
+- VirusTotal (API v3) lookup & optional upload (disabled by default)
+- DefectDojo integration (API v2) (optional) for exporting findings
+- API with Swagger and ReDoc, plus token-based authentication
+- Export scan reports to PDF
+- Findings editable with false-positive triage
 
 ![App](app/static/scan.png)
 
@@ -71,53 +68,35 @@ Image is based on python buster. Link to [Docker Hub image](https://hub.docker.c
 | mpast/mobile_audit | 1.0.0 | python:3.9.0-buster  |
 
 ### Main features
-
-- [x] Uses Docker for easy deployment in multiplatform environment
-- [x] Extract all information of the APK
-- [x] Analyze all the source code searching for weaknesses
-- [x] All findings are categorized and follows **CWE standards**
-- [x] All findings are categorized and include **Mobile Top 10 Risk**
-- [x] Also highlight the **Best Practices in Secure Android Implementation** in the APK
-- [x] The findings can be edited and the **false positives can be triaged and deleted**
-- [x] All scan results can be **exported to PDF**
-- [x] User authentication and user management
-- [x] API v1 with Swagger and ReDoc
-- [x] TLS
-- [x] Dynamic page reload (WIP)
-- [ ] LDAP integration
-- [ ] Export to Markdown
-- [ ] Export to CSV
+- Runs in Docker for easy, reproducible deployment
+- Extracts and shows detailed APK information
+- SAST rules that map to CWE and Mobile Top 10 risks
+- Malware indicators detection (MalwareDB / Maltrail)
+- Integration points for VirusTotal and DefectDojo (optional)
+- Export scan results to PDF
+- User authentication, management, and token-based API
+- Swagger and ReDoc documentation
+- TLS-ready Nginx configuration for production
+
+Planned / wishlist
+- LDAP integration
+- Export to Markdown / CSV
+- Dynamic page reload improvements (WIP)
 
 ### Patterns
-
-The application has an engine with different rules and patterns that are used though the findings scanning phase to detect vulnerabilities and/or malicious code into the apk.
-
-These can be activated and deactivated in `/patterns`
+- The app includes a rule/pattern engine that detects potential vulnerabilities and malicious snippets inside APKs.
+- Patterns are configurable and can be enabled/disabled from the `/patterns` UI.
+- Note: Some hardcoded patterns are derived from the apkleaks project: https://github.com/dwisiswant0/apkleaks
 
 ![Patterns](app/static/patterns.png)
 
-Note: some of the hardcoded patterns are from [apkleaks](https://github.com/dwisiswant0/apkleaks)
-
 ### Models
 The application has an created models for each of the entities of the scans' information to be able to create relations an abtain the best conclusions for each of the apks.
 
 ![Models](app/static/models_snippet.png)
 
 To see the whole model schema, go to [models](app/static/models.png)
 
-### Integrations
-
-#### Virus Total (API v3)
-
-It checks if there has been an scan of the APK and extract all its information. Also, there is the possibility of uploading the APK is selected a property in the environment (Disabled by default).
-
-#### Defect Dojo (API v2)
-
-It is possible to upload the findings to the defect manager.
-
-#### MalwareDB & Maltrail
-
-It checks in the database if there are URLs in the APK that are related with Malware.
 
 ### Installation
 
@@ -227,29 +206,13 @@ By default, there is a volume in `docker-compose.yml` with the configuration wit
 
 ### Environment variables
 
-All the environment variables are in a `.env` file, there is an `.env.example` with all the variables needed. Also there are collected in `app/config/settings.py`:
-
-```python
-CWE_URL = env('CWE_URL', 'https://cwe.mitre.org/data/definitions/')
+All the environment variables are in a `.env` file, there is an `.env.example` with all the variables needed. Also there are collected in `app/config/settings.py`
+Suggested minimum `.env` adjustments for local dev
+- Set SECRET_KEY, DB credentials, and admin user credentials.
+- Leave VirusTotal / DefectDojo disabled unless you have valid API keys and services available.
 
-MALWARE_ENABLED = env('MALWARE_ENABLED', True)
-MALWAREDB_URL = env('MALWAREDB_URL', 'https://www.malwaredomainlist.com/mdlcsv.php')
-MALTRAILDB_URL = env('MALTRAILDB_URL', 'https://raw.githubusercontent.com/stamparm/aux/master/maltrail-malware-domains.txt')
-
-VIRUSTOTAL_ENABLED = env('VIRUSTOTAL_ENABLED', False)
-VIRUSTOTAL_URL = env('VIRUSTOTAL_URL', 'https://www.virustotal.com/')
-VIRUSTOTAL_FILE_URL = env('VIRUSTOTAL_FILE_URL', 'https://www.virustotal.com/gui/file/')
-VIRUSTOTAL_API_URL_V3 = env('VIRUSTOTAL_API_URL_V3', 'https://www.virustotal.com/api/v3/')
-VIRUSTOTAL_URL_V2 = env('VIRUSTOTAL_API_URL_V2', 'https://www.virustotal.com/vtapi/v2/file/')
-VIRUSTOTAL_API_KEY = env('VIRUSTOTAL_API_KEY', '')
-VIRUSTOTAL_UPLOAD = env('VIRUSTOTAL_UPLOAD', False)
-
-DEFECTDOJO_ENABLED = env('DEFECTDOJO_ENABLED', False)
-DEFECTDOJO_URL = env('DEFECTDOJO_URL', 'http://defectdojo:8080/finding/')
-DEFECTDOJO_API_URL = env('DEFECTDOJO_API_URL', 'http://defectdojo:8080/api/v2/')
-DEFECTDOJO_API_KEY = env('DEFECTDOJO_API_KEY', '')
-```
+### Contributing
 
 If you like to contribute, see [Contributing](CONTRIBUTING.md)
 
----
+---