feat: add table of contents to generated changelog

Author: jondricek

mitreattack/diffStix/changelog_helper.py

@@ -1236,6 +1236,11 @@ def get_markdown_string(self) -> str:
         logger.info("Generating markdown output")
         content = ""
 
+        # Add contributors if requested by argument
+        if self.include_contributors:
+            content += self.get_contributor_section()
+            content += "\n"
+
         # Add statistics section for the new version
         logger.info("Generating statistics section")
         stats_section = self.get_statistics_section(datastore_version="new")
@@ -1245,6 +1250,9 @@ def get_markdown_string(self) -> str:
             key_content = self.get_md_key()
             content += f"{key_content}\n"
 
+        content += "## Table of Contents\n\n"
+        content += "[TOC]\n\n"
+
         for object_type in self.types:
             domains = ""
 
@@ -1279,10 +1287,6 @@ def get_markdown_string(self) -> str:
             if domains != "":
                 content += f"## {self.attack_type_to_title[object_type]}\n\n{domains}"
 
-        # Add contributors if requested by argument
-        if self.include_contributors:
-            content += self.get_contributor_section()
-
         return content
 
     def get_layers_dict(self):
@@ -1782,7 +1786,7 @@ def markdown_to_html(outfile: str, content: str, diffStix: DiffStix):
     html_string = """<div style='max-width: 55em;margin: auto;margin-top:20px;font-family: "Roboto", sans-serif;'>"""
     html_string += "<meta charset='utf-8'>"
     html_string += header
-    html_string += markdown.markdown(content)
+    html_string += markdown.markdown(content, extensions=['toc'])
     html_string += "</div>"
 
     with open(outfile, "w", encoding="utf-8") as outputfile:

tests/changelog/core/test_missing_functions.py

@@ -107,7 +107,11 @@ def test_markdown_to_html_real_conversion(self, lightweight_diffstix, tmp_path):
 
         # Verify markdown was converted to HTML
         if "# " in markdown_content:
-            assert "<h1>" in html_content or "<h2>" in html_content  # Headers should be converted
+            # when the python markdown Table of Contents plugin is enabled, it changes the <h1> and <h2> tags
+            # to include id attributes and maybe a style attribute (at least to <h1>) so this assert statement
+            # looks a little funny, but is good enough
+            # https://python-markdown.github.io/extensions/toc/
+            assert "<h1" in html_content or "<h2" in html_content  # Headers should be converted
 
     def test_layers_dict_to_files_real_file_writing(self, mock_layers_dict, tmp_path):
         """Test real layer files generation."""

tests/changelog/formatting/test_html_output.py

@@ -23,9 +23,12 @@ def test_markdown_to_html_basic(self, tmp_path, lightweight_diffstix):
         assert outfile.exists()
         html_content = outfile.read_text(encoding="utf-8")
         assert f"ATT&CK Changes Between v{old_version} and v{new_version}" in html_content
-        assert "<h1>Test Header</h1>" in html_content
         assert "<strong>bold</strong>" in html_content
         assert "charset='utf-8'" in html_content
