[Bro-Dev] Documenting Weirds
It seems like one area where our documentation is sorely lacking is the weirds. Apart from comments in the code, I believe the only documentation is the name of the weird itself. Is there a mechanism in Broxygen to document weirds? If not, has anyone thought about what such a mechanism might look like? --Vlad ___ bro-dev mailing list bro-dev@bro.org http://mailman.icsi.berkeley.edu/mailman/listinfo/bro-dev
Re: [Bro-Dev] Documenting Weirds
On Jun 27, 2014, at 3:35 PM, Vlad Grigorescu wrote: > Is there a mechanism in Broxygen to document weirds? If not, has anyone > thought about what such a mechanism might look like? There’s not currently a mechanism. Things that Broxygen can easily aid in documenting are tied to a script-layer name/symbol/identifier. Weirds differ since they’re string values. A suggestion would be to change weirds to use an enum instead of a string value. That would then provide an identifier to hang documentation off of and also maybe help keep the core-analyzers in sync w/ scripts (e.g. there’s currently not a robust way to signify to a user that a weird was removed/changed and thus their scripts may become stale or possibly broken in the case of a rename). - Jon ___ bro-dev mailing list bro-dev@bro.org http://mailman.icsi.berkeley.edu/mailman/listinfo/bro-dev
Re: [Bro-Dev] Documenting Weirds
On Fri, Jun 27, 2014 at 21:41 +, you wrote: > A suggestion would be to change weirds to use an enum instead of a > string value. Yeah, either that, or introducing a structured ID namespace (e.g., "http.client.unexpected_data"), potentially with some static analysis to find IDs that aren't linked to docs. In either case it would be nice if the scheme unified reporting weirds from core and script land. Robin -- Robin Sommer * Phone +1 (510) 722-6541 * ro...@icir.org ICSI/LBNL* Fax +1 (510) 666-2956 * www.icir.org/robin ___ bro-dev mailing list bro-dev@bro.org http://mailman.icsi.berkeley.edu/mailman/listinfo/bro-dev
Re: [Bro-Dev] Documenting Weirds
I was thinking of just a simple Weird::Type enum with comments, much like how the Notice documentation is generated. I do also like the thought of the structured namespace. Maybe more generally, we should to make a Weird closer to a Notice. For example, if a file analyzer generates a weird, there are no fields in the weird.log to map it back to the offending file. I realize that that's trickier, since Weirds can be generated from either the core or script-land. --Vlad On Fri, Jun 27, 2014 at 5:54 PM, Robin Sommer wrote: > > > On Fri, Jun 27, 2014 at 21:41 +, you wrote: > > > A suggestion would be to change weirds to use an enum instead of a > > string value. > > Yeah, either that, or introducing a structured ID namespace (e.g., > "http.client.unexpected_data"), potentially with some static analysis > to find IDs that aren't linked to docs. > > In either case it would be nice if the scheme unified reporting weirds > from core and script land. > > Robin > > -- > Robin Sommer * Phone +1 (510) 722-6541 * ro...@icir.org > ICSI/LBNL* Fax +1 (510) 666-2956 * www.icir.org/robin > ___ bro-dev mailing list bro-dev@bro.org http://mailman.icsi.berkeley.edu/mailman/listinfo/bro-dev
Re: [Bro-Dev] Documenting Weirds
On Sat, Jun 28, 2014 at 11:46 -0400, you wrote: > Maybe more generally, we should to make a Weird closer to a Notice. For > example, if a file analyzer generates a weird, there are no fields in the > weird.log to map it back to the offending file. Yeah, that would make a lot sense. > I realize that that's trickier, since Weirds can be generated from > either the core or script-land. One thing to keep in mind is that it shouldn't become burdensome to write the code for generating a Weird, in particular in core land. The situations that they report are (supposedly) rare, so it's not worth spending much time on. Right now, one appeal of the Weirds is that it's to say "alright, shouldn't happen, weird() if it does"; but if one would need to start building Vals etc. to pass the right parameters with it, one might become more inclined to skip the check (because it shouldn't happen anyways :) This is not a huge issue, and could probably be solved with a few wrappers covering common cases (and we have some of that already, like the WeirdConn() etc.; could extend that a bit more). Robin -- Robin Sommer * Phone +1 (510) 722-6541 * ro...@icir.org ICSI/LBNL* Fax +1 (510) 666-2956 * www.icir.org/robin ___ bro-dev mailing list bro-dev@bro.org http://mailman.icsi.berkeley.edu/mailman/listinfo/bro-dev
