[Bro-Dev] first try at a skeleton script

Gregor Maier gregor at icir.org
Mon Oct 18 17:11:16 PDT 2010

On 10/17/10 21:36 , Robin Sommer wrote:
>> I'm just wondering whether not using markers might end up exploding in
>> our faces once enough people write doc strings ....
> "Exploding" in which sense?
> (Note that I'm not too strong on not using markers; I personally
> find them cumbersome, but I can also configure my editor to do it
> for me :)

I'm worrying that if we don't require markers (but infer the parameters)
somebody will write a doc string that confuses the auto-detection and we
get incorrect / weird output. Don't know how much of a problem this is
going to be though.

>> Is a user somebody who just needs to use the "interface" (globals,
>> events, etc.) the script defines or somebody who might want to modify
>> the script according to their needs.
> I meant the former. I don't think we should formalize documenting a
> script's internals. As Adam wrote, for that it's often easier to
> read the source directly, and where it isn't, a few informal
> comments (which don't go into the reference manual) are fine, just
> as it's now. 

OTOH, I think it's nice if functions and parameters are described or
documented briefly, even if they are internal.  However, If somebody has
to modify the policy script's code (as I had to do for my
http-analysis), it's helpful to have such documentation in the src code.
But yes, they don't need to go into the reference manual.

> My point was a different one: Seth's initial skeleton had some
> instructions for the person writing a script *initially* (e.g., how
> to structure things etc.).  I found that confusing as there was no
> separation between these and things which will be left in the final
> script for people later needing to understand the interface.


>> Or maybe the per-element doc-comments can have a flag indicating whether
>> they are public interface or internal functionality. 
> Can't we just use the export section? Everything in there is by
> definition part of the interface and should be documented. 

Yes. Didn't think about that actually.

>> Maybe more general: can we come up with a nice way to document the redef
>> of the various "special purpose" globals that are edited by many
>> scripts? E.g., Notice enums, capture filters, analyzer configurations, etc.
> Good point. For these we need two different types of documentation:
> one defining the purpose of the global, and one which states how a
> script modifies the global when loaded. However, there aren't that
> many of these so we might be fine special-casing them (i.e., just
> listing which notices, filters, etc. a script defines).

Yeah. And maybe have a tool, script that, given the names of the
"special globals", goes through the policy files and lists how each
policy script modifies them.

Gregor Maier                                             gregor at icir.org
Int. Computer Science Institute (ICSI)          gregor at icsi.berkeley.edu
1947 Center St., Ste. 600                    http://www.icir.org/gregor/
Berkeley, CA 94704

More information about the bro-dev mailing list