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

Author: Diolor

.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 `<img>` tags for images. See the "Images" section for examples and guidelines.
+6. **Tables**: Use markdown tables for tabular data. Ensure proper formatting and alignment.
+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 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 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.
+  - 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 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
+
+- 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-<KIND>-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 `<img>` 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
+<img src="Images/Chapters/0x05b/r2_pd_10.png" width="80%" />
+```
+
+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 appropriately formatted and structured according to the guidelines.
+- **Validation**: Run the validation tools to check for compliance with the rules and guidelines.

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

@@ -0,0 +1,80 @@
+# Reference Apps Authoring Instructions
+
+Standards for authoring reference application pages under `apps/`. These pages describe vulnerable or exemplary 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 (don't edit it)
+
+## File naming and IDs
+
+- 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
+
+## Markdown structure
+
+- Follow the global Markdown rules in `.github/instructions/markdown.instructions.md`
+- Headings in the body start at `##`. Use `##` and `###` only
+
+## Metadata
+
+Each file begins with a YAML front matter block.
+
+**Required**
+
+- `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
+
+**Optional**
+
+- `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
+---
+title: Android UnCrackable L1
+platform: android
+source: https://mas.owasp.org/crackmes/Android#android-uncrackable-l1
+package: sg.vantagepoint.uncrackable1
+---
+```
+
+## Body content
+
+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
+
+### Cross-linking
+
+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:
+
+```md
+weaknesses: [MASWE-0034, MASWE-0056]
+```
+
+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
+
+- Use the official app name and capitalization
+- Prefer official sources or the MASTG Crackmes catalog for downloads
+
+## Deprecation
+
+If the original 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
+- `covered_by:` List of MASTG-APP-xxxx apps covering for this one, if any.

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

@@ -0,0 +1,83 @@
+## 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 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 @).
+
+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 (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 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.