Merge branch 'master' into port-MASTG-TEST-0033

Author: Diolor

.github/instructions/mastg-best-practice.instructions.md

@@ -14,6 +14,12 @@ Scope and relationship to Knowledge:
 - Best Practices are prescriptive: they state what to do and why from a security perspective.
 - Keep background explanations minimal; for conceptual background on OS features, link to Knowledge pages under `knowledge/`.
 
+Relationship to Tests and Knowledge (nuance):
+
+- Tests (MASTG-TEST) describe the issue and "what can go wrong", then show how to detect it.
+- Knowledge (MASTG-KNOW) describes the feature/API neutrally (no "what can go wrong").
+- Best Practices (MASTG-BEST) explains how to prevent or mitigate the issue the tests detect.
+
 ### Markdown: Metadata
 
 Include a YAML front matter block with the following fields:
@@ -27,6 +33,7 @@ Optional metadata:
 - alias: URL-friendly slug (lowercase, hyphen-separated) used for navigation.
 - status: draft, placeholder, deprecated.
 - note: Short free-form note.
+- knowledge: One or more related Knowledge pages (`MASTG-KNOW-####`) for neutral background and API reference.
 - available_since: Minimum platform version/API level where this recommendation applies (Android: integer API level; iOS: release version, for example `13`).
 - deprecated_since: Last applicable platform/API level.
 
@@ -38,6 +45,7 @@ title: Preventing Screenshots and Screen Recording
 alias: preventing-screenshots-and-screen-recording
 id: MASTG-BEST-0014
 platform: android
