Next: , Previous: portmapper variables, Up: portmapper Analyzer



7.20.2 portmapper functions

The standard script provides the following externally accessible functions:

rpc_prog (p: count): string
Returns the name of the RPC program with the given number, if it's present in ; otherwise returns the text "unknown-<p>".
pm_check_getport (r: connection, prog: string): bool
Checks a GETPORT request for the given program against the policy expressed by RPC_okay_services, any_RPC_okay, RPC_okay, and RPC_okay_nets, returning true if the request violates policy, false if it's allowed.
pm_activity (r: connection, log_it: bool)
A bookkeeping function invoked when there's been portmapper activity on the given connection.

The function records the connection via , unless it is a TCP connection (which will instead be recorded by connection_finished). If log_it is true then the function generates a real-time alert of the form:

rpc: <connection-id> <RPC-service> <r$addl>
For example:
              972616255.679799 rpc: 65.174.102.21/832 >
          	182.7.9.47/portmapper pm_getport: nfs -> 2049/udp
     

However, it does not generate the alert if either the client host and service are present in suppress_pm_log, or if it already generated an alert in the past for the same client, server and service (to prevent alert cascades).

pm_request (r: connection, proc: string, addl: string, log_it: bool)
Invoked when the given connection has made a portmapper request of some sort for the given RPC procedure proc. addl gives an annotation to add to the connection's addl field. If log_it is true, then connection should be logged; it will also be logged if the function determines that it is hot.

The function first invokes check_scan and scan_hot (with a mode of CONN_ESTABLISHED), unless r is a TCP connection, in which case these checks have already been made by connection_established. The function then adds addl to the connection's addl field, though if the field's length already exceeds 80 bytes, then it just tacks on "..." (unless already present). This last is necessary because Bro will sometimes see zillions of successive portmapper requests that all use the same connection ID, and these will each add to addl until it becomes unwieldy in size. Deficiency: Clearly, the byte limit of 80 should be adjustable.

Finally, the function invokes check_hot with a mode of CONN_FINISHED, and pm_activity to finish up bookkeeping for the connection.

No return value.

pm_attempt (r: connection, proc: string, status: count, addl: string, log_it: bool)
Invoked when the given connection attempted to make a portmapper request of some sort, but the request failed or went unanswered. The arguments are the same as for pm_request, with the addition of status, which gives the RPC status code corresponding to why the attempt failed (see below).

The function first invokes check_scan and check_hot (with a mode of CONN_ATTEMPTED), unless r is a TCP connection, in which case these checks have already been made by connection_attempt.

The function then adds addl to the connection's addl field, along with a text description of the RPC status code, as given in the Table below.

No return value.

Status description Meaning
"ok" The call succeeded.
"prog unavail" The call was for an RPC program that has not registered with the portmapper.
"mismatch" The call was for a version of the RPC program that has not registered with the portmapper.
"garbage args" The parameters in the call did not decode correctly.
"system err" A system error (such as out-of-memory) occurred when processing the call.
"timeout" No reply was received within 24 seconds of the request.
"auth error" The caller failed to authenticate to the server, or was not authorized to make the call.
"unknown" An unknown error occurred.

Table 7.6: Types of RPC status codes