Architecture
With scriptable protocols, it is possible to add new detection capabilities in Guardian. These protocols are implemented using the Lua scripting language and have access to most of the hardcoded traffic inspection and detection functionality via a dedicated application programming interface (API).
There are two different kinds of scriptable protocols, differing on the way they are invoked in the traffic processing pipeline:
- Standalone protocols
- Extensions
Standalone protocols
Standalone protocols handle transmission control protocol (TCP) / UDP traffic in an exclusive way: when a session is deemed to be handled by a standalone protocol then all packets belonging to it will be handled by this protocol and no other standalone protocol (hardcoded or not) will be involved. With standalone scriptable protocols, it is possible to implement a completely new protocol that currently doesn't have a dedicated handler in Guardian.
Standalone protocols are identified by their name and when instantiated they are inserted
to the list of possible packet handlers in the packet pipeline. When offered a packet they
have the opportunity to declare themselves (via the can_handle function) as
handlers of the session. If a positive response is provided, then this packet as well as all
subsequent packets in the session are classified as being handled by the specific protocol
and will all be offered for processing to the update_status callback.
Another possibility with standalone scriptable protocols is to override existing hardcoded implementations of a protocol. In such a case, the name of the scriptable protocol should be the same as the one to be overridden. This possibility should be used only in extraordinary circumstances: hardcoded protocols offer rich handling and it is going to be challenging to offer equivalent handling via Lua scripting.
Standalone protocols get to handle raw packets as they are captured by the network interface. For this reason, any kind of message delineation / defragmentation will need to be done by the scriptable protocol itself.
Extensions
Extensions are scriptable protocols that add detection capabilities on top of existing (hardcoded or not) standalone protocols. There is no need to completely handle the traffic of a specific protocol (this is done by the standalone protocol being extended), but instead to implement the additional detection capabilities requested.
Extension protocols are identified by the protocol being extended and their name. Their
identification string is constructed by concatenating the name of the standalone protocol
being extended, with the name of the extension protocol using the hash character as
separator. For example, the extension protocol token_detector that is extending the
http protocol will use http#token_detector for its identification.
Extension scriptable protocols are offered packets that have been accepted and handled by
the base standalone protocol. Accordingly, their can_handle function needs to check
only if the extension should handle a specific packet of the base protocol (and not do
thorough checking if the packet is indeed a base protocol one). Also, if there is any
message delineation / defragmentation done for the protocol, this will already been done by
the base protocol: the extensions will get to handle complete, reconstructed messages.
Safe restarts
The activation of a scriptable protocol is an operation that carries some risk: since new traffic handling components are being added in the packet processing pipeline, it is possible that the characteristics of the system are adversely affected, or even worse that restarts are triggered. Care has been taken to protect the system from errors happening during script execution, but it is still possible to eventually have system disturbances.
As a safety net against such occurrences, the safe restarts detection feature has been implemented. According to it, if Guardian is doing non graceful restarts too frequently (by default if more than 3 times in the last 15 minutes), then the system switches into safe restart mode. In this mode, no scriptable protocol gets activated (the user gets informed about it in the log file).