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.

Documentation

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.

• For details on how to manage connections, handle connections classes, and send events using BroccoliSharp, see topic remarks for the:
  • BroConnection class
• For details on how to handle record structures in BroccoliSharp, see topic remarks for the:
  • BroRecord class
• For details on how to handle tables and composite keys in BroccoliSharp, see topic remarks for the:
  • BroTable class
• For details on how to handle sets in BroccoliSharp, see topic remarks for the:
  • BroSet class
• For details on how BroccoliSharp safely passes strongly-typed values into Broccoli API functions with void* values, see topic remarks for the:
  • BroValue class
• For details on the BroccoliSharp structures and classes that are associated with each of the Bro types, see topic remarks for the:
  • BroType enumeration

Download

Source Code: Download Zip

BroccoliSharp is hosted on GitHub: GridProtectionAlliance/BroccoliSharp

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.