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.
Many of the following documentation topics have been derived from key portions of the official Broccoli documentation put into context of using BroccoliSharp from a .NET application. Many topics also include usage examples in C#. The BroConnection class topic remarks include examples in VB.NET and Java using IKVM.NET.
Source Code: Download Zip
BroccoliSharp is hosted on GitHub: GridProtectionAlliance/BroccoliSharp
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:
To build a debug library, use:
To build BroccoliSharp to work with a Broccoli release that has disabled PCAP support, use:
To create builds that use SafeHandle implementations for opaque pointers use:
To build BroccoliSharp to target older versions of Mono use one of the following:
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.
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.
Contains fundamental classes for interaction with the Broccoli API from within a .NET environment.