Skip to content

Writing MASTG Tool Files

Standards for authoring 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)
  • tools/index.md is the catalog landing page (don't edit it)

File naming and IDs

  • The tool ID is defined by the filetitle: MASTG-TOOL-\d{4}.md
  • Do not add an id: field to the YAML front matter

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

  • 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: Concise tool name. Add a qualifier when needed to disambiguate (for example, "Frida for Android", "nm - iOS")
  • platform: One of: android, ios, generic, network

Preferred (add for new pages when possible):

  • source: Canonical homepage, repository URL, or official documentation URL
  • hosts: List of operating systems the tool runs on
    • Prefer a YAML list under hosts: (for example, hosts: [windows, linux, macOS] or a multi-line list)
    • Common values used in this repo include windows, linux, macOS, ios, android

Optional:

  • 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

Example:

---
title: Frida for Android
platform: android
source: https://github.com/frida/frida
hosts: [windows, linux, macOS]
---

Body content

Keep pages practical, scannable, and focused on security testing use.

Tool pages are often intentionally short. Prefer a small amount of high-signal content over a large, rigid template.

Common patterns that match existing pages in tools/:

  • Start with a short description paragraph (often with a link to the upstream project or docs).
  • Add sections only when they add value for that tool. Typical headings are ## Installation, ## Usage, and tool-specific headings (for example, ## Installing Frida on iOS).
  • Include copyable commands when relevant. If usage is extensive, keep only the most common commands and link to a technique or upstream docs.
  • Do not add step-by-step usage examples or multi-step walkthroughs to tool pages. These belong in a technique page (for example, @MASTG-TECH-0031). The website will automatically list any techniques that reference the tool as examples of use on the rendered tool page, so adding them to the right technique page is the correct way to surface them.
  • Add caveats as !!! note / !!! warning admonitions when needed (version pinning, jailbreak/root requirements, security warnings).
  • Link to related techniques/tests/demos where it helps the reader complete a workflow.

If you are editing an existing tool page, keep its current structure unless there is a clear benefit to reorganizing it.

MkDocs callouts:

  • You can use MkDocs Material admonitions such as !!! note, !!! warning, and collapsible blocks (??? info) for version caveats and long side-notes.

Cross-linking

  • Tool pages may cross-link to techniques, tests, demos, and chapters when it helps the reader complete a workflow.
  • Prefer using MASTG identifiers in body text where available (for example, @MASTG-TECH-0011).
  • Tests, demos, and techniques should reference tools by ID whenever available (for example, @MASTG-TOOL-0031 in body text, or tools: [MASTG-TOOL-0031] in YAML where applicable).

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 <img> 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

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-TOOL-xxxx tools covering for this one, if any.

Example:

---
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]
---