BroccoliSharp: A .NET implementation of the Bro Client Communications Library.
C# Visual Basic Other
Switch branches/tags
Nothing to show
Clone or download
Permalink
Failed to load latest commit information.
Documentation Updated README to use mark down. Nov 18, 2014
Icons Initial source code commit. Nov 7, 2014
Internal Improved compact event structure marshalling. Nov 13, 2014
Properties Added build configurations to allow either IntPtr or SafeHandle imple… Nov 12, 2014
Tests Removed 32-preference for test applications. Nov 22, 2014
.gitattributes Initial commit to add default .gitIgnore and .gitAttribute files. Nov 7, 2014
.gitignore (1) Implemented safe handles for all Bro opaque pointer types Nov 10, 2014
BroAddress.cs (1) Implemented safe handles for all Bro opaque pointer types Nov 10, 2014
BroConfiguration.cs Initial source code commit. Nov 7, 2014
BroConnection.cs Improved compact event structure marshalling. Nov 13, 2014
BroConnectionData.cs Initial source code commit. Nov 7, 2014
BroConnectionFlags.cs Initial source code commit. Nov 7, 2014
BroEvent.cs Added args style param array overload for AddParameters method in Bro… Nov 17, 2014
BroEventArgs.cs Initial source code commit. Nov 7, 2014
BroEventQueue.cs Added build configurations to allow either IntPtr or SafeHandle imple… Nov 12, 2014
BroField.cs Updated code documentation. Nov 8, 2014
BroPacket.cs Added build configurations to allow either IntPtr or SafeHandle imple… Nov 12, 2014
BroPort.cs Initial source code commit. Nov 7, 2014
BroRecord.cs Added build configurations to allow either IntPtr or SafeHandle imple… Nov 12, 2014
BroSet.cs Added build configurations to allow either IntPtr or SafeHandle imple… Nov 12, 2014
BroString.cs Initial source code commit. Nov 7, 2014
BroSubnet.cs (1) Implemented safe handles for all Bro opaque pointer types Nov 10, 2014
BroTable.cs Added build configurations to allow either IntPtr or SafeHandle imple… Nov 12, 2014
BroTime.cs Initial source code commit. Nov 7, 2014
BroType.cs Initial source code commit. Nov 7, 2014
BroTypeExtensions.cs Initial source code commit. Nov 7, 2014
BroValue.cs Added build configurations to allow either IntPtr or SafeHandle imple… Nov 12, 2014
BroValueExtensions.cs Initial source code commit. Nov 7, 2014
BroVector.cs Added build configurations to allow either IntPtr or SafeHandle imple… Nov 12, 2014
BroccoliSharp-NET4.0.csproj Updated README to use mark down. Nov 18, 2014
BroccoliSharp-NET4.0.sln Added normal Bro ping test along with Bro record based ping test. Nov 13, 2014
BroccoliSharp.csproj Updated README to use mark down. Nov 18, 2014
BroccoliSharp.ruleset Initial source code commit. Nov 7, 2014
BroccoliSharp.sln Added normal Bro ping test along with Bro record based ping test. Nov 13, 2014
BroccoliSharpHelp.shfbproj Updated output paths for all build configurations Nov 13, 2014
LICENSE Initial source code commit. Nov 7, 2014
NamespaceDoc.cs Initial source code commit. Nov 7, 2014
README.md

README.md

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.

Build status

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.