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 | LuaJIT | |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 | |time budget | packet drops if script is slow |frontend scripts have to execute fast to avoid packet drops, backend scripts have a more relaxed time budget of about 0-30 seconds. | |deployment|place script files in directory| similar place scripts in directory on probe or put it on the hub node for automatic deployment to all probes | |debugger| manual | built in LUA debugger. just call ''dbg()'' to drop into an interactive debugger| |threading|single with load balanced workers | multithreaded with load balanced threads, this allows for very fast state sharing between multiple threads using message passing. During development and debugging you can turn it into a single threaded system | |async|yes|yes - you can have a deferred execution of a LUA code block| |intel|intel framework|Essentially we use a LevelDB library via FFI to dump all the Intel items and use that to lookup threat indicators| |packaging|Yes - Bro packages| Yes - Trisul APPs | |docs|[[https://www.bro.org/sphinx/scripting/index.html#understanding-bro-scripts|Bro Scripting]]|[[https://www.trisul.org/docs/lua/|Trisul LUA API]] |