BroccoliSharp: A .NET implementation of the Bro Client Communications Library.
BroccoliSharp is a set of managed C# based .NET classes and structures that wrap Broccoli, the "Bro client communications library". This library fully implements the Broccoli API and will allow you to create client sensors for the Bro intrusion detection system, receive Bro IDs, send and receive Bro events, as well as send and receive event requests to and from peering Bros. As in the native C Broccoli API, this .NET library can be used to create and receive values of pure types like integers, counters, timestamps, IP addresses, port numbers, booleans, and strings.
BroccoliSharp is free software under terms of the BSD license as provided in the LICENSE file distributed with the source code. This source code library was developed and is maintained by the Grid Protection Alliance who provides production grade open source software to electric utilities. This library was developed as part of a DOE CEDS project called "ARMORE" which is incorporating Bro within a security appliance for use in substations.
More details on BroccoliSharp usage can be found in the documentation related to the primary data structures. It is expected that the developer is already familiar with basic Bro concepts before using the BroccoliSharp library.
The BroccoliSharp library has only been tested on Linux so far.
BroccoliSharp requires the following libraries which need to be installed before you begin:
· Mono – version supporting .NET 4.5 is preferred, but not required.
To build the BroccoliSharp library using Mono you can use
xbuild /p:Configuration=Release BroccoliSharp.sln
To build a debug library, use:
xbuild /p:Configuration=Debug BroccoliSharp.sln
To build BroccoliSharp to work with a Broccoli release that has disabled PCAP support, use:
xbuild /p:Configuration=ReleaseNoPCAP BroccoliSharp.sln
To create builds that use SafeHandle implementations for opaque pointers use:
xbuild /p:Configuration=DebugWithSafeHandles BroccoliSharp.sln
xbuild /p:Configuration=ReleaseWithSafeHandles BroccoliSharp.sln
xbuild /p:Configuration=ReleaseNoPCAPWithSafeHandles BroccoliSharp.sln
To build BroccoliSharp to target older versions of Mono use one of the following:
xbuild /p:Configuration=Debug BroccoliSharp-NET4.0.sln
xbuild /p:Configuration=Release BroccoliSharp-NET4.0.sln
xbuild /p:Configuration=ReleaseNoPCAP BroccoliSharp-NET4.0.sln
xbuild /p:Configuration=DebugWithSafeHandles BroccoliSharp-NET4.0.sln
xbuild /p:Configuration=ReleaseWithSafeHandles BroccoliSharp-NET4.0.sln
xbuild /p:Configuration=ReleaseNoPCAPWithSafeHandles BroccoliSharp-NET4.0.sln
You can also build the library on Windows using Visual Studio and the binaries should still work on Linux depending on the corresponding installed version of Mono.
Once the BroccoliSharp.dll exists (found in the output folder associated with the build configuration, e.g., "/Main/Build/Output/Release" relative to source), you can add a reference to the library in your .NET projects and begin using BroccoliSharp.
In order for your .NET application to be able to find the Broccoli API shared library (i.e.,
libbroccoli.so), you will need to add the location of this library to your
Linux library path (e.g., add path to
LD_LIBRARY_PATH environmental variable).
See Mono Interop documentation on
"Library Handling" for more detail.
About the Code
The source code has been defined with precompiler directives to allow for compiling the code to
either use direct pointers or use safe handles for opaque Bro types. Generally, as their name
implies, safe handles are the ideal choice when using managed code with unmanaged code. See the
documentation for more detail. In general, multi-threaded race conditions between garbage collection
and pointer usage can be avoided and the unmanaged memory allocations the pointer references will
be disposed of properly even if the program abnormally terminates. That being said, depending on the
version of Mono you are targeting, the safe handle implementation may not be fully cooked. Also, if
you are trying to debug your .NET application and get Mono to report verbose information, there is a
lot less noise to filter through when you are just using pointers. As a result, you can choose which
mode of operation you want to use depending on your task. For any production level deployments, it is
recommended to use the
ReleaseWithSafeHandles build configuration with a
later build of Mono.
When building inside Visual Studio code analysis is enabled for this project. A rule set is included with the source code (i.e., BroccoliSharp.ruleset) that defines the analysis rules that are enabled for the project. Note that this rule set is basically just the "Microsoft Managed Recommended Rules" with one rule turned off: CA1060: Move P/Invokes to NativeMethods class. This rule wants to force the name of the imported Bro API functions class to be "NativeMethods", but "BroAPI" was preferred for this project.
The code has also been through extensive analysis using the Gendarme tool. All reported items of concern have been corrected and the remaining items have been reviewed thoroughly. A future to-do could be to create an exclusion list with justifications.