Add basic glossary handling

docs/hooks/add-tags.py

@@ -87,6 +87,7 @@ def on_post_page(output, page, config):
     # Matches URLs like '/tags/#tag:MASWE-<number>' and replaces them with '/MASWE-<number>'
     output = re.sub(r'/tags/#tag:(MASWE-\d+)"', lambda x: f'/{x.group(1)}"' , output)
     output = re.sub(r'/tags/#tag:know"', '/MASTG/knowledge/"' , output)
+    output = re.sub(r'/tags/#tag:term"', '/MASTG/terms/"' , output)
     output = re.sub(r'/tags/#tag:test"', '/MASTG/tests/"' , output)
     output = re.sub(r'/tags/#tag:maswe"', '/MASWE/"' , output)
     output = re.sub(r'/tags/#tag:demo"', '/MASTG/demos/"' , output)

docs/hooks/add_redirects.py

@@ -6,7 +6,7 @@
 @mkdocs.plugins.event_priority(-10)
 def on_pre_build(config):
     folders = [
-        {"base": "docs/MASTG", "subfolders": ["knowledge", "tools", "apps", "techniques", "tests", "rules", "demos", "best-practices"]},
+        {"base": "docs/MASTG", "subfolders": ["knowledge", "terms", "tools", "apps", "techniques", "tests", "rules", "demos", "best-practices"]},
         {"base": "docs/MASWE", "subfolders": [""]},
         {"base": "docs/MASVS", "subfolders": ["controls"]}
     ]

docs/hooks/combine-repos.py

@@ -87,7 +87,7 @@ def structure_mastg(docs_dir):
 
     log.info(f"Using MASTG directory: {mastg_repo_dir}")
 
-    directories = ["knowledge", "tests", "techniques", "tools", "apps", "demos", "rules", "utils", "best-practices"]
+    directories = ["knowledge", "terms", "tests", "techniques", "tools", "apps", "demos", "rules", "utils", "best-practices"]
 
     for d in directories:
         src = mastg_repo_dir / d

docs/hooks/resolve_references.py

@@ -8,7 +8,7 @@
 
 log = logging.getLogger('mkdocs')
 
-mapping = {"KNOW":{}, "TECH":{}, "TOOL":{}, "TEST": {}, "APP": {}, "MASWE": {}, "MASVS": {}, "DEMO": {}, "BEST": {}}
+mapping = {"KNOW":{}, "TERM": {}, "TECH":{}, "TOOL":{}, "TEST": {}, "APP": {}, "MASWE": {}, "MASVS": {}, "DEMO": {}, "BEST": {}}
 
 @mkdocs.plugins.event_priority(-50)
 def on_page_markdown(markdown, page, config, **kwargs):
@@ -17,7 +17,7 @@ def on_page_markdown(markdown, page, config, **kwargs):
     icons = config.get('resolve_ref_icons')
     icons_for_text = config.get('resolve_ref_icons_for_text')
 
-    pageRefs = {"KNOW": [], "TECH": [], "TOOL": [], "TEST": [], "APP": [], "MASWE": [], "MASVS": [], "DEMO": [], "BEST": []}
+    pageRefs = {"KNOW": [], "TERM": [], "TECH": [], "TOOL": [], "TEST": [], "APP": [], "MASWE": [], "MASVS": [], "DEMO": [], "BEST": []}
 
     def replaceReference(match):
         refType = match.group(2)
@@ -57,10 +57,11 @@ def replaceReferenceMASVS(match):
         return f"_[{icon}{mapping[refType][match]['title']}](/{match.group(1)} \"{refType}\")_"
 
 
-    updated_markdown = re.sub(r'@(MASTG-(KNOW|TECH|TOOL|TEST|APP|DEMO|BEST)-\d{3,})', replaceReference, markdown)
+    updated_markdown = re.sub(r'@(MASTG-(KNOW|TERM|TECH|TOOL|TEST|APP|DEMO|BEST)-\d{3,})', replaceReference, markdown)
     updated_markdown = re.sub(r'@(MASWE-\d{3,})', replaceReferenceMASWE, updated_markdown)
     updated_markdown = re.sub(r'@(MASVS-\w+)', replaceReferenceMASVS, updated_markdown)
 
