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

Installation
The BroccoliSharp library has only been tested on Linux so far.
Prerequisites
BroccoliSharp requires the following libraries which need to be installed before you begin:
·
The Broccoli library
(of course!), Broccoli has its own requirements, see
docs.
·
Mono –
version supporting .NET 4.5 is preferred, but not required.
Building BroccoliSharp
To build the BroccoliSharp library using Mono you can use xbuild:
-
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
Safe Handles
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.