[Bro-Dev] first try at a skeleton script

[Gregor Maier]

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. 

Ok.
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.

ACK.

>> 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.


cu
gregor
-- 
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
USA