This is an old revision of the document!
Table of Contents
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 |