+    page.meta["terms"] = list(set(pageRefs["TERM"]))
     page.meta["tools"] = list(set(pageRefs["TOOL"]))
     page.meta["techniques"] = list(set(pageRefs["TECH"]))
 

docs/hooks/resolve_terms.py

@@ -0,0 +1,74 @@
+import glob
+import mkdocs
+import yaml
+import re
+import os
+import logging
+
+log = logging.getLogger('mkdocs')
+
+
+def get_terms():
+    terms = {}
+
+    for file in glob.glob("docs/MASTG/terms/MASTG-TERM-*.md", recursive=True):
+        with open(file, 'r') as f:
+            id = os.path.splitext(os.path.basename(file))[0]
+            content = f.read()
+            frontmatter = next(yaml.load_all(content, Loader=yaml.FullLoader))
+
+            # Build a normalized relative path (from docs/) and a mkdocs-friendly URL
+            rel_path = os.path.relpath(file, "docs")
+            rel_path_no_ext, _ = os.path.splitext(rel_path)
+            # mkdocs pages usually resolve to "/<path-without-ext>/"
+            url = "/" + rel_path_no_ext.replace(os.sep, "/") + "/"
+
+            terms[id] = {
+                "url": url,
+                "title": frontmatter.get("title"),
+                "nist_url": frontmatter.get("nist"),
+                "cwe_url": frontmatter.get("cwe"),
+            }
+
+    return terms
+
+
+@mkdocs.plugins.event_priority(-10)
+def on_pre_build(config):
+    config["terms"] = get_terms()
+
+
+@mkdocs.plugins.event_priority(-40)
+def on_page_markdown(markdown, page, config, **kwargs):
+    path = page.file.src_uri
+
+    if path.endswith("terms/index.md"):
+        # glossary terms index
+        terms = config.get("terms", {}).values()
+        # Sort by title (case-insensitive)
+        terms_sorted = sorted(terms, key=lambda term: (term.get("title") or "").lower())
+        # Format as markdown links
+        terms_formatted = [f"[{term['title']}]({term['url']})" for term in terms_sorted if
+                           term.get("title") and term.get("url")]
+
+        return markdown + "<br/>" + "<br/>".join(terms_formatted)
+    elif path and re.compile(r"^.*terms/MASTG-TERM-\d{4}.md").match(path):
+        # append NIST and CWE link to the term
+
+        terms = config.get("terms", {})
+        term_id = os.path.splitext(os.path.basename(path))[0]
+        term = terms.get(term_id)
+
+        if term:
+            nist_url = term.get("nist_url")
+            cwe_url = term.get("cwe_url")
+            if nist_url or cwe_url:
+                references = f"## Other Framework References"
+                if nist_url:
+                    references += f"\n\n[NIST]({nist_url})"
+                if cwe_url:
+                    references += f"\n\n[CWE]({cwe_url})"
+
+                return markdown + f"\n\n\n{references}"
+
+    return markdown

mkdocs.yml

@@ -203,6 +203,9 @@ nav:
           - ... | flat | MASTG/apps/android/*.md
         - iOS:
           - ... | flat | MASTG/apps/ios/*.md
+      - Glossary (Beta):
+        - MASTG/terms/index.md
+        - ... | flat | MASTG/terms/MASTG-TERM-*.md
   - "MAS Checklist":
      - checklists/index.md
      - MASVS-STORAGE: checklists/MASVS-STORAGE.md
@@ -262,6 +265,7 @@ theme:
       update-pending: material/information-outline
       deprecated: octicons/circle-slash-16
       new: material/alert-decagram
+      term: material/book
       tool: octicons/tools-24
       know: material/book-open-blank-variant-outline
       test: octicons/codescan-checkmark-24
@@ -389,6 +393,7 @@ hooks:
   - docs/hooks/replace_snippets.py
   - docs/hooks/maswe-beta-banner.py
   - docs/hooks/create_dynamic_tables.py
+  - docs/hooks/resolve_terms.py
 
   # Priority -49 for last-minute tag modification
   - docs/hooks/add-tags.py