Update Instructions

.github/instructions/mastg-apps.instructions.md

@@ -15,7 +15,10 @@ 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 next available number in the platform folder. Coordinate in PRs to avoid collisions
+
+When creating a new app (whether during porting or writing from scratch), use a **fake ID** with the notation `MASTG-APP-0x##` (for example, `MASTG-APP-0x33`). This prevents conflicts between parallel pull requests. Create new fake IDs incrementally (e.g., `MASTG-APP-0x33`, `MASTG-APP-0x34`, `MASTG-APP-0x35`) as you add new content.
+
+Once your pull request is reviewed and ready to merge, the team will assign real IDs (for example, `MASTG-APP-0008`) before the content is published.
 
 ## Markdown structure
 

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

@@ -8,7 +8,11 @@ applyTo: 'best-practices/*.md'
 
 Best practices live under `best-practices/` and each file name must be the best-practice ID, for example `MASTG-BEST-0001.md`.
 
-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 @).
+## Creating Best Practice IDs
+
+When creating a new best practice (whether during porting or writing from scratch), use a **fake ID** with the notation `MASTG-BEST-0x##` (for example, `MASTG-BEST-0x33`). This prevents conflicts between parallel pull requests. Create new fake IDs incrementally (e.g., `MASTG-BEST-0x33`, `MASTG-BEST-0x34`, `MASTG-BEST-0x35`) as you add new content.
+
+Once your pull request is reviewed and ready to merge, the team will assign real IDs (for example, `MASTG-BEST-0025`) before the content is published.
 
 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).
 
@@ -27,24 +31,24 @@ Relationship to Tests and Knowledge (nuance):
 
 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.
+- `title`: Concise, action-oriented recommendation.
+- `id`: Best-practice ID in the form `MASTG-BEST-\d{4}`.
+- `platform`: One of: android, ios, generic.
 
 Optional metadata:
 
-- alias: URL-friendly slug (lowercase, hyphen-separated) used for navigation.
-- status: draft, placeholder, deprecated.
-- note: Short free-form note.
-- knowledge: One or more related Knowledge pages (`MASTG-KNOW-####`) for neutral background and API reference.
-- available_since: Minimum platform version/API level where this recommendation applies (Android: integer API level; iOS: release version, for example `13`).
-- deprecated_since: Last applicable platform/API level.
+- `alias`: URL-friendly slug (lowercase, hyphen-separated) used for navigation.
+- `status`: draft, placeholder, deprecated.
+- `note`: Short free-form note.
+- `knowledge`: One or more related Knowledge pages (`MASTG-KNOW-####`) for neutral background and API reference.
+- `available_since`: Minimum platform version/API level where this recommendation applies (Android: integer API level; iOS: release version, for example `13`).
+- `deprecated_since`: Last applicable platform/API level.
 
 Example:
 
 ```yaml
 ---
-name: Preventing Screenshots and Screen Recording
+title: Preventing Screenshots and Screen Recording
 alias: preventing-screenshots-and-screen-recording
 id: MASTG-BEST-0014
 platform: android
@@ -58,37 +62,32 @@ Notes:
 
 Best Practices should contain:
 
-- what's the recommendation
-- why is that good
+- what's the recommendation (stated clearly and concisely at the start)
+- why is that good (security value and context, woven into the explanation)
 - any caveats or considerations (for example, "it's good to have it, but remember it can be bypassed this way")
-- official references
+- official references (embedded inline as markdown links, not in a separate section)
 
-## Recommended Structure
+## Structure
 
-Use clear sections to improve readability and enable consistent rendering.
+Best practices are flexible in structure and adapt to the content. They typically:
 
-- 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.
+- Start with 1-2 paragraphs explaining the recommendation and its security value
+- Use ## subheadings to organize content by platform, language, approach, or topic (e.g., "Java/Kotlin", "Swift / Objective-C", "Using ProGuard", "Common Misconceptions")
+- Embed official documentation links inline using markdown syntax
+- Reference related MASTG content with @ notation (e.g., @MASTG-TOOL-0022, @MASTG-KNOW-0018)
+- Keep explanations concise and focused on the practice itself
+- Include minimal code examples when helpful to illustrate the recommendation. Prefer to link to MASTG-DEMOs that have metadata `kind: pass`.
+- Use **Note** or **Warning** Admonitions for important caveats or clarifications
 
-Example References section:
+Examples of good structure:
 
-```markdown
-## References
+- Brief opening paragraph stating the practice → subsections for different languages/approaches → inline references
+- Opening explanation with security context → detailed guidance with code examples → caveats woven in
+- Direct recommendation → platform-specific implementation details → misconceptions or warnings
 
