From 7f895748fa3f7311b57fb87c1d3fa597858c5651 Mon Sep 17 00:00:00 2001 From: Carlos Date: Sun, 31 Aug 2025 23:30:22 +0200 Subject: [PATCH 01/20] Add markdown content rules and formatting guidelines --- .github/instructions/markdown.instructions.md | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 .github/instructions/markdown.instructions.md diff --git a/.github/instructions/markdown.instructions.md b/.github/instructions/markdown.instructions.md new file mode 100644 index 00000000000..b8f7bb789c7 --- /dev/null +++ b/.github/instructions/markdown.instructions.md @@ -0,0 +1,134 @@ +--- +description: 'Documentation and content creation standards' +applyTo: '**/*.md' +--- + +## Markdown Content Rules + +The following markdown content rules are enforced in the validators: + +1. **Headings**: Use appropriate heading levels (H2, H3, etc.) to structure your content. Do not use an H1 heading, as this will be generated based on the title. +2. **Lists**: Use bullet points or numbered lists for lists. Ensure proper indentation and spacing. +3. **Code Blocks**: Use fenced code blocks for code snippets. Specify the language for syntax highlighting. +4. **Links**: Use standard Markdown link syntax. +5. **Images**: Use HTML `` tags for images. See the "Images" section for examples and guidelines. +6. **Tables**: Use markdown tables for tabular data. Ensure proper formatting and alignment. +8. **Whitespace**: Use appropriate whitespace to separate sections and improve readability. +9. **Front Matter**: Include YAML front matter at the beginning of the file with required metadata fields. + +## Formatting and Structure + +Follow these guidelines for formatting and structuring your markdown content: + +- **Headings**: Use `##` for H2 and `###` for H3. Ensure that headings are used in a hierarchical manner. Recommend restructuring if content includes H4, and more strongly recommend for H5. +- **Lists**: Use `-` for bullet points and `1.` for numbered lists. Indent nested lists with four spaces to match the linter configuration. Prefer dashes `-` over asterisks `*` for unordered lists. Generally: + - Limit a single list to at most nine items when reasonable. + - Avoid more than two levels of nesting. + - Punctuate and capitalize list items consistently. Do not add end punctuation to list items that are not complete sentences unless they complete the introductory sentence. If list items complete an introductory sentence, end each (except the last) with a comma, omit the "and" before the last, and end the last with appropriate punctuation. +- **Code Blocks**: Use triple backticks to create fenced code blocks. Specify the language after the opening backticks for syntax highlighting (e.g., kt, java, xml). +- **Links**: Ensure the link text is descriptive and the URL is valid. +- **Tables**: Use `|` to create tables. Ensure that columns are properly aligned and headers are included. + - Include leading and trailing pipes to conform to the linter setting (MD055: `leading_and_trailing`). +- **Line Length**: There is no enforced hard limit. +- **Whitespace**: Use blank lines to separate sections and improve readability. Avoid excessive whitespace. + +### Writing Style and Tone + +- Keep content factual, brief, and focused. Avoid duplicating other sections of the guide and refrain from advertising commercial tools or services. +- Address the reader directly in the second person ("you"). Prefer active voice over passive voice. +- Ensure cohesion and coherence: link ideas logically; keep each paragraph focused on one idea; lead sections with the key point; use bullet points for scannability when appropriate. +- Write for an international audience with a basic technical background. Avoid hard-to-translate slang. +- Provide context and orientation: use a unique page heading, a concise introduction, and links to background information where helpful. + +### Content Length and Organization + +- Use short, scannable pages where possible (roughly one to two screens of text). For very large sections, consider moving details to a supporting document and link to it. +- For digital content, favor shorter, cross-linked pages. If the content is intended for print, longer, comprehensive pages are acceptable. + +### Gender Neutrality + +- Avoid gendered pronouns (she/her/hers/herself, he/him/his/himself) and constructions like "he/she", "s/he", "his or her". +- Prefer alternatives: + - Omit the pronoun where possible. + - Use articles ("the", "a") where appropriate. + - Use plural nouns and pronouns ("they") when it improves clarity. + - Use the second person ("you") or imperative form. + +### Language and Conventions + +- Use American spelling and terminology. +- Title capitalization follows the Chicago Manual of Style: + - Capitalize first and last words; nouns, pronouns, verbs, adjectives, adverbs, and subordinating conjunctions. + - Lowercase articles, prepositions, and coordinating conjunctions (except when first or last). +- Numbers: spell out zero through ten; use numerals for numbers greater than ten. +- Android versions: write as "Android X (API level YY)" and avoid codenames. +- Contractions: prefer common contractions (e.g., "don't", "can't", "it's"). + +### Abbreviations + +- On first use, spell out the term followed by the abbreviation in parentheses; use the abbreviation alone on subsequent uses within the chapter. +- If the term appears only once, prefer the full term instead of the abbreviation. +- In titles/headings, abbreviations are acceptable, but introduce them properly in the following text. +- Use "a" or "an" based on pronunciation (e.g., a URL, an APK). +- Form plurals by adding "s" unless the abbreviation already represents a plural noun (e.g., APIs, CSS). +- For common file formats like APK, IPA, or ZIP, do not prefix with a dot unless referring explicitly to the file extension. + +### In-project Identifiers + +Use special identifiers to reference project components consistently: + +- Tests: `@MASTG-TEST-0001` +- Tools: `@MASTG-TOOL-0034` +- Similar patterns may exist for other entities (e.g., best practices, techniques) following `@MASTG--NNNN`. +- Weaknesses: `@MASWE-0123` (this one is an exception to the usual pattern) + +Usage rules: + +- In body text (Markdown content), include the leading `@` when referencing an item. +- In YAML front matter, omit the `@` and use the bare identifier (e.g., `MASTG-TEST-0001`). + +Examples: + +```markdown +You can validate this with @MASTG-TEST-0001 and compare results using @MASTG-TOOL-0034. +``` + +```yaml +weakness: MASWE-0069 +best-practices: [MASTG-BEST-0010, MASTG-BEST-0011, MASTG-BEST-0012] +``` + +### Punctuation and Typographic Conventions + +- After a colon, lowercase the first word unless it is a proper noun or starts two or more complete sentences or a direct question. +- Use the serial comma (Oxford comma). +- Use straight quotes and apostrophes (not curly quotes/apostrophes). +- Never use Horizontal rules like `---`. +- Emphasis/strong style: underscores for emphasis (`_text_`), asterisks for strong (`**text**`). +- Trailing punctuation allowed in headings (MD026) is limited to: `.,;:` +- Always prefer commas or parentheses over em-dashes, en-dashes or hyphens. + +## Images + +For MASTG chapters and related content, always embed pictures using an HTML `` element rather than Markdown image syntax: + +- Put `src` as the first attribute. +- Optionally specify a `width` (e.g., `width="80%"`). +- Store images in the appropriate directory (e.g., `Document/Images/Chapters` for MASTG chapters). +- Inline HTML is permitted; the linter rule MD033 is disabled to allow this. + +Example: + +```markdown + +``` + +Note: The linter does not require alt text for images (MD045 disabled); however, include descriptive context in the surrounding text when helpful for accessibility. + +## Validation Requirements + +Ensure compliance with the following validation requirements: + +- **Content Rules**: Ensure that the content follows the markdown content rules specified above. +- **Formatting**: Ensure that the content is properly formatted and structured according to the guidelines. +- **Validation**: Run the validation tools to check for compliance with the rules and guidelines. From df69d5a7b363b5ac9cf282b58fcd0b156974084e Mon Sep 17 00:00:00 2001 From: Carlos Holguera Date: Sun, 31 Aug 2025 23:51:00 +0200 Subject: [PATCH 02/20] initial content --- .../mastg-best-practice.instructions.md | 14 ++ .../instructions/mastg-demo.instructions.md | 208 ++++++++++++++++++ .../mastg-frida-scripts.instructions.md | 3 + .../instructions/mastg-rules.instructions.md | 46 ++++ .../instructions/mastg-test.instructions.md | 145 ++++++++++++ ...rting-mastg-v1-tests-to-v2.instructions.md | 193 ++++++++++++++++ 6 files changed, 609 insertions(+) create mode 100644 .github/instructions/mastg-best-practice.instructions.md create mode 100644 .github/instructions/mastg-demo.instructions.md create mode 100644 .github/instructions/mastg-frida-scripts.instructions.md create mode 100644 .github/instructions/mastg-rules.instructions.md create mode 100644 .github/instructions/mastg-test.instructions.md create mode 100644 .github/instructions/porting-mastg-v1-tests-to-v2.instructions.md diff --git a/.github/instructions/mastg-best-practice.instructions.md b/.github/instructions/mastg-best-practice.instructions.md new file mode 100644 index 00000000000..cad5186ccaa --- /dev/null +++ b/.github/instructions/mastg-best-practice.instructions.md @@ -0,0 +1,14 @@ +## Best Practices + +[https://mas.owasp.org/MASTG/best-practices/](https://mas.owasp.org/MASTG/best-practices/) +[https://github.com/OWASP/owasp-mastg/tree/master/best-practices](https://github.com/OWASP/owasp-mastg/tree/master/best-practices) + +Best practices must be linked to MASTG tests using the `best-practices:` key. + +They must have official references which may include the MASTG as long as it contains further references to e.g. Google/Apple docs or other official sources. + +Best Practices should contain: + +* what's the recommendation +* why is that good +* any caveats or considerations (e.g. "it's good to have it but remember it can be bypassed this way", etc.) \ No newline at end of file diff --git a/.github/instructions/mastg-demo.instructions.md b/.github/instructions/mastg-demo.instructions.md new file mode 100644 index 00000000000..509a8e9b9f3 --- /dev/null +++ b/.github/instructions/mastg-demo.instructions.md @@ -0,0 +1,208 @@ +## Demos + +A collection of demos (demonstrative examples) of the test that include working code samples and test scripts to ensure reproducibility and reliability. + +Demos live in `demos/android/` or `demos/ios/` under the corresponding MASVS category folder. Each demo has its own folder named using its ID and contains: + +* Markdown file: `MASTG-DEMO-xxx.md` +* Code samples (e.g. .kt, .swift, .xml, .plist) +* Testing code (e.g. sh, py) +* Output files (e.g. txt, sarif) + +**Language:** The samples are written in **Kotlin** or **Swift**, depending on the platform. In some cases, the samples will also include configuration files such as AndroidManifest.xml or Info.plist. + +**Decompiled Code:** If the sample can be decompiled, the decompiled code is also provided in the demo (e.g as a Java file on Android: `MastgTest_reversed.java`). This is useful for understanding the code in the context of the application. + +The **demos MUST WORK**. See [Code Samples](#code-samples). + +Demos are required to be **fully self-contained** and should **not rely on external resources or dependencies**. This ensures that the demos can be run independently and that the results are reproducible. They must be proven to work on the provided sample applications and must be tested thoroughly before being included in the MASTG. + +**Don't create demos for outdated OS versions** that aren't supported by the MASTG. The MASTestApp is meant to always be up to date and aligned with the versions supported by the MASTG, so as to avoid additional maintenance of the MASTestApp. However, you can include demos showcasing the "good case" in the metadata using `kind: pass` in certain cases where it can be helpful or educational. This is permitted as long as the demos work with the current version of the MASTestApp. + +Please specify the mobile platform version, IDE and version, device. + +Example: + +```sh +% ls -1 -F demos/android/MASVS-CRYPTO/MASTG-DEMO-0007 + +MASTG-DEMO-0007.md +MastgTest.kt +MastgTest_reversed.java +output.txt +run.sh* +``` + +### Markdown: Metadata + +#### title + +The title should concisely express what the demo is about. + +Example: + +`title: Common Uses of Insecure Random APIs` + +#### platform + +The mobile platform. Can be one of: ios, android. + +#### tools + +Tools used in the demo. + +They must be referenced using their IDs from [https://mas.owasp.org/MASTG/tools/](https://mas.owasp.org/MASTG/tools/) + +Example: + +`tools: [MASTG-TOOL-0031]` + +#### code + +The language in which the samples are written. + +Example: + +`code: [java]` + +### Markdown: Body + +#### Sample + +Shortly describe the sample and specify the exact sample files used using this notation: + +**Single file:** + +`{{ MastgTest.kt }}` + +**Multi-file rendered in tabs:** + +`{{ MastgTest.kt # MastgTest_reversed.java }}` + +Example: + +`### Sample` + +``The snippet below shows sample code that sends sensitive data over the network using the `HttpURLConnection` class. The data is sent to `https://httpbin.org/post` which is a dummy endpoint that returns the data it receives.`` + +`{{ MastgTest.kt # MastgTest_reversed.java }}` + +#### Steps + +A concise writeup following all steps from the test and including the relevant placeholders for testing code (e.g. SAST rules, run.sh files). + +Example: + +`### Steps` + +`Let's run our semgrep rule against the sample code.` + +`{{ ../../../../rules/mastg-android-non-random-use.yaml }}` + +`{{ run.sh }}` + +#### Observation + +A concise description of the observation for this specific demo including the relevant placeholders for output files (e.g. output.txt). + +Example: + +`### Observation` + +`The rule has identified some instances in the code file where a non-random source is used. The specified line numbers can be located in the original code for further investigation and remediation.` + +`{{ output.txt }}` + +#### Evaluation + +A concise explanation about how you applied the test “Evaluation” section to this specific demo. For example, if lines are present explain each line. + +Example: + +`### Evaluation` + +`Review each of the reported instances.` + +`- Line 12 seems to be used to generate random numbers for security purposes, in this case for generating authentication tokens.` +``- Line 17 is part of the function `get_random`. Review any calls to this function to ensure that the random number is not used in a security-relevant context.`` +`- Line 27 is part of the password generation function which is a security-critical operation.` + +``Note that line 37 did not trigger the rule because the random number is generated using `SecureRandom` which is a secure random number generator.`` + + +### + +### Code Samples {#code-samples} + +Code samples for demos **must be** **created using one of our test apps** to ensure consistency across demos and facilitate the review process: + +* [https://github.com/cpholguera/MASTestApp-Android](https://github.com/cpholguera/MASTestApp-Android) +* [https://github.com/cpholguera/MASTestApp-iOS](https://github.com/cpholguera/MASTestApp-iOS) + +Simply clone the repository and follow the instructions to run the apps on your local machine. You **must use these apps to validate the demos** before submitting them to the MASTG. + +#### File + +Must be a modified version of the original files in the apps’ repos: + +* Android: `app/src/main/java/org/owasp/mastestapp/MastgTest.kt` +* iOS: `MASTestApp/MastgTest.swift` + +When working on a new demo you **must include the whole file** with the original name in the demo folder. + +#### Summary + +Must contain a summary as a comment. + +Example: + +`// SUMMARY: This sample demonstrates different common ways of insecurely generating random numbers in Java.` + +#### Logic + +The file must include code that demonstrates the addressed weakness. +The provided default `MastgTest.kt` and `MastgTest.swift` contain some basic logic that will return a string to the UI. If possible try to return some meaningful string. + +For example, if you create a random number you can return it; or if you write files to the external storage you can return a list of file paths so that the user of the app can read them. You can also use that string to display some meaningful errors. + +#### Fail/Pass + +Must contain comments indicating fail/pass and the test alias. This way we're able to validate that the output is correct (e.g. the code contains 3 failures of `MASTG-TEST-0204`). We can easily parse and count the comments and we can do the same in the output. + +Each FAIL/PASS comment must include the test Id and an explanation of why it files/passes. + +Example: + +`// FAIL: [MASTG-TEST-0204] The app insecurely uses random numbers for generating authentication tokens.` +`return r.nextDouble();` + +`// PASS: [MASTG-TEST-0204] The app uses a secure random number generator.` +`return number.nextInt(21);` + +### run.sh + +Every test that can be automated must contain a run.sh file + +#### Static + +Static tests must work using the **reverse-engineered** **code**. The app’s repos contain scripts or indications to obtain the reversed files. + +Example: semgrep + +`NO_COLOR=true semgrep -c ../../../../rules/mastg-android-insecure-random-use.yaml ./MastgTest_reversed.java --text -o output.txt` + +#### Dynamic + +Example: frida-trace + +`frida-trace -U -f com.google.android.youtube --runtime=v8 -j '*!*certificate*/isu' > output.txt` + +Example: frida + +`frida -U sg.vp.owasp_mobile.omtg_android -l hook_edittext.js > output.txt` + +#### Networking + +Example: mitmproxy + +`mitmdump -s mitm_sensitive_logger.py` diff --git a/.github/instructions/mastg-frida-scripts.instructions.md b/.github/instructions/mastg-frida-scripts.instructions.md new file mode 100644 index 00000000000..3c534ac4d26 --- /dev/null +++ b/.github/instructions/mastg-frida-scripts.instructions.md @@ -0,0 +1,3 @@ +## Frida Scripts + +Demos must use Frida 17 and above, see https://mas.owasp.org/MASTG/tools/generic/MASTG-TOOL-0031/#frida-17 \ No newline at end of file diff --git a/.github/instructions/mastg-rules.instructions.md b/.github/instructions/mastg-rules.instructions.md new file mode 100644 index 00000000000..e0251187faa --- /dev/null +++ b/.github/instructions/mastg-rules.instructions.md @@ -0,0 +1,46 @@ +## Rules + +SAST rules live in `rules` folder. They can be referenced and reused by the demos. + +### Semgrep rules + +[https://semgrep.dev/docs/getting-started/quickstart/](https://semgrep.dev/docs/getting-started/quickstart/) +[https://semgrep.dev/learn](https://semgrep.dev/learn) +[https://academy.semgrep.dev/courses/secure-guardrails](https://academy.semgrep.dev/courses/secure-guardrails) + +Tip: use [https://semgrep.dev/playground/new](https://semgrep.dev/playground/new) for experimentation. + +They must be named `mastg-.yaml` and follow valid syntax according to [https://semgrep.dev/docs/writing-rules/rule-syntax/](https://semgrep.dev/docs/writing-rules/rule-syntax/) + +* **id**: same as the file name +* **severity**: + * WARNING + * ERROR +* **languages**: e.g. xaml, java (we don't create rules for kotlin as we only work with decompiled code which is in java) +* **metadata**: must include summary + * summary: Short description of the rule. + * original_source: you may use rules from sources on the internet be sure to check that the license allows this and always link to the original source here. Modify the rule if needed and the license allows for it. +* **message**: must start with the MASVS control ID and concisely explain what the rule is reporting. +* **patterns**: see [https://semgrep.dev/docs/writing-rules/pattern-syntax/](https://semgrep.dev/docs/writing-rules/pattern-syntax/) + +Do not include authors in the semgrep rules. If it was copied from some other place, **include the link to the original source**. Since many people will potentially contribute to the rule as part of the MASTG work, the authors will be calculated using git. + +Example: + +```yml +rules: + - id: mastg-android-insecure-random-use + severity: WARNING + languages: + - java + metadata: + summary: This rule looks for common patterns including classes and methods. + message: "[MASVS-CRYPTO-1] The application makes use of an insecure random number generator." + + pattern-either: + - patterns: + - pattern-inside: $M(...){ ... } + - pattern-either: + - pattern: Math.random(...) + - pattern: (java.util.Random $X).$Y(...) +``` \ No newline at end of file diff --git a/.github/instructions/mastg-test.instructions.md b/.github/instructions/mastg-test.instructions.md new file mode 100644 index 00000000000..f378ab7436b --- /dev/null +++ b/.github/instructions/mastg-test.instructions.md @@ -0,0 +1,145 @@ +## Tests + +Tests are platform-specific and must be located under tests-beta/android/ or tests-beta/ios/, within the corresponding MASVS category. Their file names are the test IDs. + +Tests have an overview and contain Steps which produce outputs called observations: after following the Steps you come up with an [Observation](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1#heading=h.h9gqgz4hdubj) which you will [Evaluate](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1#heading=h.lare0v58fwbf). + +Example: + +`% ls -1 -F tests-beta/android/MASVS-CRYPTO/` +`MASTG-TEST-0204.md` +`MASTG-TEST-0205.md` + +### Markdown: Metadata + +#### title + +Test titles should be concise and clearly state the purpose of the test. + +In some cases, the test name and the weakness may have the same title, but typically the tests will test different aspects of a weakness (as defined in "Modes of introduction"), so the titles need to reflect that. + +Avoid including Android or iOS in the titles unless absolutely necessary, as in "Insecure use of the Android Protected Confirmation API". + +Please ensure that the titles follow a similar structure and style to other titles in the dataset. + +##### **Conventions** + +* **Static**: “References to…” (semgrep/r2) +* **Dynamic**: “Runtime Use …” (frida) + +We currently consider some exceptions to this convention for “dynamic tests” where it would feel forced to start it with "Runtime ...". For example, when the test is based on using tools like adb (e.g. to perform a local backup), performing file system snapshots, etc. + +Examples include: + +* [MASTG-TEST-0207](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0207/) +* [MASTG-TEST-0216](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0216/) +* [MASTG-TEST-0263](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0263/) + +platform +The mobile platform. Can be one of: ios, android. + +#### id + +The ID of the test + +#### weakness + +The MASWE weakness ID the test is referencing. + +#### + +#### type + +A test can have one or more types. + +Supported types: static, dynamic, network, manual. + +Example: + +`type: [static]` + +#### mitigations + +Use mitigations in the test metadata to add platform specific mitigations or best practices. Our automation will create a “Mitigations” section automatically. + +You can create new best practice files under [best-practices/](https://github.com/OWASP/owasp-mastg/tree/master/best-practices) and use them as mitigations. + +Example: + +`mitigations: [MASTG-BEST-0001]` + +This will create a link to [https://mas.owasp.org/MASTG/best-practices/MASTG-BEST-0001/](https://mas.owasp.org/MASTG/best-practices/MASTG-BEST-0001/) + +#### prerequisites + +Link to any prerequisites needed for executing or evaluating the test. + +Existing prerequisites are in the prerequisites/ folder. Create new ones if required. + +For example, for evaluating the results of the test you may need to have identified the sensitive data relevant to your app. + +Example: + +`prerequisites:` +`- identify-sensitive-data` +`- identify-security-relevant-contexts` + +### + +### Markdown: Body + +#### Overview + +The overview of a test is platform-specific and acts as an extension of the weakness overview for the particular area covered by the test. It may mention specific APIs and platform features. + +Example: + +`## Overview` + +``Android apps sometimes use insecure pseudorandom number generators (PRNGs) such as `java.util.Random`, which is essentially a linear congruential generator. This type of PRNG generates a predictable sequence of numbers for any given seed value, making the sequence reproducible and insecure for cryptographic use. In particular, `java.util.Random` and `Math.random()` ([the latter](https://franklinta.com/2014/08/31/predicting-the-next-math-random-in-java/) simply calling `nextDouble()` on a static `java.util.Random` instance) produce identical number sequences when initialized with the same seed across all Java implementations.`` + +#### Steps + +A test must include one or more steps that can be static, dynamic, both. Previously in the MASTG we were forcing one or the other and sometimes mention that you can do both. But usually the steps will be mixed. + +For example, to "check app notifications" + +1. method trace for related APIs (dynamic) +2. use the app (manual) +3. RE to understand use or use backtraces & more hooking (static) +4. taint analysis using known/self-defined values and letting them get to the notification (dynamic) +5. grep the method trace or integrate "grep" in a frida script (static/dynamic) + +Example: + +`## Steps` + +`1. Run a [static analysis](/MASTG/techniques/android/MASTG-TECH-0014.md) tool on the app and look for insecure random APIs.` + +**Always link to existing techniques** (or create new ones if they don’t exist yet) to prevent duplication or repetition of content. In this example: techniques/android/MASTG-TECH-0014.md + +#### Observation + +This is the output you get after executing all steps. It serves as evidence. + +Examples: method trace for specific APIs, network traffic trace filtered in some way, hooking events containing sensitive data (indicating which APIs handle that data). + +It should start with “The output should contain …”. + +Example: + +`## Observation` + +`The output should contain a **list of locations where insecure random APIs are used**.` + +#### Evaluation + +Using the observation as input, the evaluation tells you how to evaluate it and must explicitly describe what makes the test fail. + +It should start with “The test case fails if …” + +Example: + +`## Evaluation` + +`The test case fails if you can find random numbers generated using those APIs that are used in security-relevant contexts.` \ No newline at end of file diff --git a/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md b/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md new file mode 100644 index 00000000000..93af7f2aa35 --- /dev/null +++ b/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md @@ -0,0 +1,193 @@ +# Porting MASTG v1 Tests to v2 + +### Writing content + +Check some of the current tests and take them as reference + +* tests-beta +* demos + +Always take the most recent tests (the ones with the highest IDs) as reference/template. + +Also review these. We’ll be using them and creating new ones as well: + +* [https://mas.owasp.org/MASTG/techniques/](https://mas.owasp.org/MASTG/techniques/) +* [https://mas.owasp.org/MASTG/tools/](https://mas.owasp.org/MASTG/tools/) + +#### Guidelines + +* How to write new **tests**: [Writing MAS Weaknesses & Tests](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1&tab=t.0#heading=h.j1tiymiuocrm) +* How to write **demos**: [Writing MAS Weaknesses & Tests](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1&tab=t.0#heading=h.y294y561hx14) + +**Important** tips and guidelines: + +1. Create a rough draft. + 1. In most cases you’ll have something in the v1 test + 2. Sometimes you can take the whole test or just a sentence or bullet point. + 3. You may use [chatGPT](https://chat.openai.com/) to create an initial draft and massage the content. +2. Edit it yourself using **your knowledge** +3. **Always include inline references** e.g. to + 1. MASTG chapters + 2. APIs + 3. statements in the dev docs +4. Before pushing, use [deepl write](https://www.deepl.com/en/write) to correct any mistakes and tweak phrasing (especially if you used chatGPT, use deepl to humanize the text) + +**About the IDs:** + +* Turn MASTG-TEST-0017 \-\> MASTG-TEST-0x17 +* If you need to split then do like MASTG-TEST-0x17-1, MASTG-TEST-0x17-2, MASTG-TEST-0x17-3 … +* We’ll take care of fixing the IDs before merging. + +**Language**: use simple language, be concise and clear + +- Avoid passive voice +- Avoid long and complex sentences + - **bad** "In order to encrypt data, Android offers the following Android APIs". + - **good**: "You can use these APIs to encrypt data." +- See [Style Guide \- OWASP Mobile Application Security](https://mas.owasp.org/contributing/5_Style_Guide/) + +#### List of sources + +Use the MASTG first, e.g. the guides for 0x04 (general), 0x05 (Android) and 0x06 (iOS) and **extend** with android/apple docs. + +**Android** + +- [https://developer.android.com/privacy-and-security/security-tips](https://developer.android.com/privacy-and-security/security-tips) +- [https://developer.android.com/privacy-and-security/security-best-practices](https://developer.android.com/privacy-and-security/security-best-practices) +- [https://developer.android.com/privacy-and-security/risks](https://developer.android.com/privacy-and-security/risks) (these have special treatment in the metadata) +- [https://developer.android.com/privacy-and-security/about](https://developer.android.com/privacy-and-security/about) +- [https://developer.android.com/docs/quality-guidelines/core-app-quality\#sc](https://developer.android.com/docs/quality-guidelines/core-app-quality#sc) + +**iOS** + +- [https://developer.apple.com/app-store/user-privacy-and-data-use/](https://developer.apple.com/app-store/user-privacy-and-data-use/) + +## Porting tests to V2 + +Map to MASWE. You can check the new MASWE by searching for the old test ID in the **weaknesses/** directory. For example MASTG-TEST-0017. + +Create a branch for the ticket: port-MASTG-TEST-0017 + +If the “MASVS” folder does not exist yet, create it. + +Name the new file MASTG-TEST-0x17.md \-\> We’ll use the x to avoid ID collision and we’ll rename them later. + +* Turn MASTG-TEST-0017 \-\> MASTG-TEST-0x17 +* If you need to split then do like MASTG-TEST-0x17-1, MASTG-TEST-0x17-2, MASTG-TEST-0x17-3 … + +One test in V1 may be turned into one or multiple tests in v2. Sometimes you'll find one sentence and that can be converted into a new test. + +Search for references in the current **Document/** + +And add them as + +`["Confirm Credential Flow"](../../../Document/0x05f-Testing-Local-Authentication.md#confirm-credential-flow)` + +We don’t want to duplicate information. You may summarize part of the other section but what’s important is to explain what can go wrong with that feature or API. That may be explained in the referenced section or not but it must be in the test because that’s gonna be what we’re going to test for. + +The thing we’re testing for must also have a very specific mitigation. + +Part of the test not relevant? Remove and add a note in the ticket. + +**Example:** In MASTG-TEST-0017, what’s written in dynamic analysis does not make sense: why should we validate that setUserAuthenticationValidityDurationSeconds are for real (we are not testing if Android features work; we assume they do). Maybe we could also use dynamic analysis but following a different approach. + +Add missing links to docs. + +**Example:** this test and the referenced section both were missing links to [https://developer.android.com/](https://developer.android.com/) + +## Important to consider when working on a test + +V1 tests may include **techniques**, **tools** and even theory. Move that Info to the right place or create it and use references. e.g. @MASTG-TECH-0002 + +Theory must be always linked to the 0x04/5/6 chapters. + +Review existing content and **UPDATE** it. Especially references to Android/iOS versions and things you know have changed since the text was written. + +#### Add Best Practices + +Best practices are platform specific and can 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 + +#### Deprecating V1 tests + +Add metadata: + +`"status: deprecated"` +`"covered_by: [MASTG-TEST-02xx]" (leave empty if no coverage)` +`deprecation_note: "New version available in MASTG V2"` +If the test isn’t covered in MASVS v2, enter the reason why. + +If you don't know, open a ticket "Add Deprecation Note for MASTG-TEST-01xx". + +### Threat based + +Some things we're testing are only an issue if you consider an attacker with root access (typically L2 weaknesses). Double check that the conditions of the test matches the profile of the associated MASWE. IF THERE'S A MISMATCH WE MAY CREATE A SEPARATE MASWE FOR IT BECAUSE IT REPRESENTS A DIFFERENT RISK. + +[https://mas.owasp.org/MASTG/tests/android/MASVS-PLATFORM/MASTG-TEST-0010/\#dynamic-analysis](https://mas.owasp.org/MASTG/tests/android/MASVS-PLATFORM/MASTG-TEST-0010/#dynamic-analysis) + +Pay special attention to things like this. Indicate if the thing you're testing for requires root to be exploited or not. + +*On devices supporting file-based encryption (FBE) ↗, snapshots are stored in the /data/system\_ce/\/\ folder. \ depends on the vendor but most common names are snapshots and recent\_images. If the device doesn't support FBE, the /data/system/\ folder is used.* + +Accessing these folders and the snapshots requires root. + +EXAMPLE: cleartext configured globally in NSC. No need for root, network/mitm: yes + +What other things to consider here? + +- **binary**: possible just because the attacker has the binary (decrypted on iOS) +- **app**: another app on the device with the right permissions (e.g. full access to external storage) +- **mitm**: a network based attacker capable of performing MITM +- **user computer**: the user using adb +- **user UI**: using the app's or another app’s UI, e.g. third party file manager; +- **user confirmation**: e.g. pasteboard confirmation + +### Code Snippets + +If the test has snippets, you can use them for the new demos. Rewrite any existing snippets and AVOID JAVA AND OBJECTIVE C. + +You can create a demo **status: draft** and come back later to it. Just to ensure we extracted everything from V1. Create a ticket **"Finish Demo Draft MASTG-DEMO-xxxx"** + +- [https://github.com/WithSecureLabs/sieve/](https://github.com/WithSecureLabs/sieve/) +- Ovaa +- MASTG playground +- [https://mas.owasp.org/MASTG/apps/](https://mas.owasp.org/MASTG/apps/) + +List of apps to get ideas from, as inspiration. You may include "inspired by" to ref to the original source whenever our new content is similar enough. + +### NOTES + +* platform: android, ios or network +* +* A test MUST NOT describe the general problem *again*. That’s the Weakness’ job. Focus on how that thing happens in Android / iOS and why it’s important to do this test. +* A test can be \[static, dynamic\] and the steps are describing both + * Example: MASTG-TEST-0209 + * 1\. Run a static analysis tool such as @MASTG-TOOL-0073 on the app binary, or use a dynamic analysis tool like @MASTG-TOOL-0039, and look for uses of the cryptographic functions that generate keys. + * The demos are going to be more specific and address static and dynamic separately + * If you find an edge case, let’s discuss it. + * e.g. just because *the way* something is tested it could deserve a separate test with its own distinct overview, steps, etc. + +### OS version + +**For Android:** We have agreed on supporting the **current version \- 5**. This gives a roughly 90% adoption rate on average. See [https://apilevels.com/](https://apilevels.com/) + +If a test is not applicable anymore in some OS versions we can create it with a note of the versions where it applies. This way if you're testing an app that has a minsdk greater than that, you can discard that test. + +We will avoid creating demos for unsupported versions. + +e.g. webviews file access or defaults depend on this. + +```md +--- +platform: android +title: Insecure Implementation of Confirm Credentials +id: MASTG-TEST-0x017 +type: [static, dynamic] +available_since: 21 +deprecated_since: 29 +weakness: MASWE-0034 +--- +``` \ No newline at end of file From 929918abd6e023aefa8104a0ea74072e98c13e3d Mon Sep 17 00:00:00 2001 From: Carlos Date: Mon, 1 Sep 2025 00:10:19 +0200 Subject: [PATCH 03/20] Refine test instructions for clarity and consistency in formatting --- .../instructions/mastg-test.instructions.md | 149 +++++++++++------- 1 file changed, 89 insertions(+), 60 deletions(-) diff --git a/.github/instructions/mastg-test.instructions.md b/.github/instructions/mastg-test.instructions.md index f378ab7436b..726adcbe99a 100644 --- a/.github/instructions/mastg-test.instructions.md +++ b/.github/instructions/mastg-test.instructions.md @@ -2,13 +2,15 @@ Tests are platform-specific and must be located under tests-beta/android/ or tests-beta/ios/, within the corresponding MASVS category. Their file names are the test IDs. -Tests have an overview and contain Steps which produce outputs called observations: after following the Steps you come up with an [Observation](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1#heading=h.h9gqgz4hdubj) which you will [Evaluate](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1#heading=h.lare0v58fwbf). +Tests have an overview and contain Steps which produce outputs called observations. After following the Steps you come up with an [Observation](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1#heading=h.h9gqgz4hdubj) which you will [Evaluate](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1#heading=h.lare0v58fwbf). Example: -`% ls -1 -F tests-beta/android/MASVS-CRYPTO/` -`MASTG-TEST-0204.md` -`MASTG-TEST-0205.md` +```sh +% ls -1 -F tests-beta/android/MASVS-CRYPTO/ +MASTG-TEST-0204.md +MASTG-TEST-0205.md +``` ### Markdown: Metadata @@ -16,130 +18,157 @@ Example: Test titles should be concise and clearly state the purpose of the test. -In some cases, the test name and the weakness may have the same title, but typically the tests will test different aspects of a weakness (as defined in "Modes of introduction"), so the titles need to reflect that. +In some cases, the test name and the weakness may have the same title, but typically tests cover different aspects of a weakness. Titles should reflect that. -Avoid including Android or iOS in the titles unless absolutely necessary, as in "Insecure use of the Android Protected Confirmation API". +Avoid including Android or iOS unless necessary, as in "Insecure use of the Android Protected Confirmation API". -Please ensure that the titles follow a similar structure and style to other titles in the dataset. +Follow a consistent style across all test titles. -##### **Conventions** +**Conventions** -* **Static**: “References to…” (semgrep/r2) -* **Dynamic**: “Runtime Use …” (frida) +- Static: “References to…” (semgrep/r2) +- Dynamic: “Runtime Use …” (frida) -We currently consider some exceptions to this convention for “dynamic tests” where it would feel forced to start it with "Runtime ...". For example, when the test is based on using tools like adb (e.g. to perform a local backup), performing file system snapshots, etc. +Exceptions may apply where "Runtime ..." feels forced, for example tests using adb, local backups, or filesystem snapshots. -Examples include: +Examples: -* [MASTG-TEST-0207](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0207/) -* [MASTG-TEST-0216](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0216/) -* [MASTG-TEST-0263](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0263/) +- [MASTG-TEST-0207](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0207/) +- [MASTG-TEST-0216](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0216/) +- [MASTG-TEST-0263](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0263/) -platform -The mobile platform. Can be one of: ios, android. +#### platform -#### id +The mobile platform. One of: ios, android. -The ID of the test +#### id -#### weakness +The test ID. -The MASWE weakness ID the test is referencing. +#### weakness -#### +The MASWE weakness ID the test references. #### type -A test can have one or more types. +One or more test types. -Supported types: static, dynamic, network, manual. +Supported: static, dynamic, network, manual, filesystem. Example: -`type: [static]` +```md +type: [static] +``` -#### mitigations +#### best-practices -Use mitigations in the test metadata to add platform specific mitigations or best practices. Our automation will create a “Mitigations” section automatically. +Reference platform-specific mitigations or best practices. Automation generates a “Mitigations” section. -You can create new best practice files under [best-practices/](https://github.com/OWASP/owasp-mastg/tree/master/best-practices) and use them as mitigations. +New best practice files can be added under [best-practices/](https://github.com/OWASP/owasp-mastg/tree/master/best-practices). Example: -`mitigations: [MASTG-BEST-0001]` +```md +best-practices: [MASTG-BEST-0001] +``` -This will create a link to [https://mas.owasp.org/MASTG/best-practices/MASTG-BEST-0001/](https://mas.owasp.org/MASTG/best-practices/MASTG-BEST-0001/) +This links to https://mas.owasp.org/MASTG/best-practices/MASTG-BEST-0001/ #### prerequisites -Link to any prerequisites needed for executing or evaluating the test. +List prerequisites needed to execute or evaluate the test. Existing files are in prerequisites/. Create new ones if needed. + +Example: + +```md +prerequisites: +- identify-sensitive-data +- identify-security-relevant-contexts +``` -Existing prerequisites are in the prerequisites/ folder. Create new ones if required. +#### profiles -For example, for evaluating the results of the test you may need to have identified the sensitive data relevant to your app. +Specify MASVS profiles where the test applies. Valid values: L1, L2, P. Example: -`prerequisites:` -`- identify-sensitive-data` -`- identify-security-relevant-contexts` +```md +profiles: [L1, L2, P] +``` -### +#### optional fields + +Include these if relevant: + +- `status:` draft, placeholder, deprecated +- `note:` short free-form note +- `available_since:` minimum platform/API level +- `deprecated_since:` last applicable platform/API level ### Markdown: Body #### Overview -The overview of a test is platform-specific and acts as an extension of the weakness overview for the particular area covered by the test. It may mention specific APIs and platform features. +The overview is platform-specific and extends the weakness overview with details on the area tested. It may mention specific APIs and features. -Example: +Example: -`## Overview` +```md +## Overview -``Android apps sometimes use insecure pseudorandom number generators (PRNGs) such as `java.util.Random`, which is essentially a linear congruential generator. This type of PRNG generates a predictable sequence of numbers for any given seed value, making the sequence reproducible and insecure for cryptographic use. In particular, `java.util.Random` and `Math.random()` ([the latter](https://franklinta.com/2014/08/31/predicting-the-next-math-random-in-java/) simply calling `nextDouble()` on a static `java.util.Random` instance) produce identical number sequences when initialized with the same seed across all Java implementations.`` +Android apps sometimes use insecure pseudorandom number generators (PRNGs) such as `java.util.Random`, which is essentially a linear congruential generator. This type of PRNG generates a predictable sequence of numbers for any given seed value, making the sequence reproducible and insecure for cryptographic use. In particular, `java.util.Random` and `Math.random()` ([the latter](https://franklinta.com/2014/08/31/predicting-the-next-math-random-in-java/) simply calling `nextDouble()` on a static `java.util.Random` instance) produce identical number sequences when initialized with the same seed across all Java implementations. +``` #### Steps -A test must include one or more steps that can be static, dynamic, both. Previously in the MASTG we were forcing one or the other and sometimes mention that you can do both. But usually the steps will be mixed. +A test must include one or more steps. Steps can be static, dynamic, manual, or mixed. -For example, to "check app notifications" +Example, to check app notifications: -1. method trace for related APIs (dynamic) -2. use the app (manual) -3. RE to understand use or use backtraces & more hooking (static) -4. taint analysis using known/self-defined values and letting them get to the notification (dynamic) -5. grep the method trace or integrate "grep" in a frida script (static/dynamic) +1. method trace for related APIs (dynamic) +2. use the app (manual) +3. reverse engineer code or use backtraces and hooks (static) +4. perform taint analysis with controlled values (dynamic) +5. grep traces or integrate "grep" in a frida script (static/dynamic) Example: -`## Steps` +```md +## Steps -`1. Run a [static analysis](/MASTG/techniques/android/MASTG-TECH-0014.md) tool on the app and look for insecure random APIs.` +1. Run @MASTG-TECH-0014 on the app and look for insecure random APIs. +``` -**Always link to existing techniques** (or create new ones if they don’t exist yet) to prevent duplication or repetition of content. In this example: techniques/android/MASTG-TECH-0014.md +Notes: -#### Observation +- Always link to existing techniques and tools by ID (for example, @MASTG-TECH-0014, @MASTG-TOOL-0031) to avoid duplication. +- In body text, use the leading @. In YAML front matter, omit the @ and use bare identifiers. -This is the output you get after executing all steps. It serves as evidence. +#### Observation -Examples: method trace for specific APIs, network traffic trace filtered in some way, hooking events containing sensitive data (indicating which APIs handle that data). +The output you get after executing all steps. It serves as evidence. It should start with “The output should contain …”. Example: -`## Observation` +```md +## Observation -`The output should contain a **list of locations where insecure random APIs are used**.` +The output should contain a list of locations where insecure random APIs are used. +``` #### Evaluation -Using the observation as input, the evaluation tells you how to evaluate it and must explicitly describe what makes the test fail. +Using the observation as input, describe how to evaluate it. State explicitly what makes the test fail. -It should start with “The test case fails if …” +It should start with “The test case fails if …”. Example: -`## Evaluation` +```md +## Evaluation -`The test case fails if you can find random numbers generated using those APIs that are used in security-relevant contexts.` \ No newline at end of file +The test case fails if you can find random numbers generated using those APIs that are used in security-relevant contexts. +``` From 3eb3af47e66e1cedd0c447628bbab2a384336b73 Mon Sep 17 00:00:00 2001 From: Carlos Date: Mon, 1 Sep 2025 00:10:44 +0200 Subject: [PATCH 04/20] Enhance markdown formatting in demo instructions for consistency and clarity --- .../instructions/mastg-demo.instructions.md | 76 ++++++++++++------- 1 file changed, 49 insertions(+), 27 deletions(-) diff --git a/.github/instructions/mastg-demo.instructions.md b/.github/instructions/mastg-demo.instructions.md index 509a8e9b9f3..b0fc95fedb0 100644 --- a/.github/instructions/mastg-demo.instructions.md +++ b/.github/instructions/mastg-demo.instructions.md @@ -41,7 +41,9 @@ The title should concisely express what the demo is about. Example: -`title: Common Uses of Insecure Random APIs` +```md +title: Common Uses of Insecure Random APIs +``` #### platform @@ -55,7 +57,9 @@ They must be referenced using their IDs from [https://mas.owasp.org/MASTG/tools/ Example: -`tools: [MASTG-TOOL-0031]` +```md +tools: [MASTG-TOOL-0031] +``` #### code @@ -63,7 +67,9 @@ The language in which the samples are written. Example: -`code: [java]` +```md +code: [java] +``` ### Markdown: Body @@ -73,19 +79,25 @@ Shortly describe the sample and specify the exact sample files used using this n **Single file:** -`{{ MastgTest.kt }}` +```md +{{ MastgTest.kt }} +``` **Multi-file rendered in tabs:** -`{{ MastgTest.kt # MastgTest_reversed.java }}` +```md +{{ MastgTest.kt # MastgTest_reversed.java }} +``` Example: -`### Sample` +```md +### Sample -``The snippet below shows sample code that sends sensitive data over the network using the `HttpURLConnection` class. The data is sent to `https://httpbin.org/post` which is a dummy endpoint that returns the data it receives.`` +The snippet below shows sample code that sends sensitive data over the network using the `HttpURLConnection` class. The data is sent to `https://httpbin.org/post` which is a dummy endpoint that returns the data it receives. -`{{ MastgTest.kt # MastgTest_reversed.java }}` +{{ MastgTest.kt # MastgTest_reversed.java }} +``` #### Steps @@ -93,13 +105,15 @@ A concise writeup following all steps from the test and including the relevant p Example: -`### Steps` +```md +### Steps -`Let's run our semgrep rule against the sample code.` +Let's run our semgrep rule against the sample code. -`{{ ../../../../rules/mastg-android-non-random-use.yaml }}` +{{ ../../../../rules/mastg-android-non-random-use.yaml }} -`{{ run.sh }}` +{{ run.sh }} +``` #### Observation @@ -107,11 +121,13 @@ A concise description of the observation for this specific demo including the re Example: -`### Observation` +```md +### Observation -`The rule has identified some instances in the code file where a non-random source is used. The specified line numbers can be located in the original code for further investigation and remediation.` +The rule has identified some instances in the code file where a non-random source is used. The specified line numbers can be located in the original code for further investigation and remediation. -`{{ output.txt }}` +{{ output.txt }} +``` #### Evaluation @@ -119,16 +135,17 @@ A concise explanation about how you applied the test “Evaluation” section to Example: -`### Evaluation` +```md +### Evaluation -`Review each of the reported instances.` +Review each of the reported instances. -`- Line 12 seems to be used to generate random numbers for security purposes, in this case for generating authentication tokens.` -``- Line 17 is part of the function `get_random`. Review any calls to this function to ensure that the random number is not used in a security-relevant context.`` -`- Line 27 is part of the password generation function which is a security-critical operation.` +- Line 12 seems to be used to generate random numbers for security purposes, in this case for generating authentication tokens. +- Line 17 is part of the function `get_random`. Review any calls to this function to ensure that the random number is not used in a security-relevant context. +- Line 27 is part of the password generation function which is a security-critical operation. -``Note that line 37 did not trigger the rule because the random number is generated using `SecureRandom` which is a secure random number generator.`` - +Note that line 37 did not trigger the rule because the random number is generated using `SecureRandom` which is a secure random number generator. +``` ### @@ -156,7 +173,9 @@ Must contain a summary as a comment. Example: -`// SUMMARY: This sample demonstrates different common ways of insecurely generating random numbers in Java.` +```kt +// SUMMARY: This sample demonstrates different common ways of insecurely generating random numbers in Java. +``` #### Logic @@ -173,11 +192,14 @@ Each FAIL/PASS comment must include the test Id and an explanation of why it fil Example: -`// FAIL: [MASTG-TEST-0204] The app insecurely uses random numbers for generating authentication tokens.` -`return r.nextDouble();` +```kt +// FAIL: [MASTG-TEST-0204] The app insecurely uses random numbers for generating authentication tokens. +return r.nextDouble(); + -`// PASS: [MASTG-TEST-0204] The app uses a secure random number generator.` -`return number.nextInt(21);` +// PASS: [MASTG-TEST-0204] The app uses a secure random number generator. +return number.nextInt(21); +``` ### run.sh From 60a78a959245f457c677946c47707f958b0c7353 Mon Sep 17 00:00:00 2001 From: Carlos Date: Mon, 1 Sep 2025 01:25:01 +0200 Subject: [PATCH 05/20] Add authoring standards for reference apps, knowledge base, mitmproxy scripts, r2 scripts, techniques, and tools --- .../instructions/mastg-apps.instructions.md | 107 ++++++++++++++++ .../mastg-knowledge.instructions.md | 121 ++++++++++++++++++ .../mastg-mitmproxy-scripts.instructions.md | 98 ++++++++++++++ .../mastg-r2-scripts.instructions.md | 94 ++++++++++++++ .../mastg-techniques.instructions.md | 113 ++++++++++++++++ .../instructions/mastg-tools.instructions.md | 119 +++++++++++++++++ 6 files changed, 652 insertions(+) create mode 100644 .github/instructions/mastg-apps.instructions.md create mode 100644 .github/instructions/mastg-knowledge.instructions.md create mode 100644 .github/instructions/mastg-mitmproxy-scripts.instructions.md create mode 100644 .github/instructions/mastg-r2-scripts.instructions.md create mode 100644 .github/instructions/mastg-techniques.instructions.md create mode 100644 .github/instructions/mastg-tools.instructions.md diff --git a/.github/instructions/mastg-apps.instructions.md b/.github/instructions/mastg-apps.instructions.md new file mode 100644 index 00000000000..5c5316f0f61 --- /dev/null +++ b/.github/instructions/mastg-apps.instructions.md @@ -0,0 +1,107 @@ +## Reference Apps + +Authoring standards for reference application pages under `apps/`. These list vulnerable or exemplar applications used across tests, techniques, and demos. + +Locations: + +- `apps/android/MASTG-APP-####.md` +- `apps/ios/MASTG-APP-####.md` +- `apps/index.md` is the catalog landing page. + +File naming and IDs: + +- The app ID is defined by the filename: `MASTG-APP-\d{4}.md`. +- Do not add an `id:` field to the YAML front matter for apps. +- Use the next available number within the platform folder. Coordinate in PRs to avoid collisions. + +Follow the global Markdown rules (see `.github/instructions/markdown.instructions.md`). Use `##` and `###` headings in the body. + +### Markdown: Metadata + +Include a YAML front matter block with these fields. + +Required: + +- `title:` App name with a disambiguator if needed (for example, "Android UnCrackable L1"). +- `platform:` One of: `android`, `ios`. +- `source:` Canonical page to obtain the app (official repo, release artifact, or MASTG crackmes catalog entry). Prefer a stable, versioned URL when available. + +Optional: + +- `package:` Android applicationId (for example, `com.example.app`). +- `bundle:` iOS bundle identifier (for example, `com.example.app`). +- `store:` Store listing URL (Google Play, App Store) if relevant. +- `status:` `draft`, `placeholder`, or `deprecated`. +- `note:` Short clarifying note (for example, prerequisites or license). + +Examples: + +```yaml +--- +title: Android UnCrackable L1 +platform: android +source: https://mas.owasp.org/crackmes/Android#android-uncrackable-l1 +package: sg.vantagepoint.uncrackable1 +--- +``` + +```yaml +--- +title: iGoat-Swift +platform: ios +source: https://github.com/OWASP/iGoat-Swift +bundle: org.owasp.iGoat-Swift +--- +``` + +### Markdown: Body + +Keep entries short and purely referential; avoid duplicating installation or usage docs that belong in the app’s own repo. + +Recommended sections: + +- Overview: One or two sentences describing the app and what it’s useful for. +- Acquisition: Where to download (link to releases or IPA/APK/APP sources). Include brief notes if side-loading is required. +- Notes: Any platform-specific setup hints (e.g., jailbreak/root expectations, certificate installation for proxies). +- Related: Cross-link to tests, techniques, and demos that commonly use this app. + +Cross-linking rules: + +- In body text, reference project identifiers with a leading `@` (for example, @MASTG-TEST-0204, @MASTG-TECH-0014, @MASTG-TOOL-0031). +- In YAML front matter, always use bare identifiers without the `@`. + +### Writing conventions + +- Use the official app name and capitalization as used by the project. +- Prefer official sources (original repo or the MASTG Crackmes catalog) for download links. +- If the original source is gone, mark the page with `status: deprecated` and provide a short `note:` explaining why. + +### Example + +````markdown +## Overview + +Android UnCrackable L1 is a purposely vulnerable application designed to practice reverse engineering and tampering techniques. + +## Acquisition + +- Crackmes catalog: https://mas.owasp.org/crackmes/Android#android-uncrackable-l1 +- APK file is provided via the crackmes page. + +## Notes + +- Designed for analysis on emulators and physical devices. +- Works well with @MASTG-TOOL-0031 and @MASTG-TECH-0045. + +## Related + +- Tests: @MASTG-TEST-0252, @MASTG-TEST-0263 +- Techniques: @MASTG-TECH-0039, @MASTG-TECH-0045 +```` + +### Edge cases and guidance + +- Open-source apps: Prefer linking to release artifacts (APK/IPA) rather than build-from-source instructions unless needed. +- Store-only apps: Use `store:` for the listing and add a short note if side-loading a specific version is necessary for reproducibility. +- Version specificity: When tests/demos require a specific version, state it clearly in the demo/test, not in the app entry; keep the app page evergreen. +- Deprecation: If an app becomes unavailable, set `status: deprecated` and add a `note:` with context and, if possible, a suggested replacement. diff --git a/.github/instructions/mastg-knowledge.instructions.md b/.github/instructions/mastg-knowledge.instructions.md new file mode 100644 index 00000000000..3cc48dacf68 --- /dev/null +++ b/.github/instructions/mastg-knowledge.instructions.md @@ -0,0 +1,121 @@ +## Knowledge Base + +Authoring standards for the Knowledge Base 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. + +Locations and taxonomy: + +- `knowledge/android/MASVS-/MASTG-KNOW-####.md` +- `knowledge/ios/MASVS-/MASTG-KNOW-####.md` +- `knowledge/index.md` is the catalog landing page. + +`` is one of: `AUTH`, `CODE`, `CRYPTO`, `NETWORK`, `PLATFORM`, `PRIVACY`, `RESILIENCE`, `STORAGE`. + +File naming and IDs: + +- The knowledge ID is defined by the filename: `MASTG-KNOW-\d{4}.md`. +- Do not add an `id:` field to the YAML front matter. +- Place the file in the platform (`android` or `ios`) and MASVS category folder that best matches the subject. + +Follow the global Markdown rules (see `.github/instructions/markdown.instructions.md`). Use `##` and `###` headings in the body. + +### Markdown: Metadata + +Include a YAML front matter block with these fields. + +Required: + +- `masvs_category:` One of: `MASVS-AUTH`, `MASVS-CODE`, `MASVS-CRYPTO`, `MASVS-NETWORK`, `MASVS-PLATFORM`, `MASVS-PRIVACY`, `MASVS-RESILIENCE`, `MASVS-STORAGE`. +- `platform:` One of: `android`, `ios`. +- `title:` Clear and specific concept title (for example, "Android KeyStore"). + +Optional: + +- `status:` `draft`, `placeholder`, or `deprecated`. +- `note:` Short free-form note to clarify scope. +- `available_since:` Minimum platform/API level (Android: integer API level; iOS: release version, for example `13`). +- `deprecated_since:` Last applicable platform/API level. +- `deprecation_note:` If deprecated, add a short rationale and replacement guidance. +- `covered_by:` List of knowledge IDs that supersede this page (use bare IDs). + +Examples: + +```yaml +--- +masvs_category: MASVS-STORAGE +platform: android +title: Android KeyStore +available_since: 18 +--- +``` + +```yaml +--- +masvs_category: MASVS-AUTH +platform: android +title: FingerprintManager +available_since: 23 +deprecated_since: 28 +status: deprecated +deprecation_note: The FingerprintManager class is deprecated in Android 9 (API level 28). Prefer BiometricPrompt or the Biometric library. +covered_by: [MASTG-KNOW-0001] +--- +``` + +### Markdown: Body + +Keep content authoritative, concise, and platform-focused. Avoid duplicating OS documentation; cite it and summarize what the feature is and how it works. Do not prescribe how to use it securely; move guidance to Best Practices and link to it. + +Recommended sections: + +- Overview: Define the concept and its scope. Relate to OS components, APIs, or security model elements. +- Security Context: Explain typical security-relevant behaviors or implications of the feature without recommending mitigations. +- Platform Details: API names, version nuances, storage locations, configuration knobs. Keep code samples short and explanatory. +- References: Official docs and standards. Avoid non-authoritative sources. +- Related: Cross-link to tests, techniques, tools, and best practices. + +Cross-linking rules: + +- In body text, reference project identifiers with a leading `@` (for example, @MASTG-TEST-0204, @MASTG-TECH-0014, @MASTG-TOOL-0031, @MASTG-BEST-0011). +- In YAML front matter, always use bare identifiers without the `@`. + +### Writing conventions + +- Use American spelling, second person, and active voice. +- Prefer short paragraphs and bullet lists for scannability. +- Use HTML `` for images as per the markdown instructions. + +### Example + +````markdown +## Overview + +Android KeyStore is a system-provided credential store that keeps cryptographic keys bound to the device and, optionally, to user authentication. Keys can be marked non-exportable and their usage can be limited. + +## Security Context + +- Keys can be hardware-backed depending on device support and OS version. +- Key usage can be constrained (purposes, modes, paddings) and optionally bound to user authentication. + +## Platform Details + +- Introduced in API level 18; many features evolved in later releases. +- Key properties are controlled via KeyGenParameterSpec. + +## References + +- Android docs - Keystore: https://developer.android.com/training/articles/keystore + +## Related + +- Tests: @MASTG-TEST-0263 +- Techniques: @MASTG-TECH-0014 +- Tools: @MASTG-TOOL-0033 +- Best practices: @MASTG-BEST-0011 (see this page for actionable guidance) +```` + +### Edge cases and guidance + +- 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. +- Deprecation: Mark with `status: deprecated`, add `deprecation_note`, and point to the replacement via `covered_by` or explicit links. +- 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. diff --git a/.github/instructions/mastg-mitmproxy-scripts.instructions.md b/.github/instructions/mastg-mitmproxy-scripts.instructions.md new file mode 100644 index 00000000000..79133ce0deb --- /dev/null +++ b/.github/instructions/mastg-mitmproxy-scripts.instructions.md @@ -0,0 +1,98 @@ +## mitmproxy Python scripts + +This guide defines how to write and use mitmproxy scripts in MASTG demos. Scripts live with the demo and are executed by `mitmdump -s` from `run.sh` to produce Observation output. + +### Scope and terminology + +- “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. + +### Location and naming + +- Place scripts inside the demo folder; name them by purpose in snake_case (for example, `mitm_sensitive_logger.py`). +- If multiple scripts are provided, document which one to run in the demo Steps and wire it in `run.sh`. + +### Invocation (run.sh) + +- Canonical pattern used in demos: + - `mitmdump -s mitm_sensitive_logger.py` +- Keep `run.sh` responsible for: + - Starting/stopping mitmdump (foreground or background as appropriate to the demo flow). + - Managing output files produced by the script (for example, `sensitive_data.log`). + - Ensuring the device/emulator routes traffic through the proxy (defer details to Tools page). + +### Coding conventions + +- Targeted processing via hooks: + - Implement `def request(flow: http.HTTPFlow): ...` and/or `def response(flow: http.HTTPFlow): ...` as needed. + - Factor common logic into helpers (for example, `process_flow(flow)`). +- Deterministic logging: + - Write to a known output filename (for example, `sensitive_data.log`) for Observation parsing. + - Keep log format stable: include URL, headers summary, and text body as needed. +- Sensitive data handling: + - Define a clear list of sensitive strings or patterns at the top (for example, `SENSITIVE_DATA`), ideally documented in the demo explaining how they were identified (e.g., from the app’s Data Safety section). + - Consider case-insensitive matching where appropriate. +- Performance and safety: + - Avoid excessive buffering—use streaming-friendly `flow.request.text`/`flow.response.text` guarded with presence checks. + - Wrap parsing in try/except where decoding may fail; log an informative line and continue. + - Never print secrets to stdout unless the demo requires it; prefer file logging. + +### Example (excerpt) + +```python +from mitmproxy import http + +SENSITIVE_DATA = { + "precise_location_latitude": "37.7749", + "precise_location_longitude": "-122.4194", + "name": "John Doe", + "email_address": "john.doe@example.com", + "phone_number": "+11234567890", + "credit_card_number": "1234 5678 9012 3456", +} + +SENSITIVE_STRINGS = SENSITIVE_DATA.values() + +def contains_sensitive_data(s: str) -> bool: + try: + return any(p in s for p in SENSITIVE_STRINGS) + except Exception: + return False + +def process_flow(flow: http.HTTPFlow): + url = flow.request.pretty_url + req_body = flow.request.text or "" + resp_body = flow.response.text if flow.response else "" + + if contains_sensitive_data(url) or contains_sensitive_data(req_body) or contains_sensitive_data(resp_body): + with open("sensitive_data.log", "a", encoding="utf-8") as f: + if flow.response: + f.write(f"RESPONSE URL: {url}\n") + f.write(f"Response Body: {resp_body}\n\n") + else: + f.write(f"REQUEST URL: {url}\n") + f.write(f"Request Body: {req_body}\n\n") + +def request(flow: http.HTTPFlow): + process_flow(flow) + +def response(flow: http.HTTPFlow): + process_flow(flow) +``` + +### Logging and outputs + +- Default to writing a deterministic, append-only file (for example, `sensitive_data.log`) in the demo folder. Reference it in the Observation and Evaluation sections. +- Keep the format simple and consistent—avoid timestamps unless needed for the demo, to keep diffs small. +- If multiple outputs are produced, document them in the demo’s Steps. + +### Alignment with Tools + +- Environment prep (install, certificates, proxy configuration, Android emulator notes) is documented under Tools: @MASTG-TOOL-0097. Link to that page; don’t duplicate instructions in the demo. +- If a demo requires non-default proxy ports or HTTPS sniffing modes, surface them in `run.sh` flags and document briefly in the demo body. + +### Cross-links + +- Tools: @MASTG-TOOL-0097 (mitmproxy) +- Techniques: @MASTG-TECH-0122 (Passive Eavesdropping), @MASTG-TECH-0123/0124/0125 (MITM Positioning) \ No newline at end of file diff --git a/.github/instructions/mastg-r2-scripts.instructions.md b/.github/instructions/mastg-r2-scripts.instructions.md new file mode 100644 index 00000000000..bfaae66b683 --- /dev/null +++ b/.github/instructions/mastg-r2-scripts.instructions.md @@ -0,0 +1,94 @@ +## r2 scripts (radare2) + +This guide defines how to write and use radare2 scripts in MASTG demos. Scripts live with the demo and are executed by `run.sh` to produce Observation output. + +### Scope and terminology + +- “r2 scripts” refers to radare2 command files executed with `-i `. +- 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. + +### Location and naming + +- Place scripts inside the demo folder; name them after the target concept or API, using lowercase with underscores if needed. + - Examples: + - `demos/ios/MASVS-CRYPTO/MASTG-DEMO-0015/cchash.r2` + - `demos/ios/MASVS-RESILIENCE/MASTG-DEMO-0021/jailbreak_detection.r2` +- If multiple scripts are required, use descriptive names and document which one to run in the demo Steps and `run.sh`. + +### Invocation patterns (run.sh) + +- Canonical pattern used in demos: + - `r2 -q -i script.r2 -A > output.asm` + - `-q` quiet mode for stable logs + - `-i script.r2` executes the script file + - `-A` performs auto-analysis (as used across our demos) + - Redirect to a file (commonly `output.asm`) for Observation/Evaluation +- Optional evals used by some demos: + - `-e emu.str=true` to enable emulation of strings in specific analyses +- For multi-arch or fat binaries (Mach-O), specify architecture when necessary: + - `r2 -q -i script.r2 -A -n arm64 > output.asm` +- Keep `run.sh` responsible for resolving the correct binary path/name (for example, `MASTestApp` in iOS demos) and for output redirection. + +Notes + +- Keep `run.sh` responsible for environment prep (paths, extraction/unzip, codesign stripping, etc.). The script should focus on r2 commands only. +- If a path is dynamic, pass it via `-e` evals (for example, `-e bin.file=`), or let `run.sh` build the `o ` command line. + +### Coding conventions for .r2 files + +- Be explicit and quiet: + - Start with `e scr.color=0` and `e scr.interactive=false` to keep logs clean and deterministic. + - Disable ASCII art and hints if present: `e scr.utf8=0`, `e scr.ansi=false` (only if needed). +- Analyze narrowly and only as needed to keep runtime fast and stable: + - Prefer targeted analysis commands (for example, `axt @ `, `afl~`) over full `aaa` unless required. + - When using full analysis, document why and consider `aa`/`aaa` caps for speed. +- Structure output with short, stable headings using `?e` echo lines as markers for Observation/Evaluation parsing. +- Bound outputs to minimize diffs; use filters like `afl~PATTERN`, `iz~PATTERN`, or limit disassembly lines (for example, `pd-- 5 @ ` as seen in `cchash.r2`). +- Prefer symbol-based references when available; fall back to addresses only when necessary and document the basis (for example, derived from `axt @ 0x...`). + +### Example: iOS CommonCrypto hashes (excerpt) + +``` +?e Uses of CommonCrypto hash function: +afl~CC_ + +?e +?e xrefs to CC_MD5: +axt @ 0x1000071a8 + +?e xrefs to CC_SHA1: +axt @ 0x1000071b4 + +?e +?e Use of MD5: +pd-- 5 @ 0x1000048c4 + +?e +?e Use of SHA1: +pd-- 5 @ 0x10000456c +``` + +### Logging and outputs + +- Use `?e` for plain echo markers; avoid colors and progress noise. Keep section titles consistent with the demo write-up to ease Evaluation checks. +- Redirect all command output into a file in `run.sh` (for example, `output.txt`), and reference it in the demo’s Observation. + +### Safety and troubleshooting + +- If a symbol or address is not present across versions, add a preceding discovery block to compute it: + - Example: `afl~CC_MD5[0]` to list and then `s ` before `pd`. +- For fat binaries or stripped symbols: + - Specify arch with `-a`/`-b` or `-n` as needed. + - Use heuristics: strings (`iz`), imports (`ii`), and xrefs (`axt`) to locate targets. +- Keep scripts idempotent: avoid `wt` or write operations; analysis should be read-only. + +### Alignment with Tools + +- Installation and deeper usage guides are in Tools: @MASTG-TOOL-0073 (radare2), @MASTG-TOOL-0129 (rabin2), and related entries. Do not duplicate installation or environment requirements in demos. +- When relevant, mention GUI options like Iaito @MASTG-TOOL-0098 for interactive exploration, but keep demo scripts CLI-focused and reproducible. + +### Cross-links + +- Tools: @MASTG-TOOL-0073 (radare2), @MASTG-TOOL-0129 (rabin2), @MASTG-TOOL-0098 (Iaito) +- Techniques: @MASTG-TECH-0067 (Dynamic Analysis), @MASTG-TECH-0045 (Runtime Reverse Engineering) \ No newline at end of file diff --git a/.github/instructions/mastg-techniques.instructions.md b/.github/instructions/mastg-techniques.instructions.md new file mode 100644 index 00000000000..23e73aa4cbb --- /dev/null +++ b/.github/instructions/mastg-techniques.instructions.md @@ -0,0 +1,113 @@ +## Techniques + +Authoring standards for the techniques catalog under `techniques/`. Techniques document reusable procedures and workflows used by tests and demos. + +Locations: + +- `techniques/android/MASTG-TECH-####.md` +- `techniques/ios/MASTG-TECH-####.md` +- `techniques/generic/MASTG-TECH-####.md` (platform-agnostic or cross-platform) +- `techniques/index.md` (catalog landing) + +File naming and IDs: + +- The technique ID is defined by the filename: `MASTG-TECH-\d{4}.md`. +- Do not add an `id:` field to the YAML front matter for techniques. +- Use the next available number within the platform folder. Coordinate in PRs to avoid collisions. + +Follow the global Markdown rules (see `.github/instructions/markdown.instructions.md`). Use `##` for top-level sections inside the page. + +### Markdown: Metadata + +Include a YAML front matter block with these fields. + +Required: + +- `title:` Clear, action-oriented name for the technique (for example, "Method Tracing"). +- `platform:` One of: `android`, `ios`, `generic`. + +Optional: + +- `status:` `draft`, `placeholder`, or `deprecated`. +- `note:` Short free-form note for scope or caveats. +- `available_since:` Minimum platform/API level where this technique applies (Android: integer API level; iOS: release version, for example `13`). +- `deprecated_since:` Last applicable platform/API level. + +Examples: + +```yaml +--- +title: Method Tracing +platform: android +--- +``` + +```yaml +--- +title: Intercepting HTTP Traffic Using an Interception Proxy +platform: generic +--- +``` + +### Markdown: Body + +Keep techniques practical, step-by-step, and tool-agnostic when possible. Where tool specifics are necessary, prefer linking to tool pages and keep commands minimal. + +Recommended structure: + +- Overview: What the technique does and when to use it. +- Prerequisites: Any environmental requirements (device state, jailbreak/root, certificates, OS tooling). +- Steps: Ordered steps with commands and short explanations. Prefer resilient commands and include expected prompts/outputs briefly. +- Validation: How to confirm success (signals, artifacts, logs). Mention common failure modes and remediation tips. +- Variations: Platform- or framework-specific variants (for example, Flutter, React Native), and alternatives. +- References: Authoritative docs or guides. +- Related: Cross-links to tests, tools, and demos using this technique. + +Cross-linking rules: + +- In body text, reference project identifiers with a leading `@` (for example, @MASTG-TEST-0204, @MASTG-TOOL-0031). +- In YAML front matter, always use bare identifiers (no `@`). + +### Writing conventions + +- Prefer imperative voice in steps ("Run", "Attach", "Export"). +- Keep commands copyable and self-contained. Where platform prompts or additional context are needed, explain in one short sentence. +- Favor official sources for installation instructions; avoid endorsing third-party distributions. +- Use HTML `` tags for images, per the markdown instructions. + +### Examples + +````markdown +## Overview + +Method tracing captures method entry/exit events to understand runtime behavior. This helps locate sensitive logic and verify mitigations. + +## Prerequisites + +- USB debugging enabled +- @MASTG-TOOL-0031 (Frida) + +## Steps + +1. List app processes: `frida-ps -Uai | grep com.example.app` +2. Trace target APIs: + +```sh +frida-trace -U -i "*Network*" -n com.example.app +``` + +## Validation + +You should see method entries in the console matching the targeted patterns. If nothing appears, verify the process name and that the device permits tracing. + +## Related + +- Tests: @MASTG-TEST-0252 +- Tools: @MASTG-TOOL-0031 +```` + +### Edge cases and guidance + +- Multi-platform techniques: If steps are identical across platforms, place the page under `generic/`. If they differ meaningfully, create separate platform pages. +- Tool selection: Link to multiple tools when appropriate and list trade-offs briefly in the text; keep detailed tool usage on the tool pages. +- Deprecation: If a technique becomes obsolete (for example, platform removed capability), set `status: deprecated` and add a short note at the top explaining why, with links to alternatives. diff --git a/.github/instructions/mastg-tools.instructions.md b/.github/instructions/mastg-tools.instructions.md new file mode 100644 index 00000000000..95a0c4069f7 --- /dev/null +++ b/.github/instructions/mastg-tools.instructions.md @@ -0,0 +1,119 @@ +## Tools + +Authoring standards for tool reference pages under `tools/`. These pages document tools used throughout tests, demos, and techniques in the MASTG. + +Locations: + +- `tools/android/MASTG-TOOL-####.md` +- `tools/ios/MASTG-TOOL-####.md` +- `tools/generic/MASTG-TOOL-####.md` (cross-platform or platform-agnostic tools) +- `tools/network/MASTG-TOOL-####.md` (traffic analysis and proxying) + +File naming: + +- The tool ID is defined by the filename: `MASTG-TOOL-\d{4}.md`. +- Do not add an `id:` field to the YAML front matter for tools. +- Use the next available number for the target folder. Coordinate in PRs to avoid clashes. + +Follow the global Markdown rules (see `.github/instructions/markdown.instructions.md`) for headings, images, code blocks, and style. + +### Markdown: Metadata + +Include a YAML front matter block with these fields. + +Required: + +- `title:` Concise tool name. Add a qualifier when needed to disambiguate (for example, "Frida for Android", "nm - iOS"). +- `platform:` One of: `android`, `ios`, `generic`, `network`. + +Optional: + +- `source:` Canonical homepage or repository URL. +- `host:` List of operating systems the tool runs on. Prefer this exact set (case-sensitive values): `windows`, `linux`, `macOS`, `ios`, `android`. + - Use `host:` with a YAML list (preferred). If you find `hosts:` in legacy pages, migrate to `host:` when touching the file. + - Use `ios` / `android` for on-device tools (for example, Filza). +- `alternatives:` List of tool IDs that provide comparable functionality. +- `status:` `draft`, `placeholder`, or `deprecated`. +- `deprecation_note:` Short justification and replacement guidance (required when `status: deprecated`). +- `covered_by:` List of tool IDs that supersede this tool (required when `status: deprecated`). +- `note:` Short free-form note to clarify scope or limitations. + +Examples: + +```yaml +--- +title: Frida for Android +platform: android +source: https://github.com/frida/frida +host: [windows, linux, macOS] +alternatives: + - MASTG-TOOL-0031 # Frida (generic) +--- +``` + +```yaml +--- +title: Cycript +platform: ios +source: https://www.cycript.org/ +status: deprecated +deprecation_note: Cycript is no longer maintained and fails on modern iOS versions. Prefer Frida which is actively supported and more capable. +covered_by: [MASTG-TOOL-0039] +--- +``` + +### Markdown: Body + +Keep pages practical, scannable, and focused on security testing use. Use `##` and `###` headings. + +Recommended section outline: + +- Overview: One short paragraph describing what the tool is and where it fits. +- Capabilities and Use Cases: Bullet list of relevant features for mobile testing. +- Installation: Platform-specific notes (link out to official docs when appropriate). Include the minimal, verified commands to get started. +- Usage: Common commands, flags, or workflows relevant to MASTG tests/demos. Prefer concrete, copyable examples. +- Examples: Short, targeted examples for typical tasks. If examples are long, link to demos or techniques instead. +- Caveats and Limitations: Version compatibility, jailbreak/root requirements, known issues. +- References: Links to official docs, repos, and authoritative resources. +- Related: Cross-link to relevant tests, demos, and techniques. + +Cross-linking rules: + +- In body text, reference project identifiers with a leading `@` (for example, @MASTG-TEST-0204, @MASTG-TOOL-0031, @MASTG-TECH-0014). +- In YAML front matter, always use bare identifiers without the `@`. + +Example snippets: + +````markdown +## Usage + +List running apps and attach to a process: + +```sh +frida-ps -Uai +frida -U -n com.example.app -l hook.js +``` + +See @MASTG-TECH-0014 for guidance on dynamic method tracing and @MASTG-TEST-0252 for a test that benefits from this tool. +```` + +````markdown +## References + +- GitHub: https://github.com/frida/frida +- Docs: https://frida.re/docs/home/ +```` + +### Conventions and Quality + +- Prefer official sources for installation steps; avoid advertising or endorsing third-party distributions. +- Favor commands that work across supported hosts when possible; otherwise clearly label host-specific commands. +- For images, use HTML `` tags per the markdown instructions (store assets in an appropriate images folder if needed). +- Keep examples minimal and verifiable; longer walkthroughs belong in demos with runnable scripts. + +### How tests and demos should reference tools + +- Tests and demos should reference tools by ID whenever available: + - In body text: `@MASTG-TOOL-0031`. + - In YAML (for example, demo `tools:` list): `MASTG-TOOL-0031`. +- If a commonly used tool lacks an official MASTG tool page, demos may temporarily list the tool by name (for example, `tools: [semgrep]`). Prefer adding a tool page and switching to the ID in follow-ups. From ac92a800a4ea96baf1d3753e159e76e369c5c6b7 Mon Sep 17 00:00:00 2001 From: Carlos Date: Mon, 1 Sep 2025 01:25:22 +0200 Subject: [PATCH 06/20] Enhance documentation for best practices, demos, Frida scripts, rules, tests, and porting instructions to improve clarity, consistency, and usability across the MASTG framework. --- .../mastg-best-practice.instructions.md | 79 ++++++++++++- .../instructions/mastg-demo.instructions.md | 61 ++++++++-- .../mastg-frida-scripts.instructions.md | 110 +++++++++++++++++- .../instructions/mastg-rules.instructions.md | 57 +++++++-- .../instructions/mastg-test.instructions.md | 39 ++++++- ...rting-mastg-v1-tests-to-v2.instructions.md | 106 ++++++++--------- 6 files changed, 367 insertions(+), 85 deletions(-) diff --git a/.github/instructions/mastg-best-practice.instructions.md b/.github/instructions/mastg-best-practice.instructions.md index cad5186ccaa..d7ac274491c 100644 --- a/.github/instructions/mastg-best-practice.instructions.md +++ b/.github/instructions/mastg-best-practice.instructions.md @@ -3,12 +3,81 @@ [https://mas.owasp.org/MASTG/best-practices/](https://mas.owasp.org/MASTG/best-practices/) [https://github.com/OWASP/owasp-mastg/tree/master/best-practices](https://github.com/OWASP/owasp-mastg/tree/master/best-practices) -Best practices must be linked to MASTG tests using the `best-practices:` key. +Best practices live under `best-practices/` and each file name must be the best-practice ID, for example `MASTG-BEST-0001.md`. -They must have official references which may include the MASTG as long as it contains further references to e.g. Google/Apple docs or other official sources. +Best practices must be linked from MASTG tests using the `best-practices:` key in the test’s YAML front matter (use bare IDs, without the leading @). + +They must include official references. You can cite the MASTG as a hub only when it points to official sources (for example, Google/Apple documentation, standards, or vendor advisories). + +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/`. + +### Markdown: Metadata + +Include a YAML front matter block with the following fields: + +- title: Concise, action-oriented recommendation. +- id: Best-practice ID in the form `MASTG-BEST-\d{4}`. +- platform: One of: android, ios. + +Optional metadata: + +- alias: URL-friendly slug (lowercase, hyphen-separated) used for navigation. +- status: draft, placeholder, deprecated. +- note: Short free-form note. +- 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. + +Example: + +```yaml +--- +title: Preventing Screenshots and Screen Recording +alias: preventing-screenshots-and-screen-recording +id: MASTG-BEST-0014 +platform: android +--- +``` + +Notes: + +- In body text, reference in-project identifiers with a leading @ (for example, @MASTG-TEST-0252). In YAML front matter, omit the @ and use bare IDs. Best Practices should contain: -* what's the recommendation -* why is that good -* any caveats or considerations (e.g. "it's good to have it but remember it can be bypassed this way", etc.) \ No newline at end of file +- what's the recommendation +- why is that good +- any caveats or considerations (for example, "it's good to have it but remember it can be bypassed this way") +- official references + +### Recommended Structure + +Use clear sections to improve readability and enable consistent rendering. + +- Overview or Recommendation: State the practice and its scope in one or two short paragraphs. Link to relevant Knowledge pages for background when needed. +- Rationale: Explain the security value and platform implications; keep conceptual detail brief and defer to Knowledge pages. +- Caveats or Considerations: Note limits, bypasses, compatibility constraints, or trade-offs. +- References: Bullet list of official, authoritative sources. + +Example References section: + +```markdown +## References + +- Android docs: https://developer.android.com/security/fraud-prevention/activities#flag_secure +- Apple docs: https://developer.apple.com/documentation +- Standard: https://www.rfc-editor.org +``` + +### Cross-linking + +- From tests: use `best-practices: [MASTG-BEST-0001, MASTG-BEST-0011]` in the test’s YAML front matter. The site generator will create Mitigations links automatically. +- In body text: reference tests, tools, or techniques with @ (for example, @MASTG-TEST-0252, @MASTG-TOOL-0031). + +### Style + +- Follow the global Markdown rules and writing style (second person, active voice, concise, American spelling). +- Use Chicago title case for titles. +- Keep content focused and avoid duplicating other guide sections. Link out where appropriate. \ No newline at end of file diff --git a/.github/instructions/mastg-demo.instructions.md b/.github/instructions/mastg-demo.instructions.md index b0fc95fedb0..2d337fbb4b8 100644 --- a/.github/instructions/mastg-demo.instructions.md +++ b/.github/instructions/mastg-demo.instructions.md @@ -7,7 +7,7 @@ Demos live in `demos/android/` or `demos/ios/` under the corresponding MASVS cat * Markdown file: `MASTG-DEMO-xxx.md` * Code samples (e.g. .kt, .swift, .xml, .plist) * Testing code (e.g. sh, py) -* Output files (e.g. txt, sarif) +* Output files (e.g. txt, json, sarif) **Language:** The samples are written in **Kotlin** or **Swift**, depending on the platform. In some cases, the samples will also include configuration files such as AndroidManifest.xml or Info.plist. @@ -35,6 +35,16 @@ run.sh* ### Markdown: Metadata +#### id + +The demo ID. This should match the folder name. + +Example: + +```md +id: MASTG-DEMO-0054 +``` + #### title The title should concisely express what the demo is about. @@ -47,13 +57,13 @@ title: Common Uses of Insecure Random APIs #### platform -The mobile platform. Can be one of: ios, android. +The mobile platform. One of: ios, android. #### tools Tools used in the demo. -They must be referenced using their IDs from [https://mas.owasp.org/MASTG/tools/](https://mas.owasp.org/MASTG/tools/) +Prefer referencing official tool IDs from https://mas.owasp.org/MASTG/tools/ when available (for example, `MASTG-TOOL-0031`). If an official ID is not available, you may use a well-known tool name (for example, `semgrep`). Example: @@ -61,9 +71,15 @@ Example: tools: [MASTG-TOOL-0031] ``` +Example without an official ID: + +```md +tools: [semgrep] +``` + #### code -The language in which the samples are written. +The language(s) in which the samples are written. Multiple values are supported. Example: @@ -71,6 +87,31 @@ Example: code: [java] ``` +Multi-language example: + +```md +code: [xml, kotlin] +``` + +#### kind + +Optional. When helpful, specify whether the demo demonstrates a passing or failing case. + +Valid values: `pass`, `fail`. + +Example: + +```md +kind: pass +``` + +#### optional fields + +Include these if relevant: + +- `status:` draft, placeholder, deprecated +- `note:` short free-form note providing additional context + ### Markdown: Body #### Sample @@ -101,7 +142,7 @@ The snippet below shows sample code that sends sensitive data over the network u #### Steps -A concise writeup following all steps from the test and including the relevant placeholders for testing code (e.g. SAST rules, run.sh files). +A concise writeup following all steps from the linked test, including placeholders for testing code and scripts (for example, SAST rules, `run.sh`). Example: @@ -117,7 +158,7 @@ Let's run our semgrep rule against the sample code. #### Observation -A concise description of the observation for this specific demo including the relevant placeholders for output files (e.g. output.txt). +A concise description of the observation for this specific demo including placeholders for output files (for example, `output.txt`, `output.json`). Example: @@ -131,7 +172,7 @@ The rule has identified some instances in the code file where a non-random sourc #### Evaluation -A concise explanation about how you applied the test “Evaluation” section to this specific demo. For example, if lines are present explain each 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: @@ -188,7 +229,7 @@ For example, if you create a random number you can return it; or if you write fi Must contain comments indicating fail/pass and the test alias. This way we're able to validate that the output is correct (e.g. the code contains 3 failures of `MASTG-TEST-0204`). We can easily parse and count the comments and we can do the same in the output. -Each FAIL/PASS comment must include the test Id and an explanation of why it files/passes. +Each FAIL/PASS comment must include the test Id and an explanation of why it fails/passes. Example: @@ -203,11 +244,11 @@ return number.nextInt(21); ### run.sh -Every test that can be automated must contain a run.sh file +Every demo that can be automated must contain a `run.sh` file that runs the analysis or instrumentation and generates the referenced output artifacts. #### Static -Static tests must work using the **reverse-engineered** **code**. The app’s repos contain scripts or indications to obtain the reversed files. +Static demos must work using the **reverse-engineered code**. The apps’ repositories contain scripts or instructions to obtain the reversed files. Example: semgrep diff --git a/.github/instructions/mastg-frida-scripts.instructions.md b/.github/instructions/mastg-frida-scripts.instructions.md index 3c534ac4d26..766c26cb48f 100644 --- a/.github/instructions/mastg-frida-scripts.instructions.md +++ b/.github/instructions/mastg-frida-scripts.instructions.md @@ -1,3 +1,111 @@ ## Frida Scripts -Demos must use Frida 17 and above, see https://mas.owasp.org/MASTG/tools/generic/MASTG-TOOL-0031/#frida-17 \ No newline at end of file +This guide defines how to write and use Frida scripts in MASTG demos. Scripts live alongside the demo content and are executed by `run.sh` to produce the demo’s Observation output. + +Version requirement + +- Use Frida 17 or later. See @MASTG-TOOL-0031 (Frida): https://mas.owasp.org/MASTG/tools/generic/MASTG-TOOL-0031/#frida-17 + +### Location and naming + +- Place scripts inside the demo folder and name them `script.js` unless multiple scripts are needed. +- If multiple scripts are required, use specific names (for example, `hook_ssl.js`, `hook_keystore.js`) and document which to run in the demo Steps and `run.sh`. + +Examples: + +- `demos/ios/MASVS-AUTH/MASTG-DEMO-0042/script.js` +- `demos/android/MASVS-NETWORK/MASTG-DEMO-0007/script.js` + +### Runtime and invocation + +- Prefer the V8 runtime unless a different engine is necessary; you can enforce it with `--runtime=v8`. +- Typical spawn usage in `run.sh`: + - `frida -U -f -l script.js --no-pause --runtime=v8 > output.txt` +- Typical attach usage: + - `frida -U -n -l script.js --runtime=v8 > output.txt` + +### Coding conventions + +- Keep scripts self-contained (no external module imports). +- Keep output concise and deterministic for Evaluation parsing. +- Validate availability before hooking: + - iOS: `if (ObjC.available) { ... }` + - Android: `Java.perform(() => { ... })` +- Check class/method existence; log a clear message if missing. +- Avoid global side effects; scope variables within hooks/functions. +- Logging: prefer `console.log()`; add short section headers only when helpful. +- Backtraces: use `DebugSymbol.fromAddress` and cap lines. +- In `onEnter/onLeave`, capture context first (for example, `const ctx = this.context;`) before using nested arrow functions. + +### iOS patterns + +- Hook Objective-C methods with explicit `-` (instance) or `+` (class) signatures. +- Example (LAContext evaluatePolicy): + +````javascript +if (ObjC.available && ObjC.classes.LAContext) { + const method = ObjC.classes.LAContext["- evaluatePolicy:localizedReason:reply:"]; + if (method) { + Interceptor.attach(method.implementation, { + onEnter(args) { + const ctx = this.context; + const LAPolicy = { 1: ".deviceOwnerAuthenticationWithBiometrics", 2: ".deviceOwnerAuthentication" }; + const policy = args[2].toInt32(); + console.log(`LAContext.evaluatePolicy called with ${LAPolicy[policy] || "Unknown"} (${policy})`); + const bt = Thread.backtrace(ctx, Backtracer.ACCURATE).slice(0, 8).map(DebugSymbol.fromAddress); + console.log("Backtrace:\n" + bt.join("\n")); + } + }); + } else { + console.log("LAContext.evaluatePolicy not found"); + } +} else { + console.log("ObjC runtime not available or LAContext missing"); +} +```` + +### Android patterns + +- Wrap hooks in `Java.perform` and use `Java.use` to access classes. +- Example: + +````javascript +Java.perform(() => { + const HttpsURLConnection = Java.use('javax.net.ssl.HttpsURLConnection'); + HttpsURLConnection.setHostnameVerifier.overload('javax.net.ssl.HostnameVerifier').implementation = function (verifier) { + console.log('HttpsURLConnection.setHostnameVerifier called'); + return this.setHostnameVerifier(verifier); + }; +}); +```` + +### Logging and outputs + +- Redirect script output to `output.txt` from `run.sh`. +- Keep logs minimal and structured so Observation/Evaluation can reference them directly. +- Cap list outputs (for example, backtraces) to keep diffs stable. + +### Safety and troubleshooting + +- Use try/catch around complex hooks to prevent script termination. +- If a symbol/method is missing, log and continue. +- Spawn vs attach: use `-f` for early instrumentation when needed. +- Consider stripped binaries and symbol resolution; prefer Objective-C/Java-level hooks over raw native symbols where possible. + +### Cross-links + +- Tools: @MASTG-TOOL-0031 (Frida) +- Techniques: @MASTG-TECH-0045 (Runtime Reverse Engineering), @MASTG-TECH-0015 / @MASTG-TECH-0067 (Dynamic Analysis) + +### Alignment with Tools/Frida + +- The authoritative reference for installing, configuring, and troubleshooting Frida lives under Tools: @MASTG-TOOL-0031. Do not duplicate setup steps in demos; instead, link to the Tools page. +- Version compatibility: ensure `frida-tools` (CLI on the host) and the device runtime (for example, `frida-server` on Android or injected runtime on iOS) use matching major/minor versions (17.x with 17.x). +- Device and transport flags: align with Tools documentation and prefer these consistently in `run.sh`: + - `-U` USB default device + - `-D ` a specific device by ID + - `-H ` network/remote device (for example, when port-forwarding or remote frida-server) +- Platform notes (defer details to Tools page): + - Android: frida-server typically runs on-device; you may use adb port-forwarding when targeting `-H`. + - iOS: non-jailbroken workflows don’t need frida-server; rely on USB transport. Jailbroken workflows might use frida-server; follow the Tools guidance. +- Demo authors should: link to Tools for environment prep, keep `script.js` runtime-agnostic, and focus scripts on instrumentation logic, not environment management. \ No newline at end of file diff --git a/.github/instructions/mastg-rules.instructions.md b/.github/instructions/mastg-rules.instructions.md index e0251187faa..76a83f2bd91 100644 --- a/.github/instructions/mastg-rules.instructions.md +++ b/.github/instructions/mastg-rules.instructions.md @@ -1,6 +1,6 @@ ## Rules -SAST rules live in `rules` folder. They can be referenced and reused by the demos. +SAST rules live in the `rules/` folder. They are referenced and reused by demos and should be stable and consistently named. ### Semgrep rules @@ -10,22 +10,40 @@ SAST rules live in `rules` folder. They can be referenced and reused by the demo Tip: use [https://semgrep.dev/playground/new](https://semgrep.dev/playground/new) for experimentation. -They must be named `mastg-.yaml` and follow valid syntax according to [https://semgrep.dev/docs/writing-rules/rule-syntax/](https://semgrep.dev/docs/writing-rules/rule-syntax/) +File naming and format -* **id**: same as the file name +- Name files using the pattern: `mastg--.(yml|yaml)` (for example, `mastg-android-non-random-use.yml`). +- Use either `.yml` or `.yaml` consistently per file; both are accepted. +- A file may contain one or more rules. + +Semgrep rules must follow valid syntax: [https://semgrep.dev/docs/writing-rules/rule-syntax/](https://semgrep.dev/docs/writing-rules/rule-syntax/) + +Recommended fields per rule + +* **id**: unique, stable identifier. For single-rule files, prefer matching the filename without extension. For multi-rule files, use a common prefix based on the filename and a descriptive suffix (for example, `mastg-android-data-unencrypted-shared-storage-no-user-interaction-mediastore`). * **severity**: + * INFO * WARNING * ERROR -* **languages**: e.g. xaml, java (we don't create rules for kotlin as we only work with decompiled code which is in java) +* **languages**: usually `xml` or `java` (we don’t create rules for Kotlin as we work with decompiled Java; use `xml` for AndroidManifest and resource rules). * **metadata**: must include summary * summary: Short description of the rule. * original_source: you may use rules from sources on the internet be sure to check that the license allows this and always link to the original source here. Modify the rule if needed and the license allows for it. -* **message**: must start with the MASVS control ID and concisely explain what the rule is reporting. +* **message**: must start with a MASVS identifier and concisely explain what the rule is reporting. Prefer a specific control when applicable (for example, `[MASVS-PLATFORM-2]`); otherwise, use the MASVS category tag (for example, `[MASVS-STORAGE]`). * **patterns**: see [https://semgrep.dev/docs/writing-rules/pattern-syntax/](https://semgrep.dev/docs/writing-rules/pattern-syntax/) -Do not include authors in the semgrep rules. If it was copied from some other place, **include the link to the original source**. Since many people will potentially contribute to the rule as part of the MASTG work, the authors will be calculated using git. +Multiple rules per file + +- When grouping related detections, you may define multiple rules in a single file. Ensure each rule’s `id` shares a sensible prefix and is unique. +- Keep messages and severities aligned within the group; use `INFO` for inventory-style detections and `WARNING`/`ERROR` for clear weaknesses. + +General guidance -Example: +- Do not include authors in the semgrep rules. If it was copied from some other place, **include the link to the original source**. Since many people will contribute, authorship is tracked via git history. +- Keep messages concise and actionable; they should be understandable without reading the pattern body. +- Test rules in the Semgrep Playground and against reversed code from the demos. + +Example (single rule): ```yml rules: @@ -43,4 +61,29 @@ rules: - pattern-either: - pattern: Math.random(...) - pattern: (java.util.Random $X).$Y(...) +``` + +Example (multiple rules in one file): + +```yml +rules: + - id: mastg-android-data-unencrypted-shared-storage-no-user-interaction-external-api-public + severity: WARNING + languages: [java] + metadata: + summary: Methods returning locations on shared external storage. + message: "[MASVS-STORAGE] Make sure to encrypt files at these locations if necessary" + pattern-either: + - pattern: $X.getExternalStorageDirectory(...) + - pattern: $X.getExternalStoragePublicDirectory(...) + + - id: mastg-android-data-unencrypted-shared-storage-no-user-interaction-mediastore + severity: WARNING + languages: [java] + metadata: + summary: MediaStore API writes to external storage. + message: "[MASVS-STORAGE] Data written via MediaStore can be readable by other apps on older Android versions" + pattern-either: + - pattern: import android.provider.MediaStore + - pattern: $X.MediaStore ``` \ No newline at end of file diff --git a/.github/instructions/mastg-test.instructions.md b/.github/instructions/mastg-test.instructions.md index 726adcbe99a..e524b0e9f4c 100644 --- a/.github/instructions/mastg-test.instructions.md +++ b/.github/instructions/mastg-test.instructions.md @@ -2,6 +2,10 @@ Tests are platform-specific and must be located under tests-beta/android/ or tests-beta/ios/, within the corresponding MASVS category. Their file names are the test IDs. +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/`). + Tests have an overview and contain Steps which produce outputs called observations. After following the Steps you come up with an [Observation](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1#heading=h.h9gqgz4hdubj) which you will [Evaluate](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1#heading=h.lare0v58fwbf). Example: @@ -39,7 +43,9 @@ Examples: #### platform -The mobile platform. One of: ios, android. +The mobile platform. One of: ios, android, network. + +- Use network for platform-agnostic traffic analysis tests where the checks are performed purely on captured/observed traffic (often paired with type: [network]). #### id @@ -49,11 +55,15 @@ The test ID. The MASWE weakness ID the test references. +- In YAML front matter, specify the bare identifier (for example, `weakness: MASWE-0069`). In body text, include the leading `@` (for example, @MASWE-0069). + #### type One or more test types. -Supported: static, dynamic, network, manual, filesystem. +Supported: static, dynamic, network, manual, filesystem, developer. + +- developer: tests that work on developer artifacts or supply-chain outputs (for example SBOM, dependency manager lockfiles, scanner reports) rather than the built app. Example: @@ -61,6 +71,16 @@ Example: type: [static] ``` +Examples with multiple types: + +```md +type: [dynamic, manual] +``` + +```md +type: [network] +``` + #### best-practices Reference platform-specific mitigations or best practices. Automation generates a “Mitigations” section. @@ -75,10 +95,16 @@ 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 prerequisites needed to execute or evaluate the test. Existing files are in prerequisites/. Create new ones if needed. +- If there are no prerequisites, you can omit this field or use an empty list. + Example: ```md @@ -89,7 +115,10 @@ prerequisites: #### profiles -Specify MASVS profiles where the test applies. Valid values: L1, L2, P. +Specify MASVS profiles where the test applies. Valid values: L1, L2, P, R. + +- P denotes Privacy. +- R denotes Resilience. Example: @@ -106,6 +135,10 @@ Include these if relevant: - `available_since:` minimum platform/API level - `deprecated_since:` last applicable platform/API level +Notes: + +- For Android, available/deprecated API levels are integers (for example, `deprecated_since: 24`). For iOS, use the iOS release version (for example, `available_since: 13`). + ### Markdown: Body #### Overview diff --git a/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md b/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md index 93af7f2aa35..d845d694484 100644 --- a/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md +++ b/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md @@ -1,13 +1,15 @@ -# Porting MASTG v1 Tests to v2 +## Porting MASTG v1 tests to v2 -### Writing content +### Before you start + +This document focuses on the porting workflow. For how to write v2 tests (front matter fields, required sections, styles), see `mastg-test.instructions.md`. Do not duplicate that guidance here—follow it when drafting the ported test. Check some of the current tests and take them as reference * tests-beta * demos -Always take the most recent tests (the ones with the highest IDs) as reference/template. +Always take the most recent tests (the ones with the highest IDs) as reference/template. Use `tests-beta` files as the canonical template for structure and front matter. Also review these. We’ll be using them and creating new ones as well: @@ -34,9 +36,8 @@ Also review these. We’ll be using them and creating new ones as well: **About the IDs:** -* Turn MASTG-TEST-0017 \-\> MASTG-TEST-0x17 -* If you need to split then do like MASTG-TEST-0x17-1, MASTG-TEST-0x17-2, MASTG-TEST-0x17-3 … -* We’ll take care of fixing the IDs before merging. +- Use the decimal ID format as seen in `tests-beta` (for example, `MASTG-TEST-0233`). Do not use the `0x` notation. +- If a test must be split, suffix with a short decimal part during drafting (for example, `MASTG-TEST-0233-1`, `MASTG-TEST-0233-2`). Coordinate final IDs before merging. **Language**: use simple language, be concise and clear @@ -62,48 +63,47 @@ Use the MASTG first, e.g. the guides for 0x04 (general), 0x05 (Android) and 0x06 - [https://developer.apple.com/app-store/user-privacy-and-data-use/](https://developer.apple.com/app-store/user-privacy-and-data-use/) -## Porting tests to V2 +## Porting workflow Map to MASWE. You can check the new MASWE by searching for the old test ID in the **weaknesses/** directory. For example MASTG-TEST-0017. -Create a branch for the ticket: port-MASTG-TEST-0017 +1) Create a branch for the ticket: `port-MASTG-TEST-0017` (adjust ID). -If the “MASVS” folder does not exist yet, create it. +2) Place files correctly: If the relevant `MASVS-*` folder does not exist yet under `tests-beta//`, create it. -Name the new file MASTG-TEST-0x17.md \-\> We’ll use the x to avoid ID collision and we’ll rename them later. +3) Name the new file using the decimal ID (for example, `MASTG-TEST-0233.md`). -* Turn MASTG-TEST-0017 \-\> MASTG-TEST-0x17 -* If you need to split then do like MASTG-TEST-0x17-1, MASTG-TEST-0x17-2, MASTG-TEST-0x17-3 … +4) Decide scope changes: One v1 test may become one or multiple v2 tests (or be merged). Capture only what is testable and actionable; move general theory elsewhere (see below). -One test in V1 may be turned into one or multiple tests in v2. Sometimes you'll find one sentence and that can be converted into a new test. +5) Gather references: Search for references in `Document/`, `techniques/`, `tools/`, and `knowledge/`. -Search for references in the current **Document/** +6) Normalize background vs test logic: Add platform background as @MASTG-KNOW-xxxx references. If none exists, create a new knowledge page. Keep the test focused on detection and evaluation. -And add them as +7) Link general concepts to Document: Some content belongs in the Document chapter. For example, general cryptography concepts such as symmetric/asymmetric encryption, hashing, signing, etc. If the knowledge is still in `Document/`, link to it. -`["Confirm Credential Flow"](../../../Document/0x05f-Testing-Local-Authentication.md#confirm-credential-flow)` +Example: ["Post Quantum"](https://mas.owasp.org/MASTG/Document/0x04g-Testing-Cryptography/#post-quantum) -We don’t want to duplicate information. You may summarize part of the other section but what’s important is to explain what can go wrong with that feature or API. That may be explained in the referenced section or not but it must be in the test because that’s gonna be what we’re going to test for. +8) Avoid duplication: You may summarize, but focus the test on how to detect the issue in Android/iOS and why it matters for this test. -The thing we’re testing for must also have a very specific mitigation. +9) Link mitigations: Ensure there is a clear mitigation in best-practices; add the reference in front matter (field defined in `mastg-test.instructions.md`). -Part of the test not relevant? Remove and add a note in the ticket. +10) Trim non-essential parts: If parts of the v1 test aren’t relevant, remove them and note it in the ticket. -**Example:** In MASTG-TEST-0017, what’s written in dynamic analysis does not make sense: why should we validate that setUserAuthenticationValidityDurationSeconds are for real (we are not testing if Android features work; we assume they do). Maybe we could also use dynamic analysis but following a different approach. +**Example:** In MASTG-TEST-0017, what’s written in dynamic analysis does not make sense: why should we validate that `setUserAuthenticationValidityDurationSeconds` are for real (we are not testing if Android features work; we assume they do). Maybe we could also use dynamic analysis but following a different approach. -Add missing links to docs. +11) Fill missing links to docs and developer references as needed. **Example:** this test and the referenced section both were missing links to [https://developer.android.com/](https://developer.android.com/) -## Important to consider when working on a test +## Porting considerations -V1 tests may include **techniques**, **tools** and even theory. Move that Info to the right place or create it and use references. e.g. @MASTG-TECH-0002 +V1 tests often include techniques, tools, and theory/knowledge. Move that to the right place (or create it) and reference it (for example, @MASTG-TECH-0002, @MASTG-KNOW-0011, @MASTG-TOOL-0097). In the test body, use `@` prefixes; in YAML front matter, use bare IDs without `@`. For exact field names and section structure, see `mastg-test.instructions.md`. -Theory must be always linked to the 0x04/5/6 chapters. +Theory must be always linked to the @MASTG-KNOW-xxxx components. If the theory is not covered yet, create a new knowledge page. If it's a general concept, it may still belong in the Document chapter under 0x04. Review existing content and **UPDATE** it. Especially references to Android/iOS versions and things you know have changed since the text was written. -#### Add Best Practices +#### Best practices linkage Best practices are platform specific and can be linked in the test metadata. Our automation creates a “Mitigations” section automatically. @@ -113,24 +113,25 @@ Best practices are platform specific and can be linked in the test metadata. Our #### Deprecating V1 tests -Add metadata: +Add metadata to the v1 file: + +- `status: deprecated` +- `covered_by: [MASTG-TEST-02xx]` (leave empty if no coverage) +- `deprecation_note: "New version available in MASTG V2"` -`"status: deprecated"` -`"covered_by: [MASTG-TEST-02xx]" (leave empty if no coverage)` -`deprecation_note: "New version available in MASTG V2"` If the test isn’t covered in MASVS v2, enter the reason why. -If you don't know, open a ticket "Add Deprecation Note for MASTG-TEST-01xx". +If you don't know, open a ticket "Add Deprecation Note for MASTG-TEST-00xx". -### Threat based +### Threat-based alignment -Some things we're testing are only an issue if you consider an attacker with root access (typically L2 weaknesses). Double check that the conditions of the test matches the profile of the associated MASWE. IF THERE'S A MISMATCH WE MAY CREATE A SEPARATE MASWE FOR IT BECAUSE IT REPRESENTS A DIFFERENT RISK. +Some findings apply only with stronger attacker capabilities (for example, root/jailbreak—typically L2). Double-check the threat model against the MASWE profile. If there’s a mismatch, consider creating a separate MASWE. [https://mas.owasp.org/MASTG/tests/android/MASVS-PLATFORM/MASTG-TEST-0010/\#dynamic-analysis](https://mas.owasp.org/MASTG/tests/android/MASVS-PLATFORM/MASTG-TEST-0010/#dynamic-analysis) -Pay special attention to things like this. Indicate if the thing you're testing for requires root to be exploited or not. +Indicate in the test whether exploitation requires root/jailbreak. -*On devices supporting file-based encryption (FBE) ↗, snapshots are stored in the /data/system\_ce/\/\ folder. \ depends on the vendor but most common names are snapshots and recent\_images. If the device doesn't support FBE, the /data/system/\ folder is used.* +> *On devices supporting file-based encryption (FBE) ↗, snapshots are stored in the /data/system\_ce/\/\ folder. \ depends on the vendor but most common names are snapshots and recent\_images. If the device doesn't support FBE, the /data/system/\ folder is used.* Accessing these folders and the snapshots requires root. @@ -147,7 +148,7 @@ What other things to consider here? ### Code Snippets -If the test has snippets, you can use them for the new demos. Rewrite any existing snippets and AVOID JAVA AND OBJECTIVE C. +If the v1 test has snippets that inspire a demo, prefer Kotlin and Swift for new examples (avoid Java/Objective-C). You can create a demo with `status: draft` and finish later. See `mastg-demo.instructions.md` for demo authoring. You can create a demo **status: draft** and come back later to it. Just to ensure we extracted everything from V1. Create a ticket **"Finish Demo Draft MASTG-DEMO-xxxx"** @@ -158,36 +159,23 @@ You can create a demo **status: draft** and come back later to it. Just to ensur List of apps to get ideas from, as inspiration. You may include "inspired by" to ref to the original source whenever our new content is similar enough. -### NOTES +### Notes (keep in mind while porting) -* platform: android, ios or network -* -* A test MUST NOT describe the general problem *again*. That’s the Weakness’ job. Focus on how that thing happens in Android / iOS and why it’s important to do this test. -* A test can be \[static, dynamic\] and the steps are describing both - * Example: MASTG-TEST-0209 - * 1\. Run a static analysis tool such as @MASTG-TOOL-0073 on the app binary, or use a dynamic analysis tool like @MASTG-TOOL-0039, and look for uses of the cryptographic functions that generate keys. - * The demos are going to be more specific and address static and dynamic separately - * If you find an edge case, let’s discuss it. - * e.g. just because *the way* something is tested it could deserve a separate test with its own distinct overview, steps, etc. +- A test must not describe the general problem again (that’s the Weakness’ job). Keep the test focused on detection and evaluation. +- If you find an edge case, consider whether it deserves a separate test with distinct steps/evaluation. ### OS version **For Android:** We have agreed on supporting the **current version \- 5**. This gives a roughly 90% adoption rate on average. See [https://apilevels.com/](https://apilevels.com/) -If a test is not applicable anymore in some OS versions we can create it with a note of the versions where it applies. This way if you're testing an app that has a minsdk greater than that, you can discard that test. +If a test is no longer applicable for some OS versions, add an applicability note so testers can discard it when not relevant. + +Avoid creating demos for unsupported versions. -We will avoid creating demos for unsupported versions. +For example, WebView file access or defaults depend on this. -e.g. webviews file access or defaults depend on this. +Refer to `mastg-test.instructions.md` for: -```md ---- -platform: android -title: Insecure Implementation of Confirm Credentials -id: MASTG-TEST-0x017 -type: [static, dynamic] -available_since: 21 -deprecated_since: 29 -weakness: MASWE-0034 ---- -``` \ No newline at end of file +- Exact front matter fields and examples +- Required sections (Overview, Steps, Observation, Evaluation) +- Title conventions, platforms, profiles, types, and optional fields \ No newline at end of file From 21a678ce1f92ec50bed56c6b8d43a593ef0213a8 Mon Sep 17 00:00:00 2001 From: Carlos Holguera Date: Mon, 1 Sep 2025 10:32:38 +0200 Subject: [PATCH 07/20] update app instructions --- .../instructions/mastg-apps.instructions.md | 109 ++++++++---------- 1 file changed, 46 insertions(+), 63 deletions(-) diff --git a/.github/instructions/mastg-apps.instructions.md b/.github/instructions/mastg-apps.instructions.md index 5c5316f0f61..3729d40ded6 100644 --- a/.github/instructions/mastg-apps.instructions.md +++ b/.github/instructions/mastg-apps.instructions.md @@ -1,40 +1,42 @@ -## Reference Apps +# Reference Apps Authoring Instructions -Authoring standards for reference application pages under `apps/`. These list vulnerable or exemplar applications used across tests, techniques, and demos. +Standards for authoring reference application pages under `apps/`. These pages describe vulnerable or exemplar applications used across tests, techniques, and demos. -Locations: +## Locations - `apps/android/MASTG-APP-####.md` - `apps/ios/MASTG-APP-####.md` -- `apps/index.md` is the catalog landing page. +- `apps/index.md` is the catalog landing page -File naming and IDs: +## File naming and IDs -- The app ID is defined by the filename: `MASTG-APP-\d{4}.md`. -- Do not add an `id:` field to the YAML front matter for apps. -- Use the next available number within the platform folder. Coordinate in PRs to avoid collisions. +- The app ID is defined by the filename: `MASTG-APP-\d{4}.md` +- Do not add an `id:` field to the YAML front matter +- Use the next available number within the platform folder. Coordinate in PRs to avoid collisions -Follow the global Markdown rules (see `.github/instructions/markdown.instructions.md`). Use `##` and `###` headings in the body. +## Markdown structure -### Markdown: Metadata +- Follow the global Markdown rules in `.github/instructions/markdown.instructions.md` +- Headings in the body start at `##`. Use `##` and `###` only -Include a YAML front matter block with these fields. +## Metadata -Required: +Each file begins with a YAML front matter block. -- `title:` App name with a disambiguator if needed (for example, "Android UnCrackable L1"). -- `platform:` One of: `android`, `ios`. -- `source:` Canonical page to obtain the app (official repo, release artifact, or MASTG crackmes catalog entry). Prefer a stable, versioned URL when available. +**Required** -Optional: +- `title:` App name, use the official capitalization. Add a disambiguator if needed (for example, *Android UnCrackable L1*) +- `platform:` One of `android`, `ios` +- `package:` Android application package ID or iOS bundle identifier (for example, `com.example.app`) +- `source:` Canonical page to obtain the app (official repo, release artifact, or MASTG crackmes catalog entry). Prefer a stable, versioned URL -- `package:` Android applicationId (for example, `com.example.app`). -- `bundle:` iOS bundle identifier (for example, `com.example.app`). -- `store:` Store listing URL (Google Play, App Store) if relevant. -- `status:` `draft`, `placeholder`, or `deprecated`. -- `note:` Short clarifying note (for example, prerequisites or license). +**Optional** -Examples: +- `download_url`: URL to download the APK/IPA. +- `store_url:` Store listing URL if relevant (e.g. Google Play, App Store) +- `status:` use `placeholder` only if it's a draft, otherwise do not include `status` (default is `new` and you don't have to add it explicitly) + +**Examples** ```yaml --- @@ -43,65 +45,46 @@ platform: android source: https://mas.owasp.org/crackmes/Android#android-uncrackable-l1 package: sg.vantagepoint.uncrackable1 --- -``` +```` ```yaml --- title: iGoat-Swift platform: ios source: https://github.com/OWASP/iGoat-Swift -bundle: org.owasp.iGoat-Swift +package: org.owasp.iGoat-Swift +status: placeholder --- ``` -### Markdown: Body - -Keep entries short and purely referential; avoid duplicating installation or usage docs that belong in the app’s own repo. - -Recommended sections: - -- Overview: One or two sentences describing the app and what it’s useful for. -- Acquisition: Where to download (link to releases or IPA/APK/APP sources). Include brief notes if side-loading is required. -- Notes: Any platform-specific setup hints (e.g., jailbreak/root expectations, certificate installation for proxies). -- Related: Cross-link to tests, techniques, and demos that commonly use this app. +## Body content -Cross-linking rules: +Entries should be short and referential. Do not duplicate installation or usage docs that belong in the app’s own repository. -- In body text, reference project identifiers with a leading `@` (for example, @MASTG-TEST-0204, @MASTG-TECH-0014, @MASTG-TOOL-0031). -- In YAML front matter, always use bare identifiers without the `@`. +- One or two sentences describing the app and its purpose +- Add any platform-specific hints such as jailbreak expectations or proxy setup -### Writing conventions +### Cross-linking -- Use the official app name and capitalization as used by the project. -- Prefer official sources (original repo or the MASTG Crackmes catalog) for download links. -- If the original source is gone, mark the page with `status: deprecated` and provide a short `note:` explaining why. +In YAML front matter add `weaknesses` listing all the weaknesses from the MASWE that can be tested and are present in the app. -### Example +Example: -````markdown -## Overview - -Android UnCrackable L1 is a purposely vulnerable application designed to practice reverse engineering and tampering techniques. - -## Acquisition - -- Crackmes catalog: https://mas.owasp.org/crackmes/Android#android-uncrackable-l1 -- APK file is provided via the crackmes page. +```md +weaknesses: [MASWE-0034, MASWE-0056] +``` -## Notes +Do not add specific app versions here. If a MASTG-DEMO requires a specific version of an app, document it in the demo, not in the app entry. -- Designed for analysis on emulators and physical devices. -- Works well with @MASTG-TOOL-0031 and @MASTG-TECH-0045. +## Writing conventions -## Related +- Use the official app name and capitalization +- Prefer official sources or the MASTG Crackmes catalog for downloads -- Tests: @MASTG-TEST-0252, @MASTG-TEST-0263 -- Techniques: @MASTG-TECH-0039, @MASTG-TECH-0045 -```` +## Deprecation -### Edge cases and guidance +If the original source is gone, not relevant anymore, or too old, set the following in the YAML front matter: -- Open-source apps: Prefer linking to release artifacts (APK/IPA) rather than build-from-source instructions unless needed. -- Store-only apps: Use `store:` for the listing and add a short note if side-loading a specific version is necessary for reproducibility. -- Version specificity: When tests/demos require a specific version, state it clearly in the demo/test, not in the app entry; keep the app page evergreen. -- Deprecation: If an app becomes unavailable, set `status: deprecated` and add a `note:` with context and, if possible, a suggested replacement. +- `status:` Must be set to `deprecated` +- `deprecation_note:` Short clarifying note for deprecation. Keep phrasing concise and imperative +- `covered_by:` List of MASTG-APP-xxxx apps covering for this one, if any. From 0290aaca87826094b8af0e6571159d01a4527726 Mon Sep 17 00:00:00 2001 From: Carlos Holguera Date: Mon, 1 Sep 2025 10:45:04 +0200 Subject: [PATCH 08/20] more improvements for apps --- .github/instructions/mastg-apps.instructions.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/.github/instructions/mastg-apps.instructions.md b/.github/instructions/mastg-apps.instructions.md index 3729d40ded6..2cfc17aeb33 100644 --- a/.github/instructions/mastg-apps.instructions.md +++ b/.github/instructions/mastg-apps.instructions.md @@ -6,7 +6,7 @@ Standards for authoring reference application pages under `apps/`. These pages d - `apps/android/MASTG-APP-####.md` - `apps/ios/MASTG-APP-####.md` -- `apps/index.md` is the catalog landing page +- `apps/index.md` is the catalog landing page (don't edit it) ## File naming and IDs @@ -45,16 +45,6 @@ platform: android source: https://mas.owasp.org/crackmes/Android#android-uncrackable-l1 package: sg.vantagepoint.uncrackable1 --- -```` - -```yaml ---- -title: iGoat-Swift -platform: ios -source: https://github.com/OWASP/iGoat-Swift -package: org.owasp.iGoat-Swift -status: placeholder ---- ``` ## Body content From 97f70a8bd3f3a3162c45aeb68b1273ce0d56cb82 Mon Sep 17 00:00:00 2001 From: Carlos Holguera Date: Mon, 1 Sep 2025 10:45:17 +0200 Subject: [PATCH 09/20] update tools instructions --- .../instructions/mastg-tools.instructions.md | 144 ++++++++---------- 1 file changed, 66 insertions(+), 78 deletions(-) diff --git a/.github/instructions/mastg-tools.instructions.md b/.github/instructions/mastg-tools.instructions.md index 95a0c4069f7..7f03f968f10 100644 --- a/.github/instructions/mastg-tools.instructions.md +++ b/.github/instructions/mastg-tools.instructions.md @@ -1,44 +1,45 @@ -## Tools +# Tools Authoring Instructions -Authoring standards for tool reference pages under `tools/`. These pages document tools used throughout tests, demos, and techniques in the MASTG. +Standards for authoring tool reference pages under `tools/`. These pages document tools used throughout tests, demos, and techniques in the MASTG. -Locations: +## Locations - `tools/android/MASTG-TOOL-####.md` - `tools/ios/MASTG-TOOL-####.md` - `tools/generic/MASTG-TOOL-####.md` (cross-platform or platform-agnostic tools) - `tools/network/MASTG-TOOL-####.md` (traffic analysis and proxying) +- `tools/index.md` is the catalog landing page (don't edit it) -File naming: +## File naming and IDs -- The tool ID is defined by the filename: `MASTG-TOOL-\d{4}.md`. -- Do not add an `id:` field to the YAML front matter for tools. -- Use the next available number for the target folder. Coordinate in PRs to avoid clashes. +- The tool ID is defined by the filename: `MASTG-TOOL-\d{4}.md` +- Do not add an `id:` field to the YAML front matter +- Use the next available number for the target folder. Coordinate in PRs to avoid clashes -Follow the global Markdown rules (see `.github/instructions/markdown.instructions.md`) for headings, images, code blocks, and style. +## Markdown structure -### Markdown: Metadata +- Follow the global Markdown rules in `.github/instructions/markdown.instructions.md` +- Headings in the body start at `##`. Use `##` and `###` only -Include a YAML front matter block with these fields. +## Metadata -Required: +Each file begins with a YAML front matter block. -- `title:` Concise tool name. Add a qualifier when needed to disambiguate (for example, "Frida for Android", "nm - iOS"). -- `platform:` One of: `android`, `ios`, `generic`, `network`. +**Required** -Optional: +- `title:` Concise tool name. Add a qualifier when needed to disambiguate (for example, "Frida for Android", "nm - iOS") +- `platform:` One of: `android`, `ios`, `generic`, `network` +- `source:` Canonical homepage or repository URL +- `host:` List of operating systems the tool runs on. Allowed values (case-sensitive): `windows`, `linux`, `macOS`, `ios`, `android` + - Use `host:` with a YAML list (preferred). If you find `hosts:` in legacy pages, migrate to `host:` when touching the file + - Use `ios` or `android` for on-device tools (for example, Filza) -- `source:` Canonical homepage or repository URL. -- `host:` List of operating systems the tool runs on. Prefer this exact set (case-sensitive values): `windows`, `linux`, `macOS`, `ios`, `android`. - - Use `host:` with a YAML list (preferred). If you find `hosts:` in legacy pages, migrate to `host:` when touching the file. - - Use `ios` / `android` for on-device tools (for example, Filza). -- `alternatives:` List of tool IDs that provide comparable functionality. -- `status:` `draft`, `placeholder`, or `deprecated`. -- `deprecation_note:` Short justification and replacement guidance (required when `status: deprecated`). -- `covered_by:` List of tool IDs that supersede this tool (required when `status: deprecated`). -- `note:` Short free-form note to clarify scope or limitations. +**Optional** -Examples: +- `alternatives:` List of tool IDs that provide comparable functionality (YAML list of IDs only) +- `status:` One of `draft`, `placeholder`, `deprecated`. If absent, the default is `new` + +**Examples** ```yaml --- @@ -46,74 +47,61 @@ title: Frida for Android platform: android source: https://github.com/frida/frida host: [windows, linux, macOS] -alternatives: - - MASTG-TOOL-0031 # Frida (generic) ---- -``` - -```yaml ---- -title: Cycript -platform: ios -source: https://www.cycript.org/ -status: deprecated -deprecation_note: Cycript is no longer maintained and fails on modern iOS versions. Prefer Frida which is actively supported and more capable. -covered_by: [MASTG-TOOL-0039] --- ``` -### Markdown: Body - -Keep pages practical, scannable, and focused on security testing use. Use `##` and `###` headings. +## Body content -Recommended section outline: +Keep pages practical, scannable, and focused on security testing use. -- Overview: One short paragraph describing what the tool is and where it fits. -- Capabilities and Use Cases: Bullet list of relevant features for mobile testing. -- Installation: Platform-specific notes (link out to official docs when appropriate). Include the minimal, verified commands to get started. -- Usage: Common commands, flags, or workflows relevant to MASTG tests/demos. Prefer concrete, copyable examples. -- Examples: Short, targeted examples for typical tasks. If examples are long, link to demos or techniques instead. -- Caveats and Limitations: Version compatibility, jailbreak/root requirements, known issues. -- References: Links to official docs, repos, and authoritative resources. -- Related: Cross-link to relevant tests, demos, and techniques. +### Recommended content -Cross-linking rules: +- Overview: One short paragraph describing what the tool is and where it fits +- Capabilities and Use Cases: Bullet list of relevant features for mobile testing +- Installation: Platform-specific notes (link out to official docs when appropriate). Include minimal, verified commands to get started +- Usage: Common commands, flags, or workflows relevant to MASTG tests and demos. Prefer concrete, copyable examples +- Examples: Short, targeted examples for typical tasks. If examples are long, link to demos or techniques instead +- Caveats and Limitations: Version compatibility, jailbreak or root requirements, known issues +- References: Links to official docs, repos, and authoritative resources +- Related: Cross-link to relevant tests, demos, and techniques -- In body text, reference project identifiers with a leading `@` (for example, @MASTG-TEST-0204, @MASTG-TOOL-0031, @MASTG-TECH-0014). -- In YAML front matter, always use bare identifiers without the `@`. +### Cross-linking -Example snippets: +- Do not cross-link here to tests, demos, and techniques, etc. +- Those components will cross-link to tools, typically techniques and demos +- To do that they must add @MASTG-TOOL-0031 in their markdown body or as `tools: [MASTG-TOOL-0031]` in their YAML front matter -````markdown -## Usage +## Conventions and quality -List running apps and attach to a process: +- Prefer official sources for installation steps. Avoid advertising or endorsing third-party distributions +- Favor commands that work across supported hosts when possible. Otherwise clearly label host-specific commands +- For images, use HTML `` tags per the markdown instructions (store assets in an appropriate images folder if needed) +- Keep examples minimal and verifiable. Longer walkthroughs belong in demos with runnable scripts -```sh -frida-ps -Uai -frida -U -n com.example.app -l hook.js -``` - -See @MASTG-TECH-0014 for guidance on dynamic method tracing and @MASTG-TEST-0252 for a test that benefits from this tool. -```` +## How tests and demos should reference tools -````markdown -## References +- Tests and demos should reference tools by ID whenever available: + - In body text: `@MASTG-TOOL-0031` + - In YAML (for example, demo `tools:` list): `MASTG-TOOL-0031` +- If a commonly used tool lacks an official MASTG tool page, demos may temporarily list the tool by name (for example, `tools: [semgrep]`). Prefer adding a tool page and switching to the ID in follow-ups -- GitHub: https://github.com/frida/frida -- Docs: https://frida.re/docs/home/ -```` +## Deprecation -### Conventions and Quality +If the original source is gone, not relevant anymore, or too old, set the following in the YAML front matter: -- Prefer official sources for installation steps; avoid advertising or endorsing third-party distributions. -- Favor commands that work across supported hosts when possible; otherwise clearly label host-specific commands. -- For images, use HTML `` tags per the markdown instructions (store assets in an appropriate images folder if needed). -- Keep examples minimal and verifiable; longer walkthroughs belong in demos with runnable scripts. +- `status:` Must be set to `deprecated` +- `deprecation_note:` Short clarifying note for deprecation. Keep phrasing concise and imperative +- `covered_by:` List of MASTG-TOOL-xxxx tools covering for this one, if any. -### How tests and demos should reference tools +**Example** -- Tests and demos should reference tools by ID whenever available: - - In body text: `@MASTG-TOOL-0031`. - - In YAML (for example, demo `tools:` list): `MASTG-TOOL-0031`. -- If a commonly used tool lacks an official MASTG tool page, demos may temporarily list the tool by name (for example, `tools: [semgrep]`). Prefer adding a tool page and switching to the ID in follow-ups. +```yaml +--- +title: Cycript +platform: ios +source: https://www.cycript.org/ +status: deprecated +deprecation_note: Cycript is no longer maintained and fails on modern iOS versions. Prefer Frida which is actively supported and more capable +covered_by: [MASTG-TOOL-0039] +--- +``` \ No newline at end of file From becd48c1790f831abad0340da075692abb4ae0b5 Mon Sep 17 00:00:00 2001 From: Carlos Holguera Date: Mon, 1 Sep 2025 15:59:14 +0200 Subject: [PATCH 10/20] more improvements --- .../mastg-frida-scripts.instructions.md | 100 +++++++----------- .../mastg-knowledge.instructions.md | 93 ++++++---------- .../instructions/mastg-rules.instructions.md | 28 ++--- .../instructions/mastg-test.instructions.md | 19 ++-- 4 files changed, 94 insertions(+), 146 deletions(-) diff --git a/.github/instructions/mastg-frida-scripts.instructions.md b/.github/instructions/mastg-frida-scripts.instructions.md index 766c26cb48f..4a55748698c 100644 --- a/.github/instructions/mastg-frida-scripts.instructions.md +++ b/.github/instructions/mastg-frida-scripts.instructions.md @@ -18,66 +18,55 @@ Examples: ### Runtime and invocation -- Prefer the V8 runtime unless a different engine is necessary; you can enforce it with `--runtime=v8`. - Typical spawn usage in `run.sh`: - - `frida -U -f -l script.js --no-pause --runtime=v8 > output.txt` -- Typical attach usage: - - `frida -U -n -l script.js --runtime=v8 > output.txt` + - `frida -U -f -l script.js -o output.txt` ### Coding conventions - Keep scripts self-contained (no external module imports). - Keep output concise and deterministic for Evaluation parsing. -- Validate availability before hooking: - - iOS: `if (ObjC.available) { ... }` - - Android: `Java.perform(() => { ... })` - Check class/method existence; log a clear message if missing. - Avoid global side effects; scope variables within hooks/functions. - Logging: prefer `console.log()`; add short section headers only when helpful. - Backtraces: use `DebugSymbol.fromAddress` and cap lines. - In `onEnter/onLeave`, capture context first (for example, `const ctx = this.context;`) before using nested arrow functions. -### iOS patterns - -- Hook Objective-C methods with explicit `-` (instance) or `+` (class) signatures. -- Example (LAContext evaluatePolicy): - -````javascript -if (ObjC.available && ObjC.classes.LAContext) { - const method = ObjC.classes.LAContext["- evaluatePolicy:localizedReason:reply:"]; - if (method) { - Interceptor.attach(method.implementation, { - onEnter(args) { - const ctx = this.context; - const LAPolicy = { 1: ".deviceOwnerAuthenticationWithBiometrics", 2: ".deviceOwnerAuthentication" }; - const policy = args[2].toInt32(); - console.log(`LAContext.evaluatePolicy called with ${LAPolicy[policy] || "Unknown"} (${policy})`); - const bt = Thread.backtrace(ctx, Backtracer.ACCURATE).slice(0, 8).map(DebugSymbol.fromAddress); - console.log("Backtrace:\n" + bt.join("\n")); - } - }); - } else { - console.log("LAContext.evaluatePolicy not found"); - } -} else { - console.log("ObjC runtime not available or LAContext missing"); -} -```` - -### Android patterns - -- Wrap hooks in `Java.perform` and use `Java.use` to access classes. -- Example: - -````javascript -Java.perform(() => { - const HttpsURLConnection = Java.use('javax.net.ssl.HttpsURLConnection'); - HttpsURLConnection.setHostnameVerifier.overload('javax.net.ssl.HostnameVerifier').implementation = function (verifier) { - console.log('HttpsURLConnection.setHostnameVerifier called'); - return this.setHostnameVerifier(verifier); - }; +### Inspiration + +- Don't reinvent the wheel when something already exists. Use existing open-source sources when available, for example https://codeshare.frida.re/browse. +- If you use a source be sure to document it and give creadit to the author. Include a link to the original source in a comment at the beginning of the frida script. + +Example: + +```js +// SOURCE: https://codeshare.frida.re/@TheDauntless/disable-flutter-tls-v1/ + +// Configuration object containing patterns to locate the ssl_verify_peer_cert function for different platforms and architectures. +var config = { + "ios":{ + "modulename": "Flutter", + "patterns":{ + "arm64": [ + ... +``` + +```js +// SOURCE: https://github.com/iddoeldor/frida-snippets?tab=readme-ov-file#os-log + +var m = 'libsystem_trace.dylib'; +// bool os_log_type_enabled(os_log_t oslog, os_log_type_t type); +var isEnabledFunc = Module.findExportByName(m, 'os_log_type_enabled'); +// _os_log_impl(void *dso, os_log_t log, os_log_type_t type, const char *format, uint8_t *buf, unsigned int size); +var logFunc = Module.findExportByName(m, '_os_log_impl'); + +// Enable all logs +Interceptor.attach(isEnabledFunc, { + onLeave: function (ret) { + ret.replace(0x1); + } }); -```` +... +``` ### Logging and outputs @@ -91,21 +80,4 @@ Java.perform(() => { - If a symbol/method is missing, log and continue. - Spawn vs attach: use `-f` for early instrumentation when needed. - Consider stripped binaries and symbol resolution; prefer Objective-C/Java-level hooks over raw native symbols where possible. - -### Cross-links - -- Tools: @MASTG-TOOL-0031 (Frida) -- Techniques: @MASTG-TECH-0045 (Runtime Reverse Engineering), @MASTG-TECH-0015 / @MASTG-TECH-0067 (Dynamic Analysis) - -### Alignment with Tools/Frida - -- The authoritative reference for installing, configuring, and troubleshooting Frida lives under Tools: @MASTG-TOOL-0031. Do not duplicate setup steps in demos; instead, link to the Tools page. - Version compatibility: ensure `frida-tools` (CLI on the host) and the device runtime (for example, `frida-server` on Android or injected runtime on iOS) use matching major/minor versions (17.x with 17.x). -- Device and transport flags: align with Tools documentation and prefer these consistently in `run.sh`: - - `-U` USB default device - - `-D ` a specific device by ID - - `-H ` network/remote device (for example, when port-forwarding or remote frida-server) -- Platform notes (defer details to Tools page): - - Android: frida-server typically runs on-device; you may use adb port-forwarding when targeting `-H`. - - iOS: non-jailbroken workflows don’t need frida-server; rely on USB transport. Jailbroken workflows might use frida-server; follow the Tools guidance. -- Demo authors should: link to Tools for environment prep, keep `script.js` runtime-agnostic, and focus scripts on instrumentation logic, not environment management. \ No newline at end of file diff --git a/.github/instructions/mastg-knowledge.instructions.md b/.github/instructions/mastg-knowledge.instructions.md index 3cc48dacf68..c6f3e462924 100644 --- a/.github/instructions/mastg-knowledge.instructions.md +++ b/.github/instructions/mastg-knowledge.instructions.md @@ -1,6 +1,6 @@ -## Knowledge Base +## Knowledge Articles -Authoring standards for the Knowledge Base 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. +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/`. Locations and taxonomy: @@ -30,12 +30,10 @@ Required: Optional: -- `status:` `draft`, `placeholder`, or `deprecated`. -- `note:` Short free-form note to clarify scope. +- `best-practices:` Reference platform-specific mitigations or best practices from `best-practices/`, when relevant. +- `status:` `placeholder`, or `deprecated`. - `available_since:` Minimum platform/API level (Android: integer API level; iOS: release version, for example `13`). - `deprecated_since:` Last applicable platform/API level. -- `deprecation_note:` If deprecated, add a short rationale and replacement guidance. -- `covered_by:` List of knowledge IDs that supersede this page (use bare IDs). Examples: @@ -48,35 +46,18 @@ available_since: 18 --- ``` -```yaml ---- -masvs_category: MASVS-AUTH -platform: android -title: FingerprintManager -available_since: 23 -deprecated_since: 28 -status: deprecated -deprecation_note: The FingerprintManager class is deprecated in Android 9 (API level 28). Prefer BiometricPrompt or the Biometric library. -covered_by: [MASTG-KNOW-0001] ---- -``` - ### Markdown: Body -Keep content authoritative, concise, and platform-focused. Avoid duplicating OS documentation; cite it and summarize what the feature is and how it works. Do not prescribe how to use it securely; move guidance to Best Practices and link to it. - -Recommended sections: +Keep content authoritative, concise, and platform-focused. Avoid duplicating OS documentation; cite it and summarize what the feature is and how it works. -- Overview: Define the concept and its scope. Relate to OS components, APIs, or security model elements. -- Security Context: Explain typical security-relevant behaviors or implications of the feature without recommending mitigations. -- Platform Details: API names, version nuances, storage locations, configuration knobs. Keep code samples short and explanatory. -- References: Official docs and standards. Avoid non-authoritative sources. -- Related: Cross-link to tests, techniques, tools, and best practices. +Considerations for writing the content: -Cross-linking rules: +- 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"). +- Include specific API names, version nuances, storage locations, configuration knobs. Try to avoid code samples; instead try to refer to 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). -- In body text, reference project identifiers with a leading `@` (for example, @MASTG-TEST-0204, @MASTG-TECH-0014, @MASTG-TOOL-0031, @MASTG-BEST-0011). -- In YAML front matter, always use bare identifiers without the `@`. ### Writing conventions @@ -84,38 +65,32 @@ Cross-linking rules: - Prefer short paragraphs and bullet lists for scannability. - Use HTML `` for images as per the markdown instructions. -### Example - -````markdown -## Overview - -Android KeyStore is a system-provided credential store that keeps cryptographic keys bound to the device and, optionally, to user authentication. Keys can be marked non-exportable and their usage can be limited. - -## Security Context - -- Keys can be hardware-backed depending on device support and OS version. -- Key usage can be constrained (purposes, modes, paddings) and optionally bound to user authentication. - -## Platform Details - -- Introduced in API level 18; many features evolved in later releases. -- Key properties are controlled via KeyGenParameterSpec. +### Edge cases and guidance -## References +- 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, tools always try to link to a knowledge article or create one if it's missing. -- Android docs - Keystore: https://developer.android.com/training/articles/keystore +## Deprecation -## Related +If the original source is gone, not relevant anymore, or too old, set the following in the YAML front matter: -- Tests: @MASTG-TEST-0263 -- Techniques: @MASTG-TECH-0014 -- Tools: @MASTG-TOOL-0033 -- Best practices: @MASTG-BEST-0011 (see this page for actionable guidance) -```` +- `status:` Must be set to `deprecated` +- `deprecation_note:` Short clarifying note for deprecation. Keep phrasing concise and imperative +- `covered_by:` List of MASTG-TOOL-xxxx tools covering for this one, if any. -### Edge cases and guidance +**Example** -- 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. -- Deprecation: Mark with `status: deprecated`, add `deprecation_note`, and point to the replacement via `covered_by` or explicit links. -- 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. +```yaml +--- +masvs_category: MASVS-AUTH +platform: android +title: FingerprintManager +deprecated_since: 28 +available_since: 23 +status: deprecated +deprecation_note: "The FingerprintManager class is deprecated in Android 9 (API level 28) and should not be used for new applications. Instead, use the BiometricPrompt API or the Biometric library for Android." +covered_by: [MASTG-KNOW-0001] +--- +``` \ No newline at end of file diff --git a/.github/instructions/mastg-rules.instructions.md b/.github/instructions/mastg-rules.instructions.md index 76a83f2bd91..9c1a96c7eda 100644 --- a/.github/instructions/mastg-rules.instructions.md +++ b/.github/instructions/mastg-rules.instructions.md @@ -6,7 +6,7 @@ SAST rules live in the `rules/` folder. They are referenced and reused by demos [https://semgrep.dev/docs/getting-started/quickstart/](https://semgrep.dev/docs/getting-started/quickstart/) [https://semgrep.dev/learn](https://semgrep.dev/learn) -[https://academy.semgrep.dev/courses/secure-guardrails](https://academy.semgrep.dev/courses/secure-guardrails) +[https://academy.semgrep.dev/courses/secure-guardrails](https://academy.semgrep.dev/courses/secure-guardrails) Tip: use [https://semgrep.dev/playground/new](https://semgrep.dev/playground/new) for experimentation. @@ -18,19 +18,19 @@ File naming and format Semgrep rules must follow valid syntax: [https://semgrep.dev/docs/writing-rules/rule-syntax/](https://semgrep.dev/docs/writing-rules/rule-syntax/) -Recommended fields per rule - -* **id**: unique, stable identifier. For single-rule files, prefer matching the filename without extension. For multi-rule files, use a common prefix based on the filename and a descriptive suffix (for example, `mastg-android-data-unencrypted-shared-storage-no-user-interaction-mediastore`). -* **severity**: - * INFO - * WARNING - * ERROR -* **languages**: usually `xml` or `java` (we don’t create rules for Kotlin as we work with decompiled Java; use `xml` for AndroidManifest and resource rules). -* **metadata**: must include summary - * summary: Short description of the rule. - * original_source: you may use rules from sources on the internet be sure to check that the license allows this and always link to the original source here. Modify the rule if needed and the license allows for it. -* **message**: must start with a MASVS identifier and concisely explain what the rule is reporting. Prefer a specific control when applicable (for example, `[MASVS-PLATFORM-2]`); otherwise, use the MASVS category tag (for example, `[MASVS-STORAGE]`). -* **patterns**: see [https://semgrep.dev/docs/writing-rules/pattern-syntax/](https://semgrep.dev/docs/writing-rules/pattern-syntax/) +Required fields per rule: + +- **id**: unique, stable identifier. For single-rule files, prefer matching the filename without extension. For multi-rule files, use a common prefix based on the filename and a descriptive suffix (for example, `mastg-android-data-unencrypted-shared-storage-no-user-interaction-mediastore`). +- **severity**: + - INFO + - WARNING + - ERROR +- **languages**: usually `xml` or `java` (we don’t create rules for Kotlin as we work with decompiled Java; use `xml` for AndroidManifest and resource rules). +- **metadata**: must include summary + - summary: Short description of the rule. + - original_source: you may use rules from sources on the internet be sure to check that the license allows this and always link to the original source here. Modify the rule if needed and the license allows for it. +- **message**: must start with a MASVS identifier and concisely explain what the rule is reporting. Prefer a specific control when applicable (for example, `[MASVS-PLATFORM-2]`); otherwise, use the MASVS category tag (for example, `[MASVS-STORAGE]`). +- **patterns**: see [https://semgrep.dev/docs/writing-rules/pattern-syntax/](https://semgrep.dev/docs/writing-rules/pattern-syntax/) Multiple rules per file diff --git a/.github/instructions/mastg-test.instructions.md b/.github/instructions/mastg-test.instructions.md index e524b0e9f4c..c3a85dae0c2 100644 --- a/.github/instructions/mastg-test.instructions.md +++ b/.github/instructions/mastg-test.instructions.md @@ -159,11 +159,11 @@ A test must include one or more steps. Steps can be static, dynamic, manual, or Example, to check app notifications: -1. method trace for related APIs (dynamic) -2. use the app (manual) -3. reverse engineer code or use backtraces and hooks (static) -4. perform taint analysis with controlled values (dynamic) -5. grep traces or integrate "grep" in a frida script (static/dynamic) +1. method trace for related APIs (dynamic) +2. use the app (manual) +3. reverse engineer code or use backtraces and hooks (static) +4. perform taint analysis with controlled values (dynamic) +5. grep traces or integrate "grep" in a frida script (static/dynamic) Example: @@ -175,14 +175,15 @@ Example: Notes: -- Always link to existing techniques and tools by ID (for example, @MASTG-TECH-0014, @MASTG-TOOL-0031) to avoid duplication. -- In body text, use the leading @. In YAML front matter, omit the @ and use bare identifiers. +- Always link to existing MASTG-TECH by ID (for example, @MASTG-TECH-0014) +- Don't reference MASTG-TOOLs directly (this may still be happening in some tests and we must fix it.) +- Be consistent by reusing the steps from existing tests. Do not create new phrasing or wording when it's not necessary. #### Observation The output you get after executing all steps. It serves as evidence. -It should start with “The output should contain …”. +It MUST start with “The output should contain ...”. Example: @@ -196,7 +197,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 should start with “The test case fails if …”. +It MUST start with “The test case fails if ...”. Example: From 43a06ed5cbfbe80b5c5542cfd321cd45793586c8 Mon Sep 17 00:00:00 2001 From: Carlos Holguera Date: Mon, 1 Sep 2025 16:07:58 +0200 Subject: [PATCH 11/20] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/instructions/mastg-demo.instructions.md | 1 - .github/instructions/mastg-test.instructions.md | 2 +- .../porting-mastg-v1-tests-to-v2.instructions.md | 8 ++++---- 3 files changed, 5 insertions(+), 6 deletions(-) diff --git a/.github/instructions/mastg-demo.instructions.md b/.github/instructions/mastg-demo.instructions.md index 2d337fbb4b8..eb319cc46ae 100644 --- a/.github/instructions/mastg-demo.instructions.md +++ b/.github/instructions/mastg-demo.instructions.md @@ -188,7 +188,6 @@ Review each of the reported instances. Note that line 37 did not trigger the rule because the random number is generated using `SecureRandom` which is a secure random number generator. ``` -### ### Code Samples {#code-samples} diff --git a/.github/instructions/mastg-test.instructions.md b/.github/instructions/mastg-test.instructions.md index c3a85dae0c2..82359416e87 100644 --- a/.github/instructions/mastg-test.instructions.md +++ b/.github/instructions/mastg-test.instructions.md @@ -176,7 +176,7 @@ Example: Notes: - Always link to existing MASTG-TECH by ID (for example, @MASTG-TECH-0014) -- Don't reference MASTG-TOOLs directly (this may still be happening in some tests and we must fix it.) +- Don't reference MASTG tools directly (this may still be happening in some tests and we must fix it.) - Be consistent by reusing the steps from existing tests. Do not create new phrasing or wording when it's not necessary. #### Observation diff --git a/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md b/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md index d845d694484..64afbe63c21 100644 --- a/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md +++ b/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md @@ -29,9 +29,9 @@ Also review these. We’ll be using them and creating new ones as well: 3. You may use [chatGPT](https://chat.openai.com/) to create an initial draft and massage the content. 2. Edit it yourself using **your knowledge** 3. **Always include inline references** e.g. to - 1. MASTG chapters - 2. APIs - 3. statements in the dev docs + - MASTG chapters + - APIs + - statements in the dev docs 4. Before pushing, use [deepl write](https://www.deepl.com/en/write) to correct any mistakes and tweak phrasing (especially if you used chatGPT, use deepl to humanize the text) **About the IDs:** @@ -155,7 +155,7 @@ You can create a demo **status: draft** and come back later to it. Just to ensur - [https://github.com/WithSecureLabs/sieve/](https://github.com/WithSecureLabs/sieve/) - Ovaa - MASTG playground -- [https://mas.owasp.org/MASTG/apps/](https://mas.owasp.org/MASTG/apps/) +- [https://mas.owasp.org/MASTG/apps/](https://mas.owasp.org/MASTG/apps/) List of apps to get ideas from, as inspiration. You may include "inspired by" to ref to the original source whenever our new content is similar enough. From a606f7409fdc21d4d3f72bc90df23e6fb442c556 Mon Sep 17 00:00:00 2001 From: Carlos Holguera Date: Sat, 20 Sep 2025 19:28:03 +0200 Subject: [PATCH 12/20] Apply suggestions from code review Co-authored-by: Dionysis Lorentzos --- .github/instructions/mastg-test.instructions.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/instructions/mastg-test.instructions.md b/.github/instructions/mastg-test.instructions.md index 82359416e87..300e0870748 100644 --- a/.github/instructions/mastg-test.instructions.md +++ b/.github/instructions/mastg-test.instructions.md @@ -15,6 +15,7 @@ Example: MASTG-TEST-0204.md MASTG-TEST-0205.md ``` +Each test has two parts: the [Markdown metadata](#markdown-metadata) (YAML `front matter`) and the [Markdown body](#markdown-body). ### Markdown: Metadata @@ -101,7 +102,7 @@ Notes: #### prerequisites -List prerequisites needed to execute or evaluate the test. Existing files are in prerequisites/. Create new ones if needed. +List prerequisites needed to execute or evaluate the test. Existing files are in `prerequisites/`. Create new ones if needed. - If there are no prerequisites, you can omit this field or use an empty list. @@ -116,7 +117,10 @@ prerequisites: #### profiles Specify MASVS profiles where 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) +- L1 denotes Essential Security. +- L2 denotes Advanced Security. - P denotes Privacy. - R denotes Resilience. From 2af006cd288a63ec4379af6e06b1f7f5b48ad6d6 Mon Sep 17 00:00:00 2001 From: Carlos Holguera Date: Sat, 20 Sep 2025 19:48:48 +0200 Subject: [PATCH 13/20] Address comments from the review --- .../instructions/mastg-test.instructions.md | 41 +++++++++++-------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/.github/instructions/mastg-test.instructions.md b/.github/instructions/mastg-test.instructions.md index 300e0870748..f5620e46573 100644 --- a/.github/instructions/mastg-test.instructions.md +++ b/.github/instructions/mastg-test.instructions.md @@ -1,20 +1,29 @@ ## Tests -Tests are platform-specific and must be located under tests-beta/android/ or tests-beta/ios/, within the corresponding MASVS category. Their file names are the test IDs. +A MASWE weakness can have one or more platform-specific tests associated with it. -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/`). +Tests have an [overview](#overview) and contain [Steps](#steps) which produce outputs called [observations](#observation) which must be [evaluated](#evaluation). -Tests have an overview and contain Steps which produce outputs called observations. After following the Steps you come up with an [Observation](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1#heading=h.h9gqgz4hdubj) which you will [Evaluate](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1#heading=h.lare0v58fwbf). +Tests must be located under `tests-beta/android/` or `tests-beta/ios/`, within the corresponding MASVS category. Their file names are the test IDs. -Example: +Example structure: ```sh % ls -1 -F tests-beta/android/MASVS-CRYPTO/ MASTG-TEST-0204.md MASTG-TEST-0205.md ``` + +Example tests for reference: + +- [MASTG-TEST-0207](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0207/) +- [MASTG-TEST-0216](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0216/) +- [MASTG-TEST-0263](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0263/) + +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/`). + Each test has two parts: the [Markdown metadata](#markdown-metadata) (YAML `front matter`) and the [Markdown body](#markdown-body). ### Markdown: Metadata @@ -36,12 +45,6 @@ Follow a consistent style across all test titles. Exceptions may apply where "Runtime ..." feels forced, for example tests using adb, local backups, or filesystem snapshots. -Examples: - -- [MASTG-TEST-0207](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0207/) -- [MASTG-TEST-0216](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0216/) -- [MASTG-TEST-0263](https://mas.owasp.org/MASTG/tests-beta/android/MASVS-STORAGE/MASTG-TEST-0263/) - #### platform The mobile platform. One of: ios, android, network. @@ -62,9 +65,14 @@ The MASWE weakness ID the test references. One or more test types. -Supported: static, dynamic, network, manual, filesystem, developer. +Supported: -- developer: tests that work on developer artifacts or supply-chain outputs (for example SBOM, dependency manager lockfiles, scanner reports) rather than the built app. +- `static`: analysis of the app binary, reverse-engineered source code, or developer artifacts that are available in the APK/IPA app package (e.g., Android manifest, Info.plist, entitlements, etc.). No execution of the app is required. +- `dynamic`: analysis of the app while it is running and involves runtime analysis such as hooking or method tracing. +- `manual`: manual steps that require human judgment, such as inspecting app behavior, UI, or configuration. This may include reverse engineering or runtime analysis that cannot be fully automated. +- `network`: analysis of network traffic, while the app is running. Done externally, for example using a proxy or network capture tool. +- `filesystem`: analysis of the app's file system, including local storage or backups, which doesn't involve runtime analysis such as hooking or method tracing. +- `developer`: tests only the developer can perform because they require access to the source code, build process, or other internal resources. Example: @@ -78,10 +86,6 @@ Examples with multiple types: type: [dynamic, manual] ``` -```md -type: [network] -``` - #### best-practices Reference platform-specific mitigations or best practices. Automation generates a “Mitigations” section. @@ -138,6 +142,7 @@ Include these if relevant: - `note:` short free-form note - `available_since:` minimum platform/API level - `deprecated_since:` last applicable platform/API level +- `apis:` list of relevant APIs Notes: From 77cd364cf51353532ac10c422403d7c138d9f586 Mon Sep 17 00:00:00 2001 From: Carlos Holguera Date: Sat, 20 Sep 2025 20:05:34 +0200 Subject: [PATCH 14/20] Enhance demo instructions for clarity and completeness --- .../instructions/mastg-demo.instructions.md | 27 ++++++++++++++----- 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/.github/instructions/mastg-demo.instructions.md b/.github/instructions/mastg-demo.instructions.md index eb319cc46ae..8ff0215b337 100644 --- a/.github/instructions/mastg-demo.instructions.md +++ b/.github/instructions/mastg-demo.instructions.md @@ -5,13 +5,16 @@ A collection of demos (demonstrative examples) of the test that include working Demos live in `demos/android/` or `demos/ios/` under the corresponding MASVS category folder. Each demo has its own folder named using its ID and contains: * Markdown file: `MASTG-DEMO-xxx.md` -* Code samples (e.g. .kt, .swift, .xml, .plist) -* Testing code (e.g. sh, py) -* Output files (e.g. txt, json, sarif) +* Code samples (e.g. `*.kt`, `*.swift`, `*.xml`, `*.plist`) +* Testing code (e.g. `*.sh`, `*.py`) +* Output files (e.g. `*.txt`, `*.json`, `*.sarif`) -**Language:** The samples are written in **Kotlin** or **Swift**, depending on the platform. In some cases, the samples will also include configuration files such as AndroidManifest.xml or Info.plist. +**Language:** The samples are written in **Kotlin** or **Swift**, depending on the platform. In some cases, the samples will also include configuration files such as `AndroidManifest.xml` or `Info.plist`. -**Decompiled Code:** If the sample can be decompiled, the decompiled code is also provided in the demo (e.g as a Java file on Android: `MastgTest_reversed.java`). This is useful for understanding the code in the context of the application. +**Decompiled Code:** Decompiled code must be provided if the demo involves static analysis. + +- **Android:** Follow the instructions in ["MASTestApp for Android - Run the Extraction Script"](https://github.com/cpholguera/mas-app-android) to obtain the relevant files such as the reversed `AndroidManifest.xml` and the `MastgTest_reversed.java` which is the MASTestApp's main file. Including the full version of these files is also useful for understanding the code in the context of the application, regardless of whether the demo focuses on a specific snippet. +- **iOS:** Follow the instructions in ["MASTestApp for iOS - Reverse Engineering"](https://github.com/cpholguera/MASTestApp-iOS) to obtain the relevant files such as the the IPA file and the reversed `Info.plist` already converted to XML format. Currently you need to manually extract the main binary, MASTestApp, and include it in the demo folder (we allow this for now since the files are sufficiently small). The demos will typically use reverse engineering tools like `r2` on this binary. The **demos MUST WORK**. See [Code Samples](#code-samples). @@ -21,7 +24,7 @@ Demos are required to be **fully self-contained** and should **not rely on exter Please specify the mobile platform version, IDE and version, device. -Example: +Android Example: ```sh % ls -1 -F demos/android/MASVS-CRYPTO/MASTG-DEMO-0007 @@ -33,6 +36,18 @@ output.txt run.sh* ``` +iOS Example: + +```sh +% ls -1 -F ./demos/ios/MASVS-CRYPTO/MASTG-DEMO-0016/ +MASTG-DEMO-0016.md +MASTestApp* +MastgTest.swift +cryptokit_hash.r2 +output.txt +run.sh* +``` + ### Markdown: Metadata #### id From 4f7d5b0dabab369ee688990b9f7bd3c777261ef9 Mon Sep 17 00:00:00 2001 From: Dionysis Lorentzos Date: Thu, 2 Oct 2025 10:55:54 +0200 Subject: [PATCH 15/20] Improve grammar and clarity in markdown instructions. --- .github/instructions/markdown.instructions.md | 18 +++--- .../instructions/mastg-apps.instructions.md | 12 ++-- .../mastg-best-practice.instructions.md | 4 +- .../instructions/mastg-demo.instructions.md | 38 +++++------ .../mastg-frida-scripts.instructions.md | 4 +- .../mastg-knowledge.instructions.md | 10 +-- .../mastg-mitmproxy-scripts.instructions.md | 4 +- .../mastg-r2-scripts.instructions.md | 2 +- .../instructions/mastg-rules.instructions.md | 6 +- .../mastg-techniques.instructions.md | 6 +- .../instructions/mastg-test.instructions.md | 18 +++--- .../instructions/mastg-tools.instructions.md | 6 +- ...rting-mastg-v1-tests-to-v2.instructions.md | 64 +++++++++---------- 13 files changed, 96 insertions(+), 96 deletions(-) diff --git a/.github/instructions/markdown.instructions.md b/.github/instructions/markdown.instructions.md index b8f7bb789c7..67dac833ba5 100644 --- a/.github/instructions/markdown.instructions.md +++ b/.github/instructions/markdown.instructions.md @@ -13,18 +13,18 @@ The following markdown content rules are enforced in the validators: 4. **Links**: Use standard Markdown link syntax. 5. **Images**: Use HTML `` tags for images. See the "Images" section for examples and guidelines. 6. **Tables**: Use markdown tables for tabular data. Ensure proper formatting and alignment. -8. **Whitespace**: Use appropriate whitespace to separate sections and improve readability. -9. **Front Matter**: Include YAML front matter at the beginning of the file with required metadata fields. +7. **Whitespace**: Use appropriate whitespace to separate sections and improve readability. +8. **Front Matter**: Include YAML front matter at the beginning of the file with required metadata fields. ## Formatting and Structure Follow these guidelines for formatting and structuring your markdown content: -- **Headings**: Use `##` for H2 and `###` for H3. Ensure that headings are used in a hierarchical manner. Recommend restructuring if content includes H4, and more strongly recommend for H5. +- **Headings**: Use `##` for H2 and `###` for H3. Ensure that headings are used hierarchically. Recommend restructuring if the content includes H4, and more strongly recommend for H5. - **Lists**: Use `-` for bullet points and `1.` for numbered lists. Indent nested lists with four spaces to match the linter configuration. Prefer dashes `-` over asterisks `*` for unordered lists. Generally: - Limit a single list to at most nine items when reasonable. - Avoid more than two levels of nesting. - - Punctuate and capitalize list items consistently. Do not add end punctuation to list items that are not complete sentences unless they complete the introductory sentence. If list items complete an introductory sentence, end each (except the last) with a comma, omit the "and" before the last, and end the last with appropriate punctuation. + - Punctuate and capitalize list items consistently. Do not add end punctuation to list items that are not complete sentences unless they complete the introductory sentence. If list items complete an introductory sentence, end each (except the last) with a comma, omit the "and" before the last, and end the last item with appropriate punctuation. - **Code Blocks**: Use triple backticks to create fenced code blocks. Specify the language after the opening backticks for syntax highlighting (e.g., kt, java, xml). - **Links**: Ensure the link text is descriptive and the URL is valid. - **Tables**: Use `|` to create tables. Ensure that columns are properly aligned and headers are included. @@ -42,7 +42,7 @@ Follow these guidelines for formatting and structuring your markdown content: ### Content Length and Organization -- Use short, scannable pages where possible (roughly one to two screens of text). For very large sections, consider moving details to a supporting document and link to it. +- Use short, scannable pages where possible (roughly one to two screens of text). For extensive sections, consider moving details to a supporting document and linking to it for clarity and conciseness. - For digital content, favor shorter, cross-linked pages. If the content is intended for print, longer, comprehensive pages are acceptable. ### Gender Neutrality @@ -66,7 +66,7 @@ Follow these guidelines for formatting and structuring your markdown content: ### Abbreviations -- On first use, spell out the term followed by the abbreviation in parentheses; use the abbreviation alone on subsequent uses within the chapter. +- On first use, spell out the term followed by the abbreviation in parentheses; use the acronym alone on subsequent uses within the chapter. - If the term appears only once, prefer the full term instead of the abbreviation. - In titles/headings, abbreviations are acceptable, but introduce them properly in the following text. - Use "a" or "an" based on pronunciation (e.g., a URL, an APK). @@ -106,7 +106,7 @@ best-practices: [MASTG-BEST-0010, MASTG-BEST-0011, MASTG-BEST-0012] - Never use Horizontal rules like `---`. - Emphasis/strong style: underscores for emphasis (`_text_`), asterisks for strong (`**text**`). - Trailing punctuation allowed in headings (MD026) is limited to: `.,;:` -- Always prefer commas or parentheses over em-dashes, en-dashes or hyphens. +- Always prefer commas or parentheses over em-dashes, en-dashes, or hyphens. ## Images @@ -123,12 +123,12 @@ Example: ``` -Note: The linter does not require alt text for images (MD045 disabled); however, include descriptive context in the surrounding text when helpful for accessibility. +Note: The linter does not require alt text for images (MD045 is disabled); however, including descriptive context in the surrounding text is helpful for accessibility. ## Validation Requirements Ensure compliance with the following validation requirements: - **Content Rules**: Ensure that the content follows the markdown content rules specified above. -- **Formatting**: Ensure that the content is properly formatted and structured according to the guidelines. +- **Formatting**: Ensure that the content is appropriately formatted and structured according to the guidelines. - **Validation**: Run the validation tools to check for compliance with the rules and guidelines. diff --git a/.github/instructions/mastg-apps.instructions.md b/.github/instructions/mastg-apps.instructions.md index 2cfc17aeb33..cb730ba96af 100644 --- a/.github/instructions/mastg-apps.instructions.md +++ b/.github/instructions/mastg-apps.instructions.md @@ -1,6 +1,6 @@ # Reference Apps Authoring Instructions -Standards for authoring reference application pages under `apps/`. These pages describe vulnerable or exemplar applications used across tests, techniques, and demos. +Standards for authoring reference application pages under `apps/`. These pages describe vulnerable or exemplary applications used across tests, techniques, and demos. ## Locations @@ -10,9 +10,9 @@ Standards for authoring reference application pages under `apps/`. These pages d ## File naming and IDs -- The app ID is defined by the filename: `MASTG-APP-\d{4}.md` +- The filename defines the app ID: `MASTG-APP-\d{4}.md` - Do not add an `id:` field to the YAML front matter -- Use the next available number within the platform folder. Coordinate in PRs to avoid collisions +- Use the following available number within the platform folder. Coordinate in PRs to avoid collisions ## Markdown structure @@ -52,11 +52,11 @@ package: sg.vantagepoint.uncrackable1 Entries should be short and referential. Do not duplicate installation or usage docs that belong in the app’s own repository. - One or two sentences describing the app and its purpose -- Add any platform-specific hints such as jailbreak expectations or proxy setup +- Add any platform-specific hints, such as jailbreak expectations or proxy setup ### Cross-linking -In YAML front matter add `weaknesses` listing all the weaknesses from the MASWE that can be tested and are present in the app. +In the YAML front matter, add `weaknesses` listing all the weaknesses from the MASWE that can be tested and are present in the app. Example: @@ -64,7 +64,7 @@ Example: weaknesses: [MASWE-0034, MASWE-0056] ``` -Do not add specific app versions here. If a MASTG-DEMO requires a specific version of an app, document it in the demo, not in the app entry. +Do not add specific app versions here. If a MASTG-DEMO requires a particular version of an app, document it in the demo, not in the app entry. ## Writing conventions diff --git a/.github/instructions/mastg-best-practice.instructions.md b/.github/instructions/mastg-best-practice.instructions.md index d7ac274491c..fdc4ca3c018 100644 --- a/.github/instructions/mastg-best-practice.instructions.md +++ b/.github/instructions/mastg-best-practice.instructions.md @@ -49,7 +49,7 @@ Best Practices should contain: - what's the recommendation - why is that good -- any caveats or considerations (for example, "it's good to have it but remember it can be bypassed this way") +- any caveats or considerations (for example, "it's good to have it, but remember it can be bypassed this way") - official references ### Recommended Structure @@ -73,7 +73,7 @@ Example References section: ### Cross-linking -- From tests: use `best-practices: [MASTG-BEST-0001, MASTG-BEST-0011]` in the test’s YAML front matter. The site generator will create Mitigations links automatically. +- From tests: use `best-practices: [MASTG-BEST-0001, MASTG-BEST-0011]` in the test’s YAML front matter. The site generator will automatically create Mitigations links. - In body text: reference tests, tools, or techniques with @ (for example, @MASTG-TEST-0252, @MASTG-TOOL-0031). ### Style diff --git a/.github/instructions/mastg-demo.instructions.md b/.github/instructions/mastg-demo.instructions.md index 8ff0215b337..e320fb4496f 100644 --- a/.github/instructions/mastg-demo.instructions.md +++ b/.github/instructions/mastg-demo.instructions.md @@ -13,16 +13,16 @@ Demos live in `demos/android/` or `demos/ios/` under the corresponding MASVS cat **Decompiled Code:** Decompiled code must be provided if the demo involves static analysis. -- **Android:** Follow the instructions in ["MASTestApp for Android - Run the Extraction Script"](https://github.com/cpholguera/mas-app-android) to obtain the relevant files such as the reversed `AndroidManifest.xml` and the `MastgTest_reversed.java` which is the MASTestApp's main file. Including the full version of these files is also useful for understanding the code in the context of the application, regardless of whether the demo focuses on a specific snippet. -- **iOS:** Follow the instructions in ["MASTestApp for iOS - Reverse Engineering"](https://github.com/cpholguera/MASTestApp-iOS) to obtain the relevant files such as the the IPA file and the reversed `Info.plist` already converted to XML format. Currently you need to manually extract the main binary, MASTestApp, and include it in the demo folder (we allow this for now since the files are sufficiently small). The demos will typically use reverse engineering tools like `r2` on this binary. +- **Android:** Follow the instructions in ["MASTestApp for Android - Run the Extraction Script"](https://github.com/cpholguera/mas-app-android) to obtain the relevant files, such as the reversed `AndroidManifest.xml` and the `MastgTest_reversed.java`, which is the MASTestApp's main file. Including the full version of these files is also useful for understanding the code in the context of the application, regardless of whether the demo focuses on a specific snippet. +- **iOS:** Follow the instructions in ["MASTestApp for iOS - Reverse Engineering"](https://github.com/cpholguera/MASTestApp-iOS) to obtain the relevant files, such as the IPA file and the reversed `Info.plist` already converted to XML format. Currently, you need to extract the main binary, MASTestApp, manually, and include it in the demo folder (we allow this for now since the files are sufficiently small). The demos will typically use reverse engineering tools, such as `r2`, on this binary. The **demos MUST WORK**. See [Code Samples](#code-samples). Demos are required to be **fully self-contained** and should **not rely on external resources or dependencies**. This ensures that the demos can be run independently and that the results are reproducible. They must be proven to work on the provided sample applications and must be tested thoroughly before being included in the MASTG. -**Don't create demos for outdated OS versions** that aren't supported by the MASTG. The MASTestApp is meant to always be up to date and aligned with the versions supported by the MASTG, so as to avoid additional maintenance of the MASTestApp. However, you can include demos showcasing the "good case" in the metadata using `kind: pass` in certain cases where it can be helpful or educational. This is permitted as long as the demos work with the current version of the MASTestApp. +**Don't create demos for outdated OS versions** that aren't supported by the MASTG. The MASTestApp is always intended to be up to date and aligned with the versions supported by the MASTG, thereby avoiding additional maintenance of the MASTestApp. However, you can include demos showcasing the "good case" in the metadata using `kind: pass` in certain cases where it can be helpful or educational. This is permitted as long as the demos work with the current version of the MASTestApp. -Please specify the mobile platform version, IDE and version, device. +Please specify the mobile platform version, IDE version, and device. Android Example: @@ -72,13 +72,13 @@ title: Common Uses of Insecure Random APIs #### platform -The mobile platform. One of: ios, android. +The mobile platform. One of: `ios`, `android`. #### tools Tools used in the demo. -Prefer referencing official tool IDs from https://mas.owasp.org/MASTG/tools/ when available (for example, `MASTG-TOOL-0031`). If an official ID is not available, you may use a well-known tool name (for example, `semgrep`). +When available, prefer referencing official tool IDs from https://mas.owasp.org/MASTG/tools/ (for example, `MASTG-TOOL-0031`). If an official ID is not available, you may use a well-known tool name (for example, `semgrep`). Example: @@ -131,7 +131,7 @@ Include these if relevant: #### Sample -Shortly describe the sample and specify the exact sample files used using this notation: +Shortly describe the sample and specify the exact sample files using this notation: **Single file:** @@ -150,14 +150,14 @@ Example: ```md ### Sample -The snippet below shows sample code that sends sensitive data over the network using the `HttpURLConnection` class. The data is sent to `https://httpbin.org/post` which is a dummy endpoint that returns the data it receives. +The snippet below shows sample code that sends sensitive data over the network using the `HttpURLConnection` class. The data is sent to `https://httpbin.org/post`, which is a dummy endpoint that returns the data it receives. {{ MastgTest.kt # MastgTest_reversed.java }} ``` #### Steps -A concise writeup following all steps from the linked test, including placeholders for testing code and scripts (for example, SAST rules, `run.sh`). +A concise write-up following all steps from the linked test, including placeholders for testing code and scripts (for example, SAST rules, `run.sh`). Example: @@ -173,7 +173,7 @@ Let's run our semgrep rule against the sample code. #### Observation -A concise description of the observation for this specific demo including placeholders for output files (for example, `output.txt`, `output.json`). +A concise description of the observation for this specific demo, including placeholders for output files (for example, `output.txt`, `output.json`). Example: @@ -198,9 +198,9 @@ Review each of the reported instances. - Line 12 seems to be used to generate random numbers for security purposes, in this case for generating authentication tokens. - Line 17 is part of the function `get_random`. Review any calls to this function to ensure that the random number is not used in a security-relevant context. -- Line 27 is part of the password generation function which is a security-critical operation. +- Line 27 is part of the password generation function, which is a security-critical operation. -Note that line 37 did not trigger the rule because the random number is generated using `SecureRandom` which is a secure random number generator. +Note that line 37 did not trigger the rule because the random number is generated using `SecureRandom`, which is a secure random number generator. ``` @@ -220,7 +220,7 @@ Must be a modified version of the original files in the apps’ repos: * Android: `app/src/main/java/org/owasp/mastestapp/MastgTest.kt` * iOS: `MASTestApp/MastgTest.swift` -When working on a new demo you **must include the whole file** with the original name in the demo folder. +When working on a new demo, you **must include the whole file** with the original name in the demo folder. #### Summary @@ -229,26 +229,26 @@ Must contain a summary as a comment. Example: ```kt -// SUMMARY: This sample demonstrates different common ways of insecurely generating random numbers in Java. +// SUMMARY: This sample demonstrates various common ways of generating random numbers insecurely in Java. ``` #### Logic The file must include code that demonstrates the addressed weakness. -The provided default `MastgTest.kt` and `MastgTest.swift` contain some basic logic that will return a string to the UI. If possible try to return some meaningful string. +The provided default `MastgTest.kt` and `MastgTest.swift` files contain some basic logic that returns a string to the UI. If possible, try to return some meaningful string. -For example, if you create a random number you can return it; or if you write files to the external storage you can return a list of file paths so that the user of the app can read them. You can also use that string to display some meaningful errors. +For example, if you generate a random number, you can return it; or if you write files to external storage, you can return a list of file paths so that the app's user can read them. You can also use that string to display some meaningful errors. #### Fail/Pass -Must contain comments indicating fail/pass and the test alias. This way we're able to validate that the output is correct (e.g. the code contains 3 failures of `MASTG-TEST-0204`). We can easily parse and count the comments and we can do the same in the output. +Must contain comments indicating fail/pass and the test alias. This way, we can validate that the output is correct (e.g., the code contains three failures of `MASTG-TEST-0204`). We can easily parse and count the comments, and we can do the same in the output. -Each FAIL/PASS comment must include the test Id and an explanation of why it fails/passes. +Each FAIL/PASS comment must include the test ID and an explanation of why it fails/passes. Example: ```kt -// FAIL: [MASTG-TEST-0204] The app insecurely uses random numbers for generating authentication tokens. +// FAIL: [MASTG-TEST-0204] The app insecurely generates authentication tokens using random numbers. return r.nextDouble(); diff --git a/.github/instructions/mastg-frida-scripts.instructions.md b/.github/instructions/mastg-frida-scripts.instructions.md index 4a55748698c..227577c6c0f 100644 --- a/.github/instructions/mastg-frida-scripts.instructions.md +++ b/.github/instructions/mastg-frida-scripts.instructions.md @@ -33,8 +33,8 @@ Examples: ### Inspiration -- Don't reinvent the wheel when something already exists. Use existing open-source sources when available, for example https://codeshare.frida.re/browse. -- If you use a source be sure to document it and give creadit to the author. Include a link to the original source in a comment at the beginning of the frida script. +- Don't reinvent the wheel when something already exists. Use existing open-source sources when available, for example, https://codeshare.frida.re/browse. +- If you use a source, be sure to document it and give credit to the author. Include a link to the source in a comment at the beginning of the frida script. Example: diff --git a/.github/instructions/mastg-knowledge.instructions.md b/.github/instructions/mastg-knowledge.instructions.md index c6f3e462924..64e19b1a6f6 100644 --- a/.github/instructions/mastg-knowledge.instructions.md +++ b/.github/instructions/mastg-knowledge.instructions.md @@ -12,7 +12,7 @@ Locations and taxonomy: File naming and IDs: -- The knowledge ID is defined by the filename: `MASTG-KNOW-\d{4}.md`. +- The filename defines the knowledge ID: `MASTG-KNOW-\d{4}.md`. - Do not add an `id:` field to the YAML front matter. - Place the file in the platform (`android` or `ios`) and MASVS category folder that best matches the subject. @@ -48,13 +48,13 @@ available_since: 18 ### Markdown: Body -Keep content authoritative, concise, and platform-focused. Avoid duplicating OS documentation; cite it and summarize what the feature is and how it works. +Keep content authoritative, concise, and platform-focused. Avoid duplicating OS documentation. Instead, cite it and summarize the feature, including its purpose and functionality. 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"). -- Include specific API names, version nuances, storage locations, configuration knobs. Try to avoid code samples; instead try to refer to existing MASTG-DEMO code files. If you include them keep them short and explanatory. +- 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,11 +70,11 @@ 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, 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 or create one if it's missing. ## Deprecation -If the original source is gone, not relevant anymore, or too old, set the following in the YAML front matter: +If the source is gone, not relevant anymore, or too old, set the following in the YAML front matter: - `status:` Must be set to `deprecated` - `deprecation_note:` Short clarifying note for deprecation. Keep phrasing concise and imperative diff --git a/.github/instructions/mastg-mitmproxy-scripts.instructions.md b/.github/instructions/mastg-mitmproxy-scripts.instructions.md index 79133ce0deb..784b94b88a4 100644 --- a/.github/instructions/mastg-mitmproxy-scripts.instructions.md +++ b/.github/instructions/mastg-mitmproxy-scripts.instructions.md @@ -20,7 +20,7 @@ This guide defines how to write and use mitmproxy scripts in MASTG demos. Script - Keep `run.sh` responsible for: - Starting/stopping mitmdump (foreground or background as appropriate to the demo flow). - Managing output files produced by the script (for example, `sensitive_data.log`). - - Ensuring the device/emulator routes traffic through the proxy (defer details to Tools page). + - Ensuring the device/emulator routes traffic through the proxy (defer details to the Tools page). ### Coding conventions @@ -84,7 +84,7 @@ def response(flow: http.HTTPFlow): ### Logging and outputs - Default to writing a deterministic, append-only file (for example, `sensitive_data.log`) in the demo folder. Reference it in the Observation and Evaluation sections. -- Keep the format simple and consistent—avoid timestamps unless needed for the demo, to keep diffs small. +- Keep the format consistent and straightforward. Avoid timestamps unless needed for the demo to keep diffs small. - If multiple outputs are produced, document them in the demo’s Steps. ### Alignment with Tools diff --git a/.github/instructions/mastg-r2-scripts.instructions.md b/.github/instructions/mastg-r2-scripts.instructions.md index bfaae66b683..1a28ef7224f 100644 --- a/.github/instructions/mastg-r2-scripts.instructions.md +++ b/.github/instructions/mastg-r2-scripts.instructions.md @@ -1,6 +1,6 @@ ## r2 scripts (radare2) -This guide defines how to write and use radare2 scripts in MASTG demos. Scripts live with the demo and are executed by `run.sh` to produce Observation output. +This guide defines how to write and use radare2 scripts in MASTG demos. Scripts are included with the demo and executed by `run.sh` to produce the Observation output. ### Scope and terminology diff --git a/.github/instructions/mastg-rules.instructions.md b/.github/instructions/mastg-rules.instructions.md index 9c1a96c7eda..74f0c029932 100644 --- a/.github/instructions/mastg-rules.instructions.md +++ b/.github/instructions/mastg-rules.instructions.md @@ -28,7 +28,7 @@ Required fields per rule: - **languages**: usually `xml` or `java` (we don’t create rules for Kotlin as we work with decompiled Java; use `xml` for AndroidManifest and resource rules). - **metadata**: must include summary - summary: Short description of the rule. - - original_source: you may use rules from sources on the internet be sure to check that the license allows this and always link to the original source here. Modify the rule if needed and the license allows for it. + - original_source: You may use rules from sources on the internet. Be sure to check that the license allows this, and always link to the source here. Modify the rule as needed, provided the license permits it. - **message**: must start with a MASVS identifier and concisely explain what the rule is reporting. Prefer a specific control when applicable (for example, `[MASVS-PLATFORM-2]`); otherwise, use the MASVS category tag (for example, `[MASVS-STORAGE]`). - **patterns**: see [https://semgrep.dev/docs/writing-rules/pattern-syntax/](https://semgrep.dev/docs/writing-rules/pattern-syntax/) @@ -39,7 +39,7 @@ Multiple rules per file General guidance -- Do not include authors in the semgrep rules. If it was copied from some other place, **include the link to the original source**. Since many people will contribute, authorship is tracked via git history. +- Do not include authors in the semgrep rules. If it was copied from another source, **include the link to the source**. Since many people will contribute, authorship is tracked via git history. - Keep messages concise and actionable; they should be understandable without reading the pattern body. - Test rules in the Semgrep Playground and against reversed code from the demos. @@ -52,7 +52,7 @@ rules: languages: - java metadata: - summary: This rule looks for common patterns including classes and methods. + summary: This rule looks for common patterns, including classes and methods. message: "[MASVS-CRYPTO-1] The application makes use of an insecure random number generator." pattern-either: diff --git a/.github/instructions/mastg-techniques.instructions.md b/.github/instructions/mastg-techniques.instructions.md index 23e73aa4cbb..d4767c28d33 100644 --- a/.github/instructions/mastg-techniques.instructions.md +++ b/.github/instructions/mastg-techniques.instructions.md @@ -11,9 +11,9 @@ Locations: File naming and IDs: -- The technique ID is defined by the filename: `MASTG-TECH-\d{4}.md`. +- The filename defines the technique ID: `MASTG-TECH-\d{4}.md`. - Do not add an `id:` field to the YAML front matter for techniques. -- Use the next available number within the platform folder. Coordinate in PRs to avoid collisions. +- Use the next available increment number within the platform folder. Coordinate in PRs to avoid collisions. Follow the global Markdown rules (see `.github/instructions/markdown.instructions.md`). Use `##` for top-level sections inside the page. @@ -110,4 +110,4 @@ You should see method entries in the console matching the targeted patterns. If - Multi-platform techniques: If steps are identical across platforms, place the page under `generic/`. If they differ meaningfully, create separate platform pages. - Tool selection: Link to multiple tools when appropriate and list trade-offs briefly in the text; keep detailed tool usage on the tool pages. -- Deprecation: If a technique becomes obsolete (for example, platform removed capability), set `status: deprecated` and add a short note at the top explaining why, with links to alternatives. +- Deprecation: If a technique becomes obsolete (for example, a platform's removed capability), set `status: deprecated` and add a short note at the top explaining why, with links to alternatives. diff --git a/.github/instructions/mastg-test.instructions.md b/.github/instructions/mastg-test.instructions.md index f5620e46573..fb8229018d0 100644 --- a/.github/instructions/mastg-test.instructions.md +++ b/.github/instructions/mastg-test.instructions.md @@ -32,7 +32,7 @@ Each test has two parts: the [Markdown metadata](#markdown-metadata) (YAML `fron Test titles should be concise and clearly state the purpose of the test. -In some cases, the test name and the weakness may have the same title, but typically tests cover different aspects of a weakness. Titles should reflect that. +In some cases, the test name and the weakness may have the same title, but typically, tests cover different aspects of a weakness. Titles should reflect that. Avoid including Android or iOS unless necessary, as in "Insecure use of the Android Protected Confirmation API". @@ -43,11 +43,11 @@ Follow a consistent style across all test titles. - 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. +Exceptions may apply where "Runtime ..." feels forced, for example, tests using adb, local backups, or filesystem snapshots. #### platform -The mobile platform. One of: ios, android, network. +The mobile platform. One of the following: iOS, Android, or network. - Use network for platform-agnostic traffic analysis tests where the checks are performed purely on captured/observed traffic (often paired with type: [network]). @@ -57,7 +57,7 @@ The test ID. #### weakness -The MASWE weakness ID the test references. +The MASWE weakness ID that the test references. - In YAML front matter, specify the bare identifier (for example, `weakness: MASWE-0069`). In body text, include the leading `@` (for example, @MASWE-0069). @@ -70,7 +70,7 @@ Supported: - `static`: analysis of the app binary, reverse-engineered source code, or developer artifacts that are available in the APK/IPA app package (e.g., Android manifest, Info.plist, entitlements, etc.). No execution of the app is required. - `dynamic`: analysis of the app while it is running and involves runtime analysis such as hooking or method tracing. - `manual`: manual steps that require human judgment, such as inspecting app behavior, UI, or configuration. This may include reverse engineering or runtime analysis that cannot be fully automated. -- `network`: analysis of network traffic, while the app is running. Done externally, for example using a proxy or network capture tool. +- `network`: analysis of network traffic, while the app is running. Done externally, for example, using a proxy or network capture tool. - `filesystem`: analysis of the app's file system, including local storage or backups, which doesn't involve runtime analysis such as hooking or method tracing. - `developer`: tests only the developer can perform because they require access to the source code, build process, or other internal resources. @@ -106,7 +106,7 @@ Notes: #### prerequisites -List prerequisites needed to execute or evaluate the test. Existing files are in `prerequisites/`. Create new ones if needed. +List the prerequisites needed to execute or evaluate the test. Existing files are in `prerequisites/`. Create new ones if required. - If there are no prerequisites, you can omit this field or use an empty list. @@ -120,7 +120,7 @@ prerequisites: #### profiles -Specify MASVS profiles where the test applies. Valid values: L1, L2, P, R. +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) - L1 denotes Essential Security. @@ -164,7 +164,7 @@ Android apps sometimes use insecure pseudorandom number generators (PRNGs) such #### Steps -A test must include one or more steps. Steps can be static, dynamic, manual, or mixed. +A test must include at least one step. Steps can be static, dynamic, manual, or a combination of these. Example, to check app notifications: @@ -185,7 +185,7 @@ Example: Notes: - Always link to existing MASTG-TECH by ID (for example, @MASTG-TECH-0014) -- Don't reference MASTG tools directly (this may still be happening in some tests and we must fix it.) +- Don't reference MASTG tools directly (this may still be happening in some tests, and we must fix it.) - Be consistent by reusing the steps from existing tests. Do not create new phrasing or wording when it's not necessary. #### Observation diff --git a/.github/instructions/mastg-tools.instructions.md b/.github/instructions/mastg-tools.instructions.md index 7f03f968f10..fa1b423fbed 100644 --- a/.github/instructions/mastg-tools.instructions.md +++ b/.github/instructions/mastg-tools.instructions.md @@ -68,13 +68,13 @@ Keep pages practical, scannable, and focused on security testing use. ### Cross-linking - Do not cross-link here to tests, demos, and techniques, etc. -- Those components will cross-link to tools, typically techniques and demos -- To do that they must add @MASTG-TOOL-0031 in their markdown body or as `tools: [MASTG-TOOL-0031]` in their YAML front matter +- Those components will cross-link to tools, typically techniques, and demos +- To do that, they must add @MASTG-TOOL-0031 in their markdown body or as `tools: [MASTG-TOOL-0031]` in their YAML front matter ## Conventions and quality - Prefer official sources for installation steps. Avoid advertising or endorsing third-party distributions -- Favor commands that work across supported hosts when possible. Otherwise clearly label host-specific commands +- Favor commands that work across supported hosts when possible. Otherwise, clearly label host-specific commands - For images, use HTML `` tags per the markdown instructions (store assets in an appropriate images folder if needed) - Keep examples minimal and verifiable. Longer walkthroughs belong in demos with runnable scripts diff --git a/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md b/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md index 64afbe63c21..397da68062d 100644 --- a/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md +++ b/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md @@ -4,14 +4,14 @@ This document focuses on the porting workflow. For how to write v2 tests (front matter fields, required sections, styles), see `mastg-test.instructions.md`. Do not duplicate that guidance here—follow it when drafting the ported test. -Check some of the current tests and take them as reference +Check some of the current tests and take them as a reference. * tests-beta * demos -Always take the most recent tests (the ones with the highest IDs) as reference/template. Use `tests-beta` files as the canonical template for structure and front matter. +Always use the most recent tests (those with the highest IDs) as a reference/template. Use `tests-beta` files as the canonical template for structure and front matter. -Also review these. We’ll be using them and creating new ones as well: +Also, review these. We’ll be using them and creating new ones as well: * [https://mas.owasp.org/MASTG/techniques/](https://mas.owasp.org/MASTG/techniques/) * [https://mas.owasp.org/MASTG/tools/](https://mas.owasp.org/MASTG/tools/) @@ -24,7 +24,7 @@ Also review these. We’ll be using them and creating new ones as well: **Important** tips and guidelines: 1. Create a rough draft. - 1. In most cases you’ll have something in the v1 test + 1. In most cases, you’ll have something in the v1 test 2. Sometimes you can take the whole test or just a sentence or bullet point. 3. You may use [chatGPT](https://chat.openai.com/) to create an initial draft and massage the content. 2. Edit it yourself using **your knowledge** @@ -49,7 +49,7 @@ Also review these. We’ll be using them and creating new ones as well: #### List of sources -Use the MASTG first, e.g. the guides for 0x04 (general), 0x05 (Android) and 0x06 (iOS) and **extend** with android/apple docs. +Use the MASTG first: e.g., the guides for 0x04 (general), 0x05 (Android), and 0x06 (iOS), and **extend** with Android/Apple docs. **Android** @@ -65,50 +65,50 @@ Use the MASTG first, e.g. the guides for 0x04 (general), 0x05 (Android) and 0x06 ## Porting workflow -Map to MASWE. You can check the new MASWE by searching for the old test ID in the **weaknesses/** directory. For example MASTG-TEST-0017. +Map to MASWE. You can check the new MASWE by searching for the old test ID in the **weaknesses/** directory, for example, MASTG-TEST-0017. -1) Create a branch for the ticket: `port-MASTG-TEST-0017` (adjust ID). +1. Create a branch for the ticket: `port-MASTG-TEST-0017` (adjust ID). -2) Place files correctly: If the relevant `MASVS-*` folder does not exist yet under `tests-beta//`, create it. +2. Place files correctly: If the relevant `MASVS-*` folder does not exist yet under `tests-beta//`, create it. -3) Name the new file using the decimal ID (for example, `MASTG-TEST-0233.md`). +3. Name the new file using the decimal ID (for example, `MASTG-TEST-0233.md`). -4) Decide scope changes: One v1 test may become one or multiple v2 tests (or be merged). Capture only what is testable and actionable; move general theory elsewhere (see below). +4. Decide scope changes: One v1 test may become one or multiple v2 tests (or be merged). Capture only what is testable and actionable; move general theory elsewhere (see below). -5) Gather references: Search for references in `Document/`, `techniques/`, `tools/`, and `knowledge/`. +5. Gather references: Search for references in `Document/`, `techniques/`, `tools/`, and `knowledge/`. -6) Normalize background vs test logic: Add platform background as @MASTG-KNOW-xxxx references. If none exists, create a new knowledge page. Keep the test focused on detection and evaluation. +6. Normalize background vs test logic: Add platform background as @MASTG-KNOW-xxxx references. If none exists, create a new knowledge page. Keep the test focused on detection and evaluation. -7) Link general concepts to Document: Some content belongs in the Document chapter. For example, general cryptography concepts such as symmetric/asymmetric encryption, hashing, signing, etc. If the knowledge is still in `Document/`, link to it. +7. Link general concepts to Document: Some content belongs in the Document chapter. For example, general cryptography concepts such as symmetric/asymmetric encryption, hashing, signing, etc. If the knowledge is still in `Document/`, link to it. -Example: ["Post Quantum"](https://mas.owasp.org/MASTG/Document/0x04g-Testing-Cryptography/#post-quantum) + **Example:** ["Post Quantum"](https://mas.owasp.org/MASTG/Document/0x04g-Testing-Cryptography/#post-quantum) -8) Avoid duplication: You may summarize, but focus the test on how to detect the issue in Android/iOS and why it matters for this test. +8. Avoid duplication: You may summarize, but focus the test on how to detect the issue in Android/iOS and why it matters for this test. -9) Link mitigations: Ensure there is a clear mitigation in best-practices; add the reference in front matter (field defined in `mastg-test.instructions.md`). +9. Link mitigations: Ensure there is a clear mitigation in best practices; add the reference in front matter (field defined in `mastg-test.instructions.md`). -10) Trim non-essential parts: If parts of the v1 test aren’t relevant, remove them and note it in the ticket. +10. Trim non-essential parts: If parts of the v1 test aren’t relevant, remove them and note it in the ticket. -**Example:** In MASTG-TEST-0017, what’s written in dynamic analysis does not make sense: why should we validate that `setUserAuthenticationValidityDurationSeconds` are for real (we are not testing if Android features work; we assume they do). Maybe we could also use dynamic analysis but following a different approach. + **Example:** In MASTG-TEST-0017, what’s written in dynamic analysis does not make sense: why should we validate that `setUserAuthenticationValidityDurationSeconds` is for real (we are not testing if Android features work; we assume they do). Perhaps we could also employ dynamic analysis, but using a different approach. -11) Fill missing links to docs and developer references as needed. +11. Fill missing links to docs and developer references as needed. -**Example:** this test and the referenced section both were missing links to [https://developer.android.com/](https://developer.android.com/) + **Example:** this test and the referenced section both were missing links to [https://developer.android.com/](https://developer.android.com/) ## Porting considerations V1 tests often include techniques, tools, and theory/knowledge. Move that to the right place (or create it) and reference it (for example, @MASTG-TECH-0002, @MASTG-KNOW-0011, @MASTG-TOOL-0097). In the test body, use `@` prefixes; in YAML front matter, use bare IDs without `@`. For exact field names and section structure, see `mastg-test.instructions.md`. -Theory must be always linked to the @MASTG-KNOW-xxxx components. If the theory is not covered yet, create a new knowledge page. If it's a general concept, it may still belong in the Document chapter under 0x04. +Theory must always be linked to the @MASTG-KNOW-xxxx components. If the theory is not covered yet, create a new knowledge page. If it's a general concept, it may still belong in the Document chapter under 0x04. Review existing content and **UPDATE** it. Especially references to Android/iOS versions and things you know have changed since the text was written. #### 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 can 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 +2. If it doesn’t exist yet, create it new in `best-practices/` using the following available ID 3. Add a reference to the best practices with @MASTG-BEST-xxxx #### Deprecating V1 tests @@ -131,44 +131,44 @@ Some findings apply only with stronger attacker capabilities (for example, root/ Indicate in the test whether exploitation requires root/jailbreak. -> *On devices supporting file-based encryption (FBE) ↗, snapshots are stored in the /data/system\_ce/\/\ folder. \ depends on the vendor but most common names are snapshots and recent\_images. If the device doesn't support FBE, the /data/system/\ folder is used.* +> *On devices supporting file-based encryption (FBE) ↗, snapshots are stored in the /data/system\_ce/\/\ folder. \ depends on the vendor, but the most common names are snapshots and recent\_images. If the device doesn't support FBE, the /data/system/\ folder is used.* Accessing these folders and the snapshots requires root. EXAMPLE: cleartext configured globally in NSC. No need for root, network/mitm: yes -What other things to consider here? +What other things should we consider here? - **binary**: possible just because the attacker has the binary (decrypted on iOS) - **app**: another app on the device with the right permissions (e.g. full access to external storage) -- **mitm**: a network based attacker capable of performing MITM +- **mitm**: a network-based attacker capable of performing MITM - **user computer**: the user using adb -- **user UI**: using the app's or another app’s UI, e.g. third party file manager; +- **user UI**: using the app's or another app’s UI, e.g. third-party file manager; - **user confirmation**: e.g. pasteboard confirmation ### Code Snippets If the v1 test has snippets that inspire a demo, prefer Kotlin and Swift for new examples (avoid Java/Objective-C). You can create a demo with `status: draft` and finish later. See `mastg-demo.instructions.md` for demo authoring. -You can create a demo **status: draft** and come back later to it. Just to ensure we extracted everything from V1. Create a ticket **"Finish Demo Draft MASTG-DEMO-xxxx"** +You can create a demo **status: draft** and come back to it later. To ensure we extracted everything from V1. Create a ticket **"Finish Demo Draft MASTG-DEMO-xxxx"** - [https://github.com/WithSecureLabs/sieve/](https://github.com/WithSecureLabs/sieve/) - Ovaa - MASTG playground - [https://mas.owasp.org/MASTG/apps/](https://mas.owasp.org/MASTG/apps/) -List of apps to get ideas from, as inspiration. You may include "inspired by" to ref to the original source whenever our new content is similar enough. +List of apps to get ideas from, as inspiration. You may include "inspired by" to reference the source whenever our new content is similar enough. ### Notes (keep in mind while porting) -- A test must not describe the general problem again (that’s the Weakness’ job). Keep the test focused on detection and evaluation. +- A test must not describe the general problem again (that’s the Weakness’s job). Keep the test focused on detection and evaluation. - If you find an edge case, consider whether it deserves a separate test with distinct steps/evaluation. ### OS version -**For Android:** We have agreed on supporting the **current version \- 5**. This gives a roughly 90% adoption rate on average. See [https://apilevels.com/](https://apilevels.com/) +**For Android:** We have agreed on supporting the **current version \- 5**. This yields an average adoption rate of roughly 90%. See [https://apilevels.com/](https://apilevels.com/) -If a test is no longer applicable for some OS versions, add an applicability note so testers can discard it when not relevant. +If a test is no longer applicable for specific OS versions, add an applicability note so testers can discard it when it is not relevant. Avoid creating demos for unsupported versions. From 8a7db3303840b40a9775a86e7f28efcc4ada5145 Mon Sep 17 00:00:00 2001 From: Dionysis Lorentzos Date: Sat, 4 Oct 2025 17:28:10 +0200 Subject: [PATCH 16/20] Update .github/instructions/mastg-apps.instructions.md Co-authored-by: Sven --- .github/instructions/mastg-apps.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/instructions/mastg-apps.instructions.md b/.github/instructions/mastg-apps.instructions.md index cb730ba96af..986caa90ce0 100644 --- a/.github/instructions/mastg-apps.instructions.md +++ b/.github/instructions/mastg-apps.instructions.md @@ -12,7 +12,7 @@ Standards for authoring reference application pages under `apps/`. These pages d - The filename defines the app ID: `MASTG-APP-\d{4}.md` - Do not add an `id:` field to the YAML front matter -- Use the following available number within the platform folder. Coordinate in PRs to avoid collisions +- Use the next available number in the platform folder. Coordinate in PRs to avoid collisions ## Markdown structure From cb00c7b208b3316874d7fea843205f921fcefb70 Mon Sep 17 00:00:00 2001 From: Dionysis Lorentzos Date: Sat, 4 Oct 2025 17:28:39 +0200 Subject: [PATCH 17/20] Update .github/instructions/mastg-techniques.instructions.md Co-authored-by: Sven --- .github/instructions/mastg-techniques.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/instructions/mastg-techniques.instructions.md b/.github/instructions/mastg-techniques.instructions.md index d4767c28d33..2031ba93086 100644 --- a/.github/instructions/mastg-techniques.instructions.md +++ b/.github/instructions/mastg-techniques.instructions.md @@ -13,7 +13,7 @@ File naming and IDs: - The filename defines the technique ID: `MASTG-TECH-\d{4}.md`. - Do not add an `id:` field to the YAML front matter for techniques. -- Use the next available increment number within the platform folder. Coordinate in PRs to avoid collisions. +- Use the next available number within the platform folder. Coordinate in PRs to avoid collisions. Follow the global Markdown rules (see `.github/instructions/markdown.instructions.md`). Use `##` for top-level sections inside the page. From a6a34c520fe5c32da57057b1d4f03655fc4ad1f1 Mon Sep 17 00:00:00 2001 From: Dionysis Lorentzos Date: Sat, 4 Oct 2025 17:29:31 +0200 Subject: [PATCH 18/20] Update .github/instructions/markdown.instructions.md Co-authored-by: Sven --- .github/instructions/markdown.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/instructions/markdown.instructions.md b/.github/instructions/markdown.instructions.md index 67dac833ba5..eeb1beb50cd 100644 --- a/.github/instructions/markdown.instructions.md +++ b/.github/instructions/markdown.instructions.md @@ -66,7 +66,7 @@ Follow these guidelines for formatting and structuring your markdown content: ### Abbreviations -- On first use, spell out the term followed by the abbreviation in parentheses; use the acronym alone on subsequent uses within the chapter. +- On first use, spell out the term followed by the abbreviation in parentheses; use the abbreviation alone on subsequent uses within the chapter. - If the term appears only once, prefer the full term instead of the abbreviation. - In titles/headings, abbreviations are acceptable, but introduce them properly in the following text. - Use "a" or "an" based on pronunciation (e.g., a URL, an APK). From b2542e05620c718c40a49e5c64e83629252a0d7f Mon Sep 17 00:00:00 2001 From: Dionysis Lorentzos Date: Sat, 4 Oct 2025 17:31:10 +0200 Subject: [PATCH 19/20] Update .github/instructions/porting-mastg-v1-tests-to-v2.instructions.md Co-authored-by: Sven --- .../instructions/porting-mastg-v1-tests-to-v2.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md b/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md index 397da68062d..6e25e8eae80 100644 --- a/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md +++ b/.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md @@ -108,7 +108,7 @@ Review existing content and **UPDATE** it. Especially references to Android/iOS Best practices are platform-specific and can 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 following available ID +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 #### Deprecating V1 tests From 5be8302471426ff82ed398d4b84194754e4104f4 Mon Sep 17 00:00:00 2001 From: Sven Date: Mon, 6 Oct 2025 09:57:45 +0200 Subject: [PATCH 20/20] Update .github/instructions/mastg-test.instructions.md Co-authored-by: Dionysis Lorentzos --- .github/instructions/mastg-test.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/instructions/mastg-test.instructions.md b/.github/instructions/mastg-test.instructions.md index fb8229018d0..2198a296674 100644 --- a/.github/instructions/mastg-test.instructions.md +++ b/.github/instructions/mastg-test.instructions.md @@ -57,7 +57,7 @@ The test ID. #### weakness -The MASWE weakness ID that the test references. +The MASWE weakness ID associated with this test. - In YAML front matter, specify the bare identifier (for example, `weakness: MASWE-0069`). In body text, include the leading `@` (for example, @MASWE-0069).