Documenting new Notice Types in Packages?

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

> ============================================ =
> :zeek:type:`Notice::Type`: :zeek:type:`enum`
> ============================================ =

(I'm also not sure why there's a space before the last = on those lines).

It's a table with one row, two columns. The 2nd column is empty
because the `redef` itself has no associated commentary (and Zeekygen
does not currently document the extending fields/enums at that
location).

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.

Here's a patch that improves Zeekygen to include the extending
fields/enums in the "Redefinition" section:

    https://github.com/zeek/zeek/pull/1237

Think that will work for this purpose; let me know if you try and find
otherwise.

- Jon

Thanks, Jon. I think that looks great!