Previous: Connection summaries, Up: Generic Connection Analysis



7.3.7 Connection functions

We finish our discussion of generic connection analysis with a brief summary of the different Bro functions provided by the conn analyzer:

conn_size e: endpoint, is_tcp: bool): string
returns a string giving either the number of bytes the endpoint sent during the given connection, or "?" if from the connection state this can't be determined. The is_tcp parameter is needed so that the function can inspect the endpoint's state to determine whether the connection was closed.


conn_state (c: connection, is_tcp: bool): string
returns the name associated with the connection's state, as given in the above table.


determine_service c: connection): bool
sets the service field of the given connection, using port_names. If you are using the ftp analyzer, then it knows about FTP data connections and maps them to port_names[20/tcp], i.e., "ftp-data".


full_id_string (c: connection): string
returns a string identifying the connection in one of the two following forms. If the connection is in state S0, S1, or REJ, then no data has been transferred, and the format is:
A_o <state> A_r/<service> <addl>

where A_o is the IP address of the originator ($id$orig_h), state is as given in the Symbol column of the above table. A_r is the IP address of the responder ($id$resp_h), service gives the application service ($service) as set by determine_service, and addl is the contents of the $addl field (which may be an empty string).

Note that the ephemeral port used by the originator is not reported. If you want to display it, use id_string.

So, for example:

              128.3.6.55 > 131.243.88.10/telnet "luser"
     

identifies a connection originated by 128.3.6.55 to 131.243.88.10's Telnet server, for which the additional associated information is "luser", the username successfully used during the authentication dialog as determined by the analyzer. From the table above we see that the connection must be in state S1, as that's the only state of S0, S1, or REJ that has a > symbol. (We can tell it's not in state SF because the format used for that state differs—see below.)

For connections in other states, Bro has size and duration information available, and the format returned by full_id_string is:

A_o S_ob <state> A_r/<service> S_rb D_s <addl>

where A_o, A_r, state, service, and addl are as before, S_o and S_r give the number of bytes transmitted so far by the originator to the responder and vice versa, and D gives the duration of the connection in seconds (reported with one decimal place) so far.

An example of this second format is:

              128.3.6.55 63b > 131.243.88.10/telnet 391b 39.1s "luser"
     

which reflects the same connection as before, but now 128.3.6.55 has transmitted 63 bytes to 131.243.88.10, which has transmitted 391 bytes in response, and the connection has been active for 39.1 seconds. The “>” indicates that the connection is in state SF.


id_string (id: conn_id): string
returns a string identifying the connection by its address/port quadruple. Regardless of the connection's state, the format is:
A_o/P_o > A_r/P_r
where A_o and A_r are the originator and responder addresses, respectively, and P_o and P_r are representations of the originator and responder ports as returned by the port-name module, i.e., either or a string like “http” for a well-known port such as 80/tcp.

An example:

              128.3.6.55/2244 > 131.243.88.10/telnet
     

Note, id_string is implemented using a pair of calls to endpoint_id.

Deficiency:It would be convenient to have a form of id_string that can incorporate a notion of directionality, for example 128.3.6.55/2244 < 131.243.88.10/telnet to indicate the same connection as before, but referring specifically to the flow from responder to originator in that connection (indicated by using “<” instead of “>”).


log_hot_conn (c: connection)
logs a real-time alert of the form:
hot: <connection-id>
where connection-id is the format returned by full_id_string. log_hot_conn keeps track of which connections it has logged and will not log the same connection more than once.


record_connection (c: connection, disposition: string)
Generates a connection summary to the red file in the format described in Connection summaries. If the connection's hot field is positive, then also logs the connection using log_hot_conn. The disposition is a text description of the connection's state, such as "attempt" or "half_finished"; it is not presently used.


service_name (c: connection): string
returns a string describing the service associated with the connection, computed as follows. If the responder port ($id$resp_p), p, is well-known, that is, in the port_names table, then p's entry in the table is returned (such as "http" for TCP port 80). Otherwise, for TCP connections, if the responder port is less than 1024, then priv-p is returned, otherwise other-p. For UDP connections, the corresponding service names are upriv-p and uother-p.


terminate_connection (c: connection)
Attempts to terminate the given connection using the rst utility in the current directory. It does not check to see whether the utility is actually present, so an unaesthetic shell error will appear if the utility is not available.

rst terminates connections by forging RST packets. It is not presently distributed with Bro, due to its potential for disruptive use.

If Bro is reading a trace file rather than live network traffic, then terminate_connection logs the rst invocation but does not actually invoke the utility. In either case, it finishes by logging that the connection is being terminated.