Something I’d like to figure out is how to document new notice types in the package documentation.
If I add a new notice type, e.g.
redef enum Notice::Type += {
IPv6 Router Advertisement packet seen with the Recursive
DNS Server Option that had length which could cause a
buffer overflow and can lead to code execution.
Bad_Neighbor_RCE_Attack_Detected,
IPv6 Router Advertisement packet seen with the DNS Search
List Option that had a length which will cause a buffer
overflow and can lead to a Denial of Service.
Bad_Neighbor_DoS_Attack_Detected,
};
All that Zeekygen generates is something which tells me that Notice::Type was redef-ed, but the comments on the specific types are lost:
Summary
Redefinitions ############# ============================================ = :zeek:type:`Notice::Type`: :zeek:type:`enum` ============================================ =
(I’m also not sure why there’s a space before the last = on those lines).
Another example is visible here: https://raw.githubusercontent.com/zeek/zeek-docs/master/scripts/policy/protocols/ssh/detect-bruteforcing.zeek.rst
If we look at the documentation for Notice::Type, all the new types are documented there: https://raw.githubusercontent.com/zeek/zeek-docs/master/scripts/base/frameworks/notice/main.zeek.rst
However this doesn’t work when moving detections to packages.
It seems like this is missing from Zeekygen, but I’m not sure of the right fix. Most enums don’t have comments for the various values. Do we look for comments for all enum values, and provide them if found? Or do we special-case Notice::Type?
–Vlad