in this next section, I'm going to discuss one of Bro's central concepts, the event
in bro like many programming languages, Actions Air carried out When something occurs
and Breaux's case that something is an event,
you can think of events in bro like events in real life, they represent a thing that happened or is happening
in real life. A traffic analyst reconstructs a TCP stream from a pea cap
by tracing the originating sin, responding Cenac in the final act of the three way handshake.
When Bro analyzes that same pea cap and reconstructs the three way handshake,
it executes events that signify where in the reconstruction process it iss.
It will execute an event when the first sentence scene,
when the connection is established. And so
bro actually represents TCP, UDP and ICMP Communications. This way,
many of Rose Protocol analyzers execute events throughout their traffic analysis life cycle as well
broke or makes many events globally accessible for handling that could be used to satisfy a wide variety of use cases.
In fact, Bro's Base contains 51 individual bro scripts,
26 frameworks in 21 protocol analyzers.
In total, they declare 119 globally accessible events, which provides extensive functionality and capabilities in network traffic analysis,
I'll provide a link in the resource is section tomb or information about pros built in events.
Events could be executed from any of bro's excusable types.
When they are, they're past the required arguments. If there were any defined.
Handlers are blocks of code that are executed every time an event is executed.
Handlers joined a queue in order of priority,
and that priority is determined by the priority attributes that has specified when the handler is declared.
If no priority attributes is specified,
the handler assumes a default priority of zero,
as mentioned before broke or executes many events. It also defines numerous event handlers for its own built in events.
Many of Bro's protocol analyzers define handlers for core events, and these do the dissection analysis and Richmond and transformation task that take raw packets and turn them in the logs that broz known for.
Along the way, event handlers declared by non core policy scripts perform a variety of other analysis tasks like capture measurements for statistics, store traffic artifacts or evaluate protocol fields for specific patterns or attributes,
and the next slide will take a closer look at how handlers interact with events through event cues.
Now let's step into this from a different perspective.
For the purposes of this discussion, let's say that this box represents Bro's runtime environment.
The process starts, does some low level set up and reads and interprets any scripts that air specified in broke. Or
many of these core scripts declare events.
The declaration of events results in the creation of event cues within the main bro process.
It can help to think of these. Choose as a data pipeline where you can imagine events entering on one end and exiting on the other.
Scripts defined event handlers that attached to this pipeline
and work with the record instances in the events. As they pass through,
each handler gets access to an event and its record instance once and only once,
Bruce script interpreter executes non core scripts and policies. Last
new scripts can also declare events which results in the creation of an event cue in the court process.
Scripts executed by the interpreter not only declare in trigger events, they define handlers, too.
Handlers are a black of code that gets executed any time an event is executed.
The order in which handlers are executed is determined by the priority attributes.
The attribute is set when an event handler is declared in bro script
as the packets of process by broke or the event engine inspects the packet headers and determines if the new packet is related to an existing connection or one. It is already tracking when that determination is made broke or generates events relevant to the part of the UDP TCP, or ICMP, exchange, that is currently taking place.
When an event is executed, each of its handlers is executed in order of priority.
The priority is determined based on a range of imagers where higher positive imagers represent higher priority and lower negative integers are lower priority.
Each event handler does some work with the arguments contained in the event.
Those arguments could be a record type
and or any combination of Bro's other non execute herbal types.
The handler does some work with the arguments and actually executes other events.
Those events are passed through event cues, and the process continues until each handler for every triggered event has been executed.
Now let's talk about the difference between invocation and declaration with regard to events.
When you see the word event in bro script, it could be in a couple different context. This could be confusing at first, and it's helpful to understand the differences. Early on,
events in their handlers are referenced in to general ways, and Bro Script declaration and In Vocation
declaration is required. Invocation is optional.
Typically, events in Brewer declared as global variables inside of an export block.
In this declaration statement, the events arguments are also defined.
An example of this global variable declaration is shown here
the key word global, followed by the name of the new event,
followed by the type specifications in this case event,
followed by the list of names, arguments which is contained inside of these parentheses.
Events do not require arguments, and there can also be multiple arguments of varying types.
Each argument is assigned a name and it's type specified.
In many cases, an event declaration will include a record type as an argument, such as in the example here, the argument is the info record defined by the alerts module.
Passing record instances between event handlers is a common practice for sharing and working with Connection State and Bro
event handlers are declared within the main body of the script. In other words, they're not available to other scripts.
A Handler declaration will specify the event name in arguments list that match the event declaration,
as shown in the second example here, The handler's name is the same as the event alert underscore triggered,
and the list of arguments is also exactly the same as the event declaration.
A large portion of Bro's Execute herbal code is defined within event handlers.
Handlers perform a multitude of analysis task, including the cause of the logging frameworks right function that rights record instances to disc in the form of log entries.
Invocation occurs when bro events are executed within an executed will. Type like an event handler at this point, broke. Use all of the declared handlers for execution in the define priority order and passes them each the event arguments, if any, were declared.
I understand the difference between declaration and in vocation can be difficult, so I suggest you take a look at some of the scripts included in bro source and other resources available to get more familiar.
I mentioned the Bro, innit. event several times during the prologue segment
Ruin. That is what can be referred to as a bro process event, and it's one of two I want to mention now.
Rohan. It is executed once every time the bro process starts up, and it's used for things like declaring Constance, setting up log streams and filters as we discussed before, as well as configuring inputs like threat Intel feeds.
Conversely, Brogan is executed. Every time a bro process shuts down,
you might not find much need for bro Done. Initially, it is a valuable event for cleaning up state information being maintained by your scripts or preserving data to desk before it's cleared out of bro's memory.
Now let's take a look at some of Bro's more commonly used events. The connection state events,
the vast majority of events generated by Bro, our Connection state events.
The first of these I want to mention, is the new connection event.
As you might expect, this is executed every time RO begins tracking a new connection. That is when Bro sees the first packet of a new connection.
At this point in the tracking process, Bro knows very little other than the layer three and layer four details.
The connection established event is executed when Bro sees the sin AC in response to the originating sin of a TCP connection.
This doesn't signify the completion of the TCP three way handshake,
but at this point, Bro begins tracking the connection and assigns a day. You it a unique identifier
connection. State Remove events are triggered when Bro has completely finished its processing of a connection. Both sides have closed the session or the activity time out for the protocol has expired.
At this point, Bro has learned everything it can know about a connection.
All of it's protocol analyzers have finished running, and Bro was about to remove the connection from memory.
This is an important event to be aware of because it's executed for every connection, regardless of protocol.
You can handle this event an access. All of the information Bro gathered about a connection
in a single record, which is very convenient.
As I mentioned, Bro also strives to make its handling of UDP look and feel like its handling of TCP,
and this is apparent in the U. T. P Session Done event
for protocol's like D. N s NTP Net Bios and CeCe Log.
Bro executes these events when it has seen the request and Response sides of UDP transaction or the UDP activity timer has expired.
Now let's take a closer look at the connection. State Remove event.
The Connection State remove event is triggered for every connection Bro analyzes, regardless of protocol
has shown below, this event has declared, with a single argument the connection record
and the script editor here. I've pasted a formatted instance of a live connection record.
Connection records aren't normally written to a log in this state. So for demo purposes,
I've written a small script that converts them to Jason and Prints to standard out.
As you can see here, there are many field available at the time. Connection. State Removed is executed
as you saw before. The connection record contains the I D Field, which is also a record.
The I D. Is where you find eyepiece and ports and use in the connection.
Additionally, note how bro includes an instance of the http info record in the http field.
This is where the convenience of certain events is apparent as a bro script author can work with the connection fields in http fields inside of a single event handler
Toe Access Record Field within the http record used the sub record dollar sign notation. As I've shown here,
you'll see and probably need this syntax a lot in bro script, so it's worth getting familiar with early on.
Now, let's talk about some of the log events to find my bro.
Most of Bro's protocol analyzers define a log underscore event that contains the analyzers info record as Theo. Only argument.
Unlike other events that represent the different stages of a network transaction
these air generated when protocol analyzers have completed,
we're reached the point where an event needs to be written to a long stream.
The Analyzers info record is typically the only argument passed with the log underscore event.
The info record instance contains the protocol Metadata Bro has collected up until this point.
This often occurs when a client and server exchange has completed, such as the case with http and D. N s
log underscore. Events are very useful on bro scripting and our good mechanism for performing more extensive scripting operations.
For a quick example, let's take a look at the log underscore http event
and the http info record.
We saw this before when we reviewed the http law
and bro script. We can handle the log underscore http event and have programmatic access to everything contained in that info record.
As you can see here, this includes a lot of great information and fields and values that support a variety of analysis. Task.
No, I briefly want to mention Bro's other protocol analyzers.
I've mentioned Rose http analyzer a lot because it's one of the most commonly sought after by New Bro. Users
broken analyze many other application layer protocols, however, and all of the analyzers shown here declared globally accessible events.
One of the first steps you'll take when defining a new bro script is to see if bro supports the protocol you want to work with.
Next. Take a look at the events generated by that analyzer.
You can find these in a few places. For instance, this is a list of protocol analyzer event declaration files.
These are big ifs or built in function files,
and they're defined by each analyzer.
They contain. The events relevant the inspection of each of the listed protocols,
alternatively, a protocol analyzers log. Underscore event is typically defined in that analyzers main dot bro script file.
You can find this in the directory path of the analyzer itself.
When you're reviewing a bro Modules contents on the documentation website.
Take a look at the navigation menus on the right hand side.
From here, you can jump directly to the event section.
As a bro script author, you can define event handlers for any of these events, giving you access to an enormous amount of protocol. Instance. Information
exposing protocol analysis results in this way is part of what makes bro scripts so extensible and attractive for ongoing analysis as well as incident response.
Now let's take a look at some of bro's file analysis events.
When Bro's Files framework is enabled, events are also generated during the various phases of the file analysis process.
This isn't functionality were spending a lot of time one than this course, but it's definitely good to be aware of.
The design of the files framework is consistent with the design of Rose Connection handling in that events are triggered as analysis progresses and they're handled in the very same way.
For instance, Bro declares a file new event that has executed whenever it determines a new file analysis is underway.
File sniff, on the other hand, is executed. One bro has performed some analysis of the first chunk of the file,
but a fault. That chunk is 4000 and 96 bites.
At this point, Bro is determined the files type and applied any specified analyzers.
Another consistency with Bro's connection handling, is the files frameworks file State Remove event, which is triggered every time bro completes analysis of a file.
At this point, all hashing an extraction operations have completed
handlers or the file state Remove event can access that calculated file hashes. And if the file was extracted, then do something with the file
is very helpful to remember this event for when you need to perform some external action on files extracted by bro.
In this segment, we reviewed bro events in detail.
I described how the event could be associated with real life occurrences that relates a network traffic analysis.
I also mentioned how handlers air defined and executed based on priority.
After that, I described how events in handlers are declared in invoked.
From there, we reviewed several of Bro's built in events, including process events like bro in It and Bro Done,
as well as connection oriented events like Connection State Removed.
Finally, I discussed how application protocol and file analysis events are also available for handling and bro script.
This exposes a tremendous amount of extensive bility and potential for implementing many analysis use. Cases
in the next section will introduce Bro's other types and expand on our previous examples to illustrate how and why those types were used.