7.21.3 portmapper event handlers

The standard script handles the following events:

pm_request_null (r: connection)

Invoked upon a successful portmapper request for the “null” procedure. The script invokes pm_request with log_it=F.

pm_request_set (r: connection, m: pm_mapping, success: bool)

Invoked upon a nominally successful portmapper request to set the portmapper binding m. The script invokes pm_request with log_it=T. success is true if the server honored the request, false otherwise; the script turns this into an annotation of "ok" or "failed".

The pm_mapping type (for m) has three fields, program: count, version: count and p: port, the port for the mapping of the given program and version. pm_mapping

pm_request_unset (r: connection, m: pm_mapping, success: bool)

Invoked upon a nominally successful portmapper request to remove a portmapper binding. The script invokes pm_request with log_it=T. success is true if the server honored the request, false otherwise; the script turns this into an annotation of "ok" or "failed".

pm_request_getport (r: connection, pr: pm_port_request, p: port)

Invoked upon a successful portmapper request to look up a portmapper binding. pr, of type pm_port_request, has three fields: program: count, version: count, and is_tcp: bool, this last indicating whether the caller is request the TCP or UDP port, if the given program/version has mappings for both. The script invokes pm_request with log_it set according to the return value of and an annotation of the mapping.

pm_request_dump (r: connection, m: pm_mappings)

Invoked upon a successful portmapper request to dump the portmapper bindings. The script invokes pm_request with log_it=T unless indicates that the dump call is allowed. The script ignores m, which gives the mappings as a table[count] of pm_mapping, where the table index simply reflects the order in which the mappings were returned, starting with an index of 1. Deficiency: What the script should do, instead, is keep track of the mappings so that Bro can identify the service associated with connections for otherwise unknown ports.

pm_request_callit (r: connection, pm_callit_request, p: port)

Invoked upon a successful portmapper request to look up and call an RPC procedure. The script invokes pm_request with log_it=T unless the combination of the caller and the program are in suppress_pm_log. Finally, if the program called is walld, then the script adds the caller to suppress_pm_log.

The pm_callit_request type has four fields: pm_callit_request program: count, version: count, proc: count, and arg_size: count. These reflect the procedure being looked up and called, and the size of the arguments being passed to it, respectively. Deficiency: Currently, the event engine does not do any analysis or refinement of the arguments passed to the procedure (such as making them available to the event handler) or the return value. p is the port value returned by the call.

pm_attempt_null (r: connection, status: count)

Invoked upon a failed portmapper request for the “null” procedure. status gives the reason for the failure. The script invokes pm_attempt with log_it=T.

pm_attempt_set (r: connection, status: count, m: pm_mapping)

Invoked upon a failed portmapper request to set the portmapper binding m. The script invokes pm_attempt with log_it=T.

pm_attempt_unset (r: connection, status: count, m: pm_mapping)

Invoked upon a failed portmapper request to remove a portmapper binding. The script invokes pm_attempt with log_it=T.

pm_attempt_getport (r: connection, status: count, pr: pm_port_request)

Invoked upon a failed portmapper request to look up a portmapper binding. pr, of type pm_port_request, has three fields: program: count, version: count, and is_tcp: bool, this last indicating whether the caller requested the TCP or UDP port. The script invokes pm_attempt with log_it set according to the return value of pm_check_get_port.

pm_attempt_dump (r: connection, status: count)

Invoked upon a failed portmapper request to dump the portmapper bindings. The script invokes pm_attempt with log_it=T unless RPC_dump_okay indicates that the dump call is allowed.

pm_attempt_callit (r: connection, status: count, pm_callit_request)

Invoked upon a failed portmapper request to look up and call an RPC procedure. The script invokes pm_attempt with log_it=T unless the combination of the caller and the program are in suppress_pm_log. Finally, if the program called is walld, then the script adds the caller to suppress_pm_log.

pm_bad_port (r: connection, bad_p: count)

Invoked when a portmapper request or response includes an invalid port number. Since ports are represented by unsigned 4-byte integers, they can stray outside the allowed range of 0–65535 by being >= 65536. The script invokes conn_weird_log with a weird tag of "bad_pm_port".