+knowledge: [MASTG-KNOW-0105, MASTG-KNOW-0106, MASTG-KNOW-0107]
 ---
 ```
 

.github/instructions/mastg-demo.instructions.md

@@ -187,7 +187,7 @@ The rule has identified some instances in the code file where a non-random sourc
 
 #### Evaluation
 
-A concise explanation of how you applied the test’s “Evaluation” section to this demo. If lines are present in the observation, explain each relevant line.
+A concise explanation of how you applied the test’s "Evaluation" section to this demo. If lines are present in the observation, explain each relevant line.
 
 Example:
 

.github/instructions/mastg-knowledge.instructions.md

@@ -1,6 +1,21 @@
 ## Knowledge Articles
 
-Authoring standards for the Knowledge articles under `knowledge/`. Knowledge pages explain Android or iOS features and concepts that tests and techniques rely on. They are descriptive, not prescriptive: do not include security recommendations here. Best practices belong in `best-practices/`.
+Authoring standards for the Knowledge articles under `knowledge/`.
+
+Knowledge pages explain Android or iOS features and concepts that tests and techniques rely on.
+
+Scope boundaries (this is important for consistency across the project):
+
+- Knowledge (MASTG-KNOW) is descriptive: what the thing is, what it does, how it works, and what APIs/configuration knobs exist.
+- Tests (MASTG-TEST) are issue-focused: what can go wrong with that thing in apps, and how to detect it.
+- Best Practices (MASTG-BEST) are prescriptive: how to prevent or fix the issues that tests look for.
+
+Because of this separation, do not include "what can go wrong", threat scenarios, failure criteria, or remediation advice in Knowledge pages.
+
+Avoid language and structures that imply security testing or remediation, for example:
+
+- "attackers can …", "this is insecure …", "this is vulnerable …"
+- "the test fails if …", "to prevent this …", "you should/shouldn’t …"
 
 Locations and taxonomy:
 
@@ -53,7 +68,7 @@ Keep content authoritative, concise, and platform-focused. Avoid duplicating OS
 Considerations for writing the content:
 
 - Define the concept and its scope. Relate to OS components, APIs, or security model elements.
-- Explain typical security-relevant behaviors or implications of the feature without necessarily recommending mitigations (that's for "best practices").
+- Explain behavior and implications that are relevant to security testing without framing them as "risks" or "attacks". (Tests cover "what can go wrong"; Best Practices cover "what to do about it".)
 - Include specific API names, version nuances, storage locations, and configuration knobs. Try to avoid code samples. Instead, refer to the existing MASTG-DEMO code files. If you include them, keep them short and explanatory.
 - Use references from official docs and standards. Avoid non-authoritative sources.
 - In body text, reference internal MAS identifiers with a leading `@` (for example, @MASTG-KNOW-0001, @MASTG-TEST-0204, @MASTG-TECH-0014, @MASTG-TOOL-0031, MASWE-0089).
@@ -70,7 +85,7 @@ Considerations for writing the content:
 - Cross-category content: If a topic spans two MASVS categories, choose the best fit and reference the other in the body; avoid duplicate pages.
 - Generic vs platform: Concepts that are identical across platforms should be split into platform folders if platform detail matters; otherwise, place details where they differ and keep overviews succinct.
 - Where to place recommendations: Keep all prescriptive advice (do/don't, secure configuration values, mitigations) in Best Practices pages under `best-practices/`, and link them from the "Related" section.
-- When writing tests, techniques, or tools, always try to link to a knowledge article or create one if it's missing.
+- When writing tests, techniques, or tools, always try to link to a Knowledge article (and create one if it's missing). Tests should also link to Knowledge by using the `@MASTG-KNOW-xxxx` notation to make the relationship explicit.
 
 ## Deprecation
 

.github/instructions/mastg-mitmproxy-scripts.instructions.md

@@ -4,7 +4,7 @@ This guide defines how to write and use mitmproxy scripts in MASTG demos. Script
 
 ### Scope and terminology
 
-- “mitmproxy scripts” refers to Python addons for mitmproxy/mitmdump written against the mitmproxy scripting API.
+- "mitmproxy scripts" refers to Python addons for mitmproxy/mitmdump written against the mitmproxy scripting API.
 - Tools background (installation, proxy setup, certificates) lives in @MASTG-TOOL-0097 (mitmproxy). Do not duplicate setup steps here—link to the Tools page.
 - We use the command-line runner `mitmdump` in demos for reproducibility; `mitmweb` and the interactive `mitmproxy` UI are fine for exploration but not for demo automation.
 

.github/instructions/mastg-r2-scripts.instructions.md

@@ -4,7 +4,7 @@ This guide defines how to write and use radare2 scripts in MASTG demos. Scripts
 
 ### Scope and terminology
 
-- “r2 scripts” refers to radare2 command files executed with `-i <file>`.
+- "r2 scripts" refers to radare2 command files executed with `-i <file>`.
 - The repo uses `.r2` as the primary extension (for example, `cchash.r2`); variations like `.jr2` are not used in this repository.
 - Tools background lives under @MASTG-TOOL-0073 (radare2) and @MASTG-TOOL-0129 (rabin2). Do not duplicate setup or installation steps—link to Tools pages.
 

.github/instructions/mastg-test.instructions.md

@@ -23,6 +23,7 @@ Example tests for reference:
 Notes:
 
 - Tests with `platform: network` are still organized under the OS folder that the MASVS category belongs to (for example, Android network tests live under `tests-beta/android/MASVS-NETWORK/`).
+- Old tests under `tests/` do not follow these new guidelines. We are currently working to deprecate all of them in favor of these new approach. 
 
 Each test has two parts: the [Markdown metadata](#markdown-metadata) (YAML `front matter`) and the [Markdown body](#markdown-body).
 
@@ -40,16 +41,18 @@ Follow a consistent style across all test titles.
 
 **Conventions**
 
-- Static: “References to…” (semgrep/r2)
-- Dynamic: “Runtime Use …” (frida)
+- Static: "References to…" (semgrep/r2)
+- Dynamic: "Runtime Use …" (frida)
 
 Exceptions may apply where "Runtime ..." feels forced, for example, tests using adb, local backups, or filesystem snapshots.
 
 #### platform
 
-The mobile platform. One of the following: iOS, Android, or network.
+The mobile platform. One of the following:
 
-- Use network for platform-agnostic traffic analysis tests where the checks are performed purely on captured/observed traffic (often paired with type: [network]).
+- `android`
+- `ios`
+- `network`: for platform-agnostic traffic analysis tests where the checks are performed purely on captured/observed traffic (often paired with `type: [network]`).
 
 #### id
 
@@ -88,22 +91,16 @@ type: [dynamic, manual]
 
 #### best-practices
 
-Reference platform-specific mitigations or best practices. Automation generates a “Mitigations” section.
+Reference platform-specific mitigations or best practices. Automation generates a "Mitigations" section.
 
-New best practice files can be added under [best-practices/](https://github.com/OWASP/owasp-mastg/tree/master/best-practices).
+Reference the related `best-practices/` pages for background using their ID. Create the pages if they don't exist yet.
 
 Example:
 
 ```md
 best-practices: [MASTG-BEST-0001]
 ```
 
-This links to https://mas.owasp.org/MASTG/best-practices/MASTG-BEST-0001/
-
-Notes:
-
-- If no applicable best practices exist yet, you can omit the field or set an empty list: `best-practices: []`.
-
 #### prerequisites
 
 List the conditions that must be known or available before running or evaluating the test. These items capture internal context that only the developer or the organization can provide. Existing files are in the `prerequisites/` folder. Create new ones when needed.
@@ -126,8 +123,8 @@ prerequisites:
 
 #### profiles
 
-Specify the MASVS profiles to which the test applies. Valid values: L1, L2, P, R.
-The profiles are described in [MAS Testing Profiles Guide]( https://docs.google.com/document/d/1paz7dxKXHzAC9MN7Mnln1JiZwBNyg7Gs364AJ6KudEs/edit?tab=t.0#heading=h.il6q80u4fm3n)
+Specify the MAS profiles to which the test applies. Valid values: L1, L2, P, R.
+The profiles are described in [MAS Testing Profiles Guide](Document/0x03b-Testing-Profiles.md)
 
 - L1 denotes Essential Security.
 - L2 denotes Advanced Security.
@@ -140,6 +137,16 @@ Example:
 profiles: [L1, L2, P]
 ```
 
