Docs: Autogenerate threats into docs

[fkromer]

If we#d use mkdocs for generating docs we could use the approach represented in mkdocs/mkdocs#3487 (reply in thread) potentially to free our self from manually updating supported threats defined in https://github.com/OWASP/pytm/blob/master/pytm/threatlib/threats.json into https://github.com/OWASP/pytm/blob/master/docs/threats.md .

Would this be helpful @Dakes @nineinchnick ?

This idea would align with other ideas like #279 .

[izar]

Can you give a bit more context on how you see that working ?

[fkromer]

According to mkdocs/mkdocs#3487 (reply in thread) it should be possible to implement a mkdocs plugin which reads the json file content and creates a markdown file from it dynamically before the actual site output is generated.

[pranavvardia]

Is it okay if I take up this issue to work on ?

[izar]

go for it!

[pranavvardia]

Hey, I had a couple of ideas on how to implement this and wanted the community's insights into what would be the best approach.

Approach 1: Add a build script to devbox.json that read the threats.json and runs the mkdocs build command on it. The drawback i feel in this approach is that it is only available for when the project is built using devbox and not any other manner for eg: using docker.

Approach 2: Regenerate threats.md automatically every time mkdocs build or mkdocs serve runs. But this again comes with the same opt-in problem, that someone will need to manually run mkdocs build. This might also lead to conflicts, since when someone opens a PR they might forget to run the build command, leading to a stale threats.md file.

Approach 3: Use github actions that triggers on every PR and push to master. It checks if threats.md changed. If it did, it means the contributor edited threats.json without regenerating threats.md, and the CI fails. This will use a generator script that converts threats.json to threats.md and has no dependency on Mkdocs.

Looking forward for your inputs.

[izar]

I'm still unsure what the final outcome expected is, here. Can you guys provide an example of what the markdown would look like, and what the added value would be ?

[raphaelahrens]

I had the reverse idea, that the threats should be written in Markdown and then converted to the JSON threat file.

It was just a prototype https://github.com/raphaelahrens/threatmd

@izar the advantage for me was that the Markdown files were much easier on the eyes than the JSON file. :D

Here my example from back then.
https://github.com/raphaelahrens/threatmd/blob/main/test_examples/DO04.md