-- 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
-```
+If additional resources need to be highlighted, list them informally at the end with natural phrasing (e.g., "See these resources for more details:") rather than a formal "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 automatically create Mitigations links.
-- 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.
+- From MASTG-TEST: use `best-practices: [MASTG-BEST-0001, MASTG-BEST-0011]` in the test's YAML front matter.
+- Anywhere in markdown bodies: use @MASTG-BEST-0001 to link to a best practice.

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

@@ -51,6 +51,12 @@ output.txt
 run.sh*
 ```
 
+## Creating Demo IDs
+
+When creating a new demo (whether porting from v1 or writing from scratch), use a **fake ID** with the notation `MASTG-DEMO-0x##` (for example, `MASTG-DEMO-0x33`). This prevents conflicts between parallel pull requests. Create new fake IDs incrementally (e.g., `MASTG-DEMO-0x33`, `MASTG-DEMO-0x34`, `MASTG-DEMO-0x35`) as you add new content.
+
+Once your pull request is reviewed and ready to merge, the team will assign real IDs (for example, `MASTG-DEMO-0054`) before the content is published.
+
 ## Markdown: Metadata
 
 ### id
@@ -97,12 +103,12 @@ tools: [semgrep]
 
 ### code
 
-The language(s) in which the samples are written. Multiple values are supported.
+The language(s) in which the samples are written. This must not include the reverse-engineered files (e.g. `.java`, `.asm`, etc.)
 
 Example:
 
 ```md
-code: [java]
+code: [kotlin]
 ```
 
 Multi-language example:

.github/instructions/mastg-frooky-hooks.instructions.md

@@ -47,12 +47,33 @@ Hook configurations are JSON files that declare which classes and methods to ins
 }
 ```
 
+```json
+{
+  "category": "RESILIENCE",
+  "hooks": [
+    {
+      "class": "java.io.File",
+      "method": "$init",
+      "overloads": [
+        {
+          "args": ["java.lang.String"]
+        }
+      ],
+      "filterEventsByStacktrace": ["org.owasp.mastestapp"]
+    }
+  ]
+}
+```
+
 Key fields:
 
-- `category`: A label for grouping hooks (for example, `STORAGE`, `CRYPTO`, `NETWORK`)
-- `hooks`: Array of hook definitions
-    - `class`: Fully qualified class name to hook
-    - `methods`: Array of method names to intercept
+- `category`: A label for grouping hooks (for example, `STORAGE`, `CRYPTO`, `NETWORK`).
+- `hooks`: Array of hook definitions.
+    - `class`: Fully qualified class name to hook.
+    - `methods`: Array of method names to intercept.
+    - `method`: One method name (alternative to `methods` array).
+        - `overloads`: Optional array of overload signatures to specify which method variants to hook.
+    - `filterEventsByStacktrace`: Optional array of strings; only events with stack traces containing these strings will be included in the output.
 
 See more in the [frooky Usage page](https://github.com/cpholguera/frooky/blob/main/docs/usage.md).
 

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

@@ -34,6 +34,10 @@ File naming and IDs:
 - 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.
 
+When creating a new knowledge page (whether during porting or writing from scratch), use a **fake ID** with the notation `MASTG-KNOW-0x##` (for example, `MASTG-KNOW-0x33`). This prevents conflicts between parallel pull requests. Create new fake IDs incrementally (e.g., `MASTG-KNOW-0x33`, `MASTG-KNOW-0x34`, `MASTG-KNOW-0x35`) as you add new content.
+
+Once your pull request is reviewed and ready to merge, the team will assign real IDs (for example, `MASTG-KNOW-0112`) before the content is published.
+
 Follow the global Markdown rules (see `.github/instructions/markdown.instructions.md`). Use `##` and `###` headings in the body.
 
 ## Markdown: Metadata