+#### knowledge
+
+Reference the related `knowledge/` pages for background using their ID. Create the pages if they don't exist yet.
+
+Example:
+
+```md
+knowledge: [MASTG-KNOW-0013]
+```
+
 #### optional fields
 
 Include these if relevant:
@@ -158,7 +165,22 @@ Notes:
 
 #### Overview
 
-The overview is platform-specific and extends the weakness overview with details on the area tested. It may mention specific APIs and features.
+The overview is platform-specific and extends the weakness overview with details on the area tested (the Knowledge items from the `knowledge` in the metadata).
+
+Very important: the overview must be phrased like an issue.
+
+- Describe the relevant platform feature/API from the perspective of "what can go wrong" (risk, failure mode, exposure).
+- Make it clear why the test exists: what the tester is trying to detect and why that matters.
+
+Do not repeat the weakness description here. Focus on the specific issue the test is checking for on the given platform.
+
+Good patterns for issue framing:
+
+- "If the app uses/implements/configures X, Y can happen …"
+- "This can lead to … (exposure, bypass, integrity failure, privacy leak) …"
+- "This test checks/verifies whether the app …"
+
+Do not write the overview like a neutral platform description. Neutral/descriptive explanations belong in `knowledge/`.
 
 Example:
 
@@ -198,7 +220,7 @@ Notes:
 
 The output you get after executing all steps. It serves as evidence.
 
-It MUST start with “The output should contain ...”.
+It MUST start with "The output should contain ...".
 
 Example:
 
@@ -212,7 +234,7 @@ The output should contain a list of locations where insecure random APIs are use
 
 Using the observation as input, describe how to evaluate it. State explicitly what makes the test fail.
 
-It MUST start with “The test case fails if ...”.
+It MUST start with "The test case fails if ...".
 
 Example:
 
@@ -221,3 +243,5 @@ Example:
 
 The test case fails if you can find random numbers generated using those APIs that are used in security-relevant contexts.
 ```
+
+IMPORTANT: Do not include remediation advice or best practices in the evaluation section. Remediation belongs in `best-practices/` and must be linked in the test metadata `best-practices`. If it does not exist yet, create it.

.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md

@@ -105,11 +105,11 @@ Review existing content and **UPDATE** it. Especially references to Android/iOS
 
 #### Best practices linkage
 
-Best practices are platform-specific and can be linked in the test metadata. Our automation creates a “Mitigations” section automatically.
+Best practices are platform-specific and must be linked in the test metadata. Our automation creates a "Mitigations" section automatically.
 
 1. Check if a best practice already exists in `best-practices/` folder
 2. If it doesn’t exist yet, create it new in `best-practices/` using the next available ID.
-3. Add a reference to the best practices with @MASTG-BEST-xxxx
+3. Add a reference to the best practices in the test YAML front matter, for example `best-practices: [MASTG-BEST-0023]`.
 
 #### Deprecating V1 tests
 

.github/workflows/docgenerator.yml

@@ -25,6 +25,8 @@ jobs:
     - uses: actions/setup-python@v5
       with:
         python-version: 3.x
+    - name: Install system dependencies
+      run: sudo apt-get update && sudo apt-get install -y libxml2-dev libxslt1-dev
     - name: Install dependencies
       run: pip install -r src/scripts/requirements.txt
 

best-practices/MASTG-BEST-0001.md

@@ -3,6 +3,7 @@ title: Use Secure Random Number Generator APIs
 alias: android-use-secure-random
 id: MASTG-BEST-0001
 platform: android
+knowledge: [MASTG-KNOW-0013]
 ---
 
 Use a cryptographically secure pseudorandom number generator as provided by the platform or programming language you are using.

best-practices/MASTG-BEST-0002.md

@@ -3,6 +3,7 @@ title: Remove Logging Code
 alias: remove-logging-code
 id: MASTG-BEST-0002
 platform: android
+knowledge: [MASTG-KNOW-0049]
 ---
 
 Ideally, a release build shouldn't use any logging functions, making it easier to assess sensitive data exposure.