Trisul Network Analytics
Developer Zone

**This is an old revision of the document!** ----

====== Introduction to Trisul Scripting for Bro IDS users ====== Bro IDS is a popular open source network analysis platform. A key feature of Bro IDS is the custom BRO language that allows you to write scripts to enhance the functionality of the platform. Trisul Network Analytics is also a platform that can be extended by writing scripts. This page introduces the Trisul Scripting API for those who are already familiar with Bro IDS scripting. ===== Trisul API ===== ==== Outputs : database objects vs logs ==== Trisul is built from ground up to be full streaming analytics platform - database included. In Trisul, you work directly with database objects like metrics , resources, flows, documents, and graphs.This can be a bit confusing to Bro scripters who focus on generating logs. To illustrate with an example. **Say you are calculating TLS Fingerprints from network traffic** * In Bro, you might write scripts to add the fingerprint to the connection/flow log. * In Trisul, your approach would be to create a new counter group for TLS Fingerprints and count each print there. You can also mark the flows like Bro, or create graph edges, but the main focus is on metrics. ==== Two scripting pipelines in Trisul ==== A second architectural difference is : In Trisul, you can script either the packet processing stream or the analytics stream. We call these two streams the Frontend (Fastpath) or the Backend (slowpath). The Frontend / Fastpath scripts work on packets and reassembled payloads, and the Backend scripts work on objects like traffic metrics for a particular entity, Top-K, flows, resources, etc. The two pipelines can talk to each other using a messaging API. === Comparison === |Feature | Bro | Trisul | |language | .bro language | lua | |protocol decoding | Bro framework provides fine grained events representing protocol fields to your script. | Trisul framework provides a lower level access to the raw payload bytes for a protocol. You have to decode it yourself. It is not as hard as it sounds, you can use the BITMAUL library to dissect protocols to the depth you want | |events | fine grained "typed" events. For example ''dns_A6_reply(..)'' event contains parsed fields for the DNS AAAA reply record |loose documents in a canonical text format. In Trisul, //DNS Resource// is a text dump of a DNS transaction in a canonical DIG format. You can pick the fields you want using Regex. This means you have a dramatically lower number of events to deal with and are free to decode packets to the depth you want. | |extending | you can write C code and integrate it to your Bro scripting using a *.bif file. This involves a binary compile process |leverages LuaJIT FFI to directly call library functions |