.github/instructions/mastg-techniques.instructions.md

@@ -16,7 +16,10 @@ 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 number within the platform folder. Coordinate in PRs to avoid collisions.
+
+When creating a new technique (whether during porting or writing from scratch), use a **fake ID** with the notation `MASTG-TECH-0x##` (for example, `MASTG-TECH-0x33`). This prevents conflicts between parallel pull requests. Create new fake IDs incrementally (e.g., `MASTG-TECH-0x33`, `MASTG-TECH-0x34`, `MASTG-TECH-0x35`) as you add new content.
+
+Once your pull request is reviewed and ready to merge, the team will assign real IDs (for example, `MASTG-TECH-0018`) before the content is published.
 
 Follow the global Markdown rules (see `.github/instructions/markdown.instructions.md`). Use `##` for top-level sections inside the page.
 

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

@@ -30,6 +30,12 @@ Notes:
 
 Each test has two parts: the [Markdown metadata](#markdown-metadata) (YAML `front matter`) and the [Markdown body](#markdown-body).
 
+## Creating Test IDs
+
+When creating a new test (whether porting from v1 or writing from scratch), use a **fake ID** with the notation `MASTG-TEST-0x##` (for example, `MASTG-TEST-0x33`). This prevents conflicts between parallel pull requests. Create new fake IDs incrementally (e.g., `MASTG-TEST-0x33`, `MASTG-TEST-0x34`, `MASTG-TEST-0x35`) as you add new content.
+
+Once your pull request is reviewed and ready to merge, the team will assign real IDs (for example, `MASTG-TEST-0233`) before the content is published.
+
 ## Markdown: Metadata
 
 ### title

.github/instructions/mastg-tools.instructions.md

@@ -17,7 +17,10 @@ Standards for authoring tool reference pages under `tools/`. These pages documen
 
 - 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
+
+When creating a new tool (whether during porting or writing from scratch), use a **fake ID** with the notation `MASTG-TOOL-0x##` (for example, `MASTG-TOOL-0x33`). This prevents conflicts between parallel pull requests. Create new fake IDs incrementally (e.g., `MASTG-TOOL-0x33`, `MASTG-TOOL-0x34`, `MASTG-TOOL-0x35`) as you add new content.
+
+Once your pull request is reviewed and ready to merge, the team will assign real IDs (for example, `MASTG-TOOL-0051`) before the content is published.
 
 ## Markdown structure
 

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

@@ -39,8 +39,11 @@ Also, review these. We'll be using them and creating new ones as well:
 
 **About the IDs:**
 
-- 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.
+- Use "fake IDs" with the `MASTG-TEST-0x` notation (for example, `MASTG-TEST-0x33`).
+- If a test must be split, suffix with a short decimal part during drafting (for example, `MASTG-TEST-0x33-1`, `MASTG-TEST-0x33-2`).
+- Once the test is ready, the team will assign a real ID (for example, `MASTG-TEST-0233`).
+
+Use the same approach for demos (for example, `MASTG-DEMO-0x33-1`), best practices (for example, `MASTG-BEST-0x33`), knowledge (for example, `MASTG-KNOW-0x33`) and techniques (for example, `MASTG-TECH-0x33`) or any other content type. This way, we can keep track of the relationships between the content pieces during drafting and porting and avoid conflicts. Once the content is ready, we will assign real IDs.
 
 **Language**: use simple language, be concise and clear
 
@@ -52,7 +55,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-KNOW articles first and **extend** with Android/Apple docs.
 
 #### Android