broShell.html

BroShell 0.2

Introduction

The BroShell is an interactive shell used for bro administration and configuration which allows an administrator to log into a bro instance and interact with it directly via bro events. The current instance is more of a proof of concept, but operational information such as memory, cpu and connection information can be extracted. Even more interesting is the ability to modify running policy and inject/extract data from the running instance including policy such as the ability to drop hosts or data relating to specific hosts. If something can be written into the bro policy language (which is not dependant on existing at run/interperate time), it should be able to be hooked into the shell. See the example code for details.

The bro shell is actually two components. The first is the bro shell program. This is the command shell parser and interpreter. It uses the Broccoli library to take the pased commands and create bro events that are handed over to the second component on the bro 'server' side. The policy component on the 'serve' side interprets the events created by the first and performes whatever task is requested. This could be anything from responding to a ping event, to modifying the status of a provided IP address.

To start the shell on a local machine, just make sure that there is a non-encrypted listener running on 47758/tcp. More details on this will be included shortly. You should see something like this:

[scottc@localhost test]$ ./shell
Handshake complete, starting shell...
-->
--> ping
pong event from 127.0.0.1: seq=1, time=0.009791/1.009742 s
-->

An overview of the current set of commands available to the shell are as follows. They have been set up more to explore the range of functionality of the shell than to provide a useful tool for bro administration. The (0.2) version of the shell has been set up for fleability in tool creation so that additional functionality can be added as needed.

A new type of functionality has been added via the shell. The 'lookup' series of commands rely on creating a policy side listing of connections that are defined by a list of parameters. This data is not normally accessable due to the way that the event engine defines connection information. In it's current form, the hash table uses a full 4-tuple for each connection - it is therefore nearly impossible to look up connection s relating to a single IP as a source or destination. The default conditions are all successful connections. Support will be added so that additional parameters can be set via the command line such as particular IP addresses, networks, or even all connections. Since this mechanism lives on the policy side of bro, it should not be turned on without fully understanding the possible implications of this. Possible uses might be monitoring the current active connections for a given IP rather than waiting for the data to be flushed out from the state tables after timeout of connection completion.

Command taxonomy is similar to a unix shell or a cisco like command line with the general identifier being followed by a more specific parameters:

show
        cpu
        memory|mem
        conn
        dropped [ip]
        scan [ip]
        lookup [ip]
        lookup [ip] [ip]
        pcap

set
        scan clear [ip]
        scan [on|off]
        lookup [on|off]
        drop [on|off]
        pcap [expression]
ping
drop
undrop

Expressions enclosed by '[ ]' are mandatory, so to examine the dropped status of a given IP you might enter: 'show dropped 10.10.10.10' . A detailed listing of commands and examples are as follows.

Command Reference

Command	Sample/Notes
show cpu	Provides ratio of CPU and clock time. --> show cpu total CPU time/total clock time: 0.009896
show memory\|mem	Basic information regarding memory usage. --> show memory total mem (k): 2719744 minor faults: 827 major faults: 693 num swap: 0 blocking input: 0 blocking output: 0 context changes: 0
show conn	Overview of connection related information. --> show conn connection data: tcp (current/max): 0/0 udp (current/max): 0/0 icmp (current/max): 0/0 fragments (current/max): 0/0
show dropped	A yes/no answer for the drop status of an IP address. --> show dropped 10.10.10.1 Host 10.10.10.1 is not dropped
show scan	Provides an overview of scan data regarding a provided IP. --> show scan 10.10.10.1 scan data for 10.10.10.1: host count: 0 backscatter count: 0 possible scan source: 0
show pcap	Lists current pcap filter. --> show pcap tcp or udp or icmp
set scan clear 10.10.10.1	Clears all scan data on an IP and removes it from the list of identified scanner host addresses. Also removes it from the list of dropped addresses. (log output) DynamicPolicyChange <127.0.0.1:33376/tcp> reset_scan called on 10.10.10.1
set scan on	Turn on scan detection. DynamicPolicyChange <127.0.0.1:33376/tcp> suppress_scan_checks = F
set scan off	Turn off scan detection. DynamicsPolicyChange <127.0.0.1:33376/tcp> suppress_scan_checks = T
set drop on	Turn host auto host dropping on. DynamicPolicyChange <127.0.0.1:33376/tcp> allow drop changed to T
set drop off	Turn auto host dropping off. DynamicPolicyChange <127.0.0.1:33376/tcp> allow drop changed to F
set lookup on	Activate 'lookup' related functionality. DynamicPolicyChange <127.0.0.1:33377/tcp> connection lookup toggled to T
set lookup off	Deactivate 'lookup' related functionality. DynamicPolicyChange <127.0.0.1:33377/tcp> connection lookup toggled to F
set pcap "filter"	----- currently broken - fixing parser
ping	Simple event connectivity test. pong event from 127.0.0.1: seq=1, time=0.009782/3.229675 s
drop	Manually drop a host. A series of tests are performed and feedback provided in case dropping is not allowed. --> drop 10.10.10.1 Dropping not allowed via policy --> set drop on --> drop 10.10.10.1 Address 10.10.10.1 dropped 1120514311.000000 DynamicPolicyChange <127.0.0.1:33379/tcp> allow drop changed to T 1120514316.000000 AddressDroppedShell <127.0.0.1:33379/tcp> dropping address 10.10.10.1 via interactive shell
undrop	Remove a host from the dropped list, but do not reset the scan statistics related to it. DynamicPolicyChange <127.0.0.1:33380/tcp> host_undrop called on 10.10.10.1
	NOTE: the 'lookup' series of commands should not be used without understanding the performance penalties of using this mechanism. These commands are still in testing and may not always do what you expect!

show lookup 210.173.179.46:	If 'lookup' functionality is activated, return all connections with the source address equal to the provided IP. --> show lookup 210.173.179.46 210.173.179.46:34635/tcp -> 128.55.6.34:80/tcp 210.173.179.46:34642/tcp -> 128.55.6.35:80/tcp
show lookup 210.173.179.46 128.55.6.34	If 'lookup' functionality is activated, return all connections that match the source-dest pair provided. --> show lookup 210.173.179.46 128.55.6.34 210.173.179.46:34635/tcp -> 128.55.6.34:80/tcp

Download

Sample code can be found for the policy and the client here:

POLICY 0.2
CLIENT 0.2