Add deprecation notes and status for MASTG tests (#3089)

* Add deprecation notes for MASTG-TESTs

* Add deprecated status to theme and extra sections in mkdocs.yml

* Add support for 'deprecated' status in tags for markdown pages

* Add status for tests in dynamic tables

* Add draft banner for MASTG v2 tests and deprecated banner for MASTG v1 tests

docs/hooks/add-tags.py

@@ -45,6 +45,10 @@ def on_page_markdown(markdown, page, **kwargs):
     if page.meta.get('status'):
         if page.meta.get('status') == 'draft':
             tags.append('draft')
+
+    if page.meta.get('status'):
+        if page.meta.get('status') == 'deprecated':
+            tags.append('deprecated')
 
     page.meta['tags'] = tags
 

docs/hooks/create_dynamic_tables.py

@@ -185,6 +185,9 @@ def get_mastg_components_dict(name):
                         frontmatter['platform'] = "".join([get_platform_icon(platform) for platform in frontmatter['platform']])
                     else:
                         frontmatter['platform'] = get_platform_icon(frontmatter['platform'])
+                    if "tests" in component_path:
+                        frontmatter['status'] = frontmatter.get('status', 'current')
+
                     components.append(frontmatter)
         return components
 
@@ -236,6 +239,14 @@ def get_all_tests_beta():
             frontmatter['id'] = test_id
             frontmatter['title'] = f"@{frontmatter['id']}"            
             frontmatter['platform'] = get_platform_icon(frontmatter['platform'])
+            frontmatter['status'] = frontmatter.get('status', 'new')
+            status = frontmatter['status']
+            if status == 'new':
+                frontmatter['status'] = '<span class="md-tag md-tag-icon md-tag--new">new</span><span style="display: none;">status:new</span>'
+            elif status == 'draft':
+                frontmatter['status'] = f'<a href="https://github.com/OWASP/owasp-mastg/issues?q=is%3Aissue+is%3Aopen+{test_id}" target="_blank"><span class="md-tag md-tag-icon md-tag--draft" style="min-width: 4em">draft</span></a><span style="display: none;">status:draft</span>'
+            elif status == 'deprecated':
+                frontmatter['status'] = '<span class="md-tag md-tag-icon md-tag--deprecated">deprecated</span><span style="display: none;">status:deprecated</span>'
 
             tests.append(frontmatter)
     return tests
@@ -291,7 +302,7 @@ def on_page_markdown(markdown, page, **kwargs):
 
         # tests/index.md
 
-        column_titles = {'id': 'ID', 'title': 'Title', 'platform': "Platform", 'masvs_v2_id': "MASVS v2 ID", 'masvs_v1_id': "MASVS v1 IDs", 'last_updated': 'Last Updated'} #'id': 'ID',  ... , 'refs': 'Refs', 'techniques': 'Techniques'
+        column_titles = {'id': 'ID', 'title': 'Title', 'platform': "Platform", 'masvs_v2_id': "MASVS v2 ID", 'masvs_v1_id': "MASVS v1 IDs", 'status': 'Status'}
         tests = get_mastg_components_dict("docs/MASTG/tests")
         tests_of_type = [reorder_dict_keys(test, column_titles.keys()) for test in tests]
         for test in tests_of_type:
@@ -305,7 +316,7 @@ def on_page_markdown(markdown, page, **kwargs):
 
         # tests-beta/index.md
 
-        column_titles = {'id': 'ID', 'title': 'Title', 'platform': "Platform", 'weakness': "Weakness", 'type': "Type"}
+        column_titles = {'id': 'ID', 'title': 'Title', 'platform': "Platform", 'weakness': "Weakness", 'type': "Type", 'status': "Status"}
 
         tests_beta = get_all_tests_beta()
         tests_beta_columns_reordered = [reorder_dict_keys(test, column_titles.keys()) for test in tests_beta]

docs/hooks/maswe-beta-banner.py

@@ -63,7 +63,7 @@ def get_mastg_v1_coverage(meta):
             mastg_v1_tests = "    No MASTG v1 tests are related to this weakness."
     return mastg_v1_tests
 
-def get_info_banner(meta):
+def get_maswe_draft_banner(meta):
 
     id = meta.get('id')
 
@@ -88,7 +88,7 @@ def get_info_banner(meta):
 
     mastg_v1_tests = get_mastg_v1_coverage(meta)
 
-    info_banner = f"""
+    banner = f"""
 !!! warning "Draft Weakness"
 
     This weakness hasn't been created yet and it's in **draft**. But you can check its status or start working on it yourself.
@@ -108,7 +108,54 @@ def get_info_banner(meta):
 
 {mastg_v1_tests}
 """
-    return info_banner
+    return banner
+
+def get_tests_draft_banner(meta):
+    id = meta.get('id')
+    note = meta.get('note', None)
+    weakness = meta.get('weakness', None)
+
+    if note:
+        note = f"    > Note: {note}\n"
+
+    if weakness:
+        weakness = f"\nFor more details, check the associated weakness: @{weakness}\n"
+
+    banner = f"""
+!!! warning "Draft Test"
+
+    This test hasn't been created yet and it's in **draft**. But you can check its status or start working on it yourself.
+    If the issue has not yet been assigned, you can request to be assigned to it and submit a PR with the new content for that test by following our [guidelines](https://docs.google.com/document/d/1EMsVdfrDBAu0gmjWAUEs60q-fWaOmDB5oecY9d9pOlg/edit?pli=1&tab=t.0#heading=h.j1tiymiuocrm).
+
+    <a href="https://github.com/OWASP/owasp-mastg/issues?q=is%3Aissue+is%3Aopen+{id}" target="_blank">:material-github: Check our GitHub Issues for {id}</a>
+
+    If an issue doesn't exist yet, please create one and assign it to yourself or request to be assigned to it.
+
+{note}
+{weakness}
+"""
+    return banner
+
+def get_v1_deprecated_tests_banner(meta):
+    id = meta.get('id')
+    covered_by = meta.get('covered_by', [])
+    deprecation_note = meta.get('deprecation_note', "")
+
+    if covered_by:
+        covered_by = "\n".join([f"    - @{test}" for test in covered_by])
+    else:
+        covered_by = "    No tests are covering this weakness."
+
+    banner = f"""
+!!! danger "Deprecated Test"
+
+    This test is **deprecated** and should not be used anymore. **Reason**: {deprecation_note}
+
+    Please check the following MASTG v2 tests that cover this v1 test:
+
+{covered_by}
+"""
+    return banner
 
 # https://www.mkdocs.org/dev-guide/plugins/#on_page_markdown
 @mkdocs.plugins.event_priority(-50)
@@ -121,7 +168,13 @@ def on_page_markdown(markdown, page, **kwargs):
         banners.append(beta_banner)
 
     if "MASWE/" in path and page.meta.get('status') == 'draft':
-        banners.append(get_info_banner(page.meta))
+        banners.append(get_maswe_draft_banner(page.meta))
+
+    if "MASTG/tests-beta/" in path and page.meta.get('status') == 'draft':
+        banners.append(get_tests_draft_banner(page.meta))
+
+    if "MASTG/tests/" in path and page.meta.get('status') == 'deprecated':
+        banners.append(get_v1_deprecated_tests_banner(page.meta))
 
     if banners:
         markdown = "\n\n".join(banners) + "\n\n" + markdown

mkdocs.yml

@@ -246,6 +246,7 @@ theme:
       l2: material/circle-multiple-outline
       r: material/circle-double
       draft: material/information-outline
+      deprecated: material/trash-can
       new: material/alert-decagram
       tool: octicons/tools-24
       test: octicons/codescan-checkmark-24
@@ -370,6 +371,7 @@ extra:
     L2: l2
     R: r
     draft: draft
+    deprecated: deprecated
     new: new
     tool: tool
     test: test
@@ -381,4 +383,5 @@ extra:
     best: best
   status:
     draft: This page is in draft.
+    deprecated: This page is deprecated.
     new: New in this beta!

tests/android/MASVS-STORAGE/MASTG-TEST-0001.md

@@ -11,6 +11,7 @@ masvs_v1_levels:
 - L2
 status: deprecated
 covered_by: [MASTG-TEST-0207, MASTG-TEST-0200]
+deprecation_note: New version available in MASTG V2
 ---
 
 ## Overview

tests/android/MASVS-STORAGE/MASTG-TEST-0003.md

@@ -10,6 +10,7 @@ masvs_v1_levels:
 - L2
 status: deprecated
 covered_by: [MASTG-TEST-0203, MASTG-TEST-0231]
+deprecation_note: New version available in MASTG V2
 ---
 
 ## Overview

tests/ios/MASVS-RESILIENCE/MASTG-TEST-0081.md

@@ -9,6 +9,7 @@ masvs_v1_levels:
 - R
 covered_by: [MASTG-TEST-0220]
 status: deprecated
+deprecation_note: New version available in MASTG V2
 ---
 
 ## Overview

tests/ios/MASVS-RESILIENCE/MASTG-TEST-0083.md

@@ -9,6 +9,7 @@ masvs_v1_levels:
 - R
 covered_by: [MASTG-TEST-0219]
 status: deprecated
+deprecation_note: New version available in MASTG V2
 ---
 
 ## Overview