search

minvws / nl-kat-coordination

Repo nl-kat-coordination for minvws
European Union Public License 1.2
121 stars 55 forks source link

Extend Octopoes documentation with object definitions #2946

Open zcrt opened 2 months ago

zcrt commented 2 months ago

Is your feature request related to a problem? Please describe. https://github.com/minvws/nl-kat-coordination/pull/2858 greatly enhanced the documentation on Octopoes objects. However, it would be even greater if explanations/definitions for (some) objects could also be added. E.g. what does it mean to be a RiskLevelSeverity Octopoes model finding? How would a DNSSPFMechanismNetBlock be defined?

Describe the solution you'd like Ideally, docstrings will be added to the objects giving a definition in one or two sentences and maybe an example when to use this object. These docstrings could then automatically appear as a description in the documentation.

Additional context Potential duplicate though unclear due to missing description: https://github.com/minvws/nl-kat-coordination/issues/2273 Related: https://github.com/minvws/nl-kat-coordination/issues/2622

ammar92 commented 1 month ago

Thanks for the suggestion. https://github.com/minvws/nl-kat-coordination/pull/2858 indeed served as a framework to enable model documentation. Besides the provided examples, do you have more models that need to be documented? This would help us prioritize them accordingly.

zcrt commented 1 month ago

Well, ideally all of them ;). Nevertheless, the (octopoes.models.ooi.)web, reports, config, monitoring and email_security may be good starting points, while network, dns.record, dns.zone and findings may be more self-explainatory.

However, that may be my personal subjective view. (Which also means I might be able to help documenting the latter ones if you can provide some examples how you would like those documented)