+        # it might be nice to add this back in, but when using the python markdown TOC extension,
+        # it modifies the <h1> and <h2> tags, giving them additional attributes, like id (and maybe style?)
+        # https://python-markdown.github.io/extensions/toc/
+        # assert "<h1>Test Header</h1>" in html_content
 
     def test_write_detailed_html_basic(
         self, tmp_path, lightweight_diffstix, sample_deepdiff_data, minimal_stix_bundles

tests/resources/changelog-v16.1_to_v17.0/changelog.md

@@ -1,3 +1,74 @@
+## Contributors to this release
+
+* Aaron Sullivan aka ZerkerEOD
+* Adam Lichters
+* Alden Schmidt
+* Ale Houspanossian
+* Alexey Kleymenov
+* Alon Klayman, Hunters Security
+* Amnon Kushnir, Sygnia
+* Ben Smith, @cyberg3cko
+* Caio Silva
+* Cian Heasley
+* Cristian Souza - Kaspersky GERT
+* Cristóbal Martínez Martín
+* David Hughes, BT Security
+* Dhiraj Mishra (@RandomDhiraj)
+* Dmitry Bestuzhev
+* Dvir Sasson, Reco
+* Eliraz Levi, Hunters Security
+* Fabian Kammel
+* Fernando Bacchin
+* Flavio Costa, Cisco
+* Frank Angiolelli
+* Gabriel Currie
+* Gerardo Santos
+* Harikrishnan Muthu, Cyble
+* Hiroki Nagahama, NEC Corporation
+* Inna Danilevich, U.S. Bank
+* Jaesang Oh, KC7 Foundation
+* Janantha Marasinghe
+* Jennifer Kim Roman
+* Jiraput Thamsongkrah
+* Joas Antonio dos Santos, @C0d3Cr4zy
+* Joe Gumke, U.S. Bank
+* Jun Hirata, NEC Corporation
+* Kaung Zaw Hein
+* Kevin Ward
+* Kori Yoshihiro, NEC Corporation
+* Kyaw Pyiyt Htet, @KyawPyiytHtet
+* Liran Ravich, CardinalOps
+* Lê Phương Nam, Group-IB
+* Manikantan Srinivasan, NEC Corporation India
+* Matt Anderson, @‌nosecurething, Huntress
+* Matt Brenton, Zurich Global Information Security
+* Matt Brenton, Zurich Insurance Group
+* Menachem Goldstein
+* Michael Davis @ ServiceNow Threat Intelligence
+* MyungUk Han, ASEC
+* Natthawut Saexu
+* Nikita Rostovcev, Group-IB
+* Oren Biderman, Sygnia
+* Peter Oakes
+* Pooja Natarajan, NEC Corporation India
+* Raghvendra Mishra
+* ReliaQuest
+* RoseSecurity
+* Rouven Bissinger (SySS GmbH)
+* Ruben Groenewoud (@RFGroenewoud)
+* Ryan Perez
+* Sareena Karapoola, NEC Corporation India
+* seungyoul.yoo@ahnlab.com
+* Sharmine Low, Group-IB
+* Shun Miyazaki, NEC Corporation
+* Shwetank Murarka
+* Sittikorn Sangrattanapitak
+* Suraj Khetani (@r00treaver)
+* Vicky Ray, RayvenX
+* Vijay Lalwani
+* Wietze Beukema @Wietze
+* Yoshihiro Kori, NEC Corporation
+
 ## Statistics
 
 This version of ATT&CK contains 877 Software, 170 Groups, and 50 Campaigns.
@@ -19,6 +90,10 @@ Broken out by domain:
 * Object deprecations: ATT&CK objects which are deprecated and no longer in use, and not replaced.
 * Object deletions: ATT&CK objects which are no longer found in the STIX data.
 
+## Table of Contents
+
+[TOC]
+
 ## Techniques
 
 ### Enterprise
@@ -2226,73 +2301,3 @@ Broken out by domain:
 * [Service Metadata](/datasources/DS0019/#Service%20Metadata) <small style="color:#929393">(v1.0)</small>
 * [Software](/datasources/DS0039/#Software) <small style="color:#929393">(v1.0)</small>
 
-## Contributors to this release
-
-* Aaron Sullivan aka ZerkerEOD
-* Adam Lichters
-* Alden Schmidt
-* Ale Houspanossian
-* Alexey Kleymenov
-* Alon Klayman, Hunters Security
-* Amnon Kushnir, Sygnia
-* Ben Smith, @cyberg3cko
-* Caio Silva
-* Cian Heasley
-* Cristian Souza - Kaspersky GERT
-* Cristóbal Martínez Martín
-* David Hughes, BT Security
-* Dhiraj Mishra (@RandomDhiraj)
-* Dmitry Bestuzhev
-* Dvir Sasson, Reco
-* Eliraz Levi, Hunters Security
-* Fabian Kammel
-* Fernando Bacchin
-* Flavio Costa, Cisco
-* Frank Angiolelli
-* Gabriel Currie
-* Gerardo Santos
-* Harikrishnan Muthu, Cyble
-* Hiroki Nagahama, NEC Corporation
-* Inna Danilevich, U.S. Bank
-* Jaesang Oh, KC7 Foundation
-* Janantha Marasinghe
-* Jennifer Kim Roman
-* Jiraput Thamsongkrah
-* Joas Antonio dos Santos, @C0d3Cr4zy
-* Joe Gumke, U.S. Bank
-* Jun Hirata, NEC Corporation
-* Kaung Zaw Hein
-* Kevin Ward
-* Kori Yoshihiro, NEC Corporation
-* Kyaw Pyiyt Htet, @KyawPyiytHtet
-* Liran Ravich, CardinalOps
-* Lê Phương Nam, Group-IB
-* Manikantan Srinivasan, NEC Corporation India
-* Matt Anderson, @‌nosecurething, Huntress
-* Matt Brenton, Zurich Global Information Security
-* Matt Brenton, Zurich Insurance Group
-* Menachem Goldstein
-* Michael Davis @ ServiceNow Threat Intelligence
-* MyungUk Han, ASEC
-* Natthawut Saexu
-* Nikita Rostovcev, Group-IB
-* Oren Biderman, Sygnia
-* Peter Oakes
-* Pooja Natarajan, NEC Corporation India
-* Raghvendra Mishra
-* ReliaQuest
-* RoseSecurity
-* Rouven Bissinger (SySS GmbH)
-* Ruben Groenewoud (@RFGroenewoud)
-* Ryan Perez
-* Sareena Karapoola, NEC Corporation India
-* seungyoul.yoo@ahnlab.com
-* Sharmine Low, Group-IB
-* Shun Miyazaki, NEC Corporation
-* Shwetank Murarka
-* Sittikorn Sangrattanapitak
-* Suraj Khetani (@r00treaver)
-* Vicky Ray, RayvenX
-* Vijay Lalwani
-* Wietze Beukema @Wietze
-* Yoshihiro Kori, NEC Corporation