Library rpc

RPC Library supporting a very limited subset of operations.

The library works over both the UDP and TCP protocols. A subset of nfs and mountd procedures are supported. The nfs and mountd programs support versions 1 through 3. Authentication is supported using the NULL RPC Authentication protocol

The library contains the following classes:

  • Comm
** Handles network connections. ** Handles low-level packet sending, receiving, decoding and encoding. ** Stores rpc programs info: socket, protocol, program name, id and version. ** Used by Mount, NFS, RPC and Portmap.
  • Portmap
** Contains RPC constants. ** Handles communication with the portmap RPC program.
  • Mount
** Handles communication with the mount RPC program.
  • NFS
** Handles communication with the nfs RPC program.
  • Helper
** Provides easy access to common RPC functions. ** Implemented as a static class where most functions accept host and port parameters.
  • Util
** Mostly static conversion routines.

The portmapper dynamically allocates TCP/UDP ports to RPC programs. So in in order to request a list of NFS shares from the server we need to:

  • Make sure that we can talk to the portmapper on port 111 TCP or UDP.
  • Query the portmapper for the ports allocated to the NFS program.
  • Query the NFS program for a list of shares on the ports returned by the portmap program.

The Helper class contains functions that facilitate access to common RPC program procedures through static class methods. Most functions accept host and port parameters. As the Helper functions query the portmapper to get the correct RPC program port, the port supplied to these functions should be the rpcbind port 111/tcp or 111/udp.

The following sample code illustrates how scripts can use the Helper class to interface the library:

-- retrieve a list of NFS export
status, mounts = rpc.Helper.ShowMounts( host, port )

-- iterate over every share
for _, mount in ipairs( mounts ) do

   -- get the NFS attributes for the share
   status, attribs = rpc.Helper.GetAttributes( host, port, mount.name )
   .... process NFS attributes here ....
end

RPC transaction IDs (XID) are not properly implemented as a random ID is generated for each client call. The library makes no attempt to verify whether the returned XID is valid or not.

Therefore TCP is the preferred method of communication and the library always attempts to connect to the TCP port of the RPC program first. This behaviour can be overridden by setting the rpc.protocol argument. The portmap service is always queried over the protocol specified in the port information used to call the Helper function from the script.

When multiple versions exists for a specific RPC program the library always attempts to connect using the highest available version.

Author:

  • Patrik Karlsson <patrik@cqure.net>

Copyright © Same as Nmap--See https://nmap.org/book/man-legal.html

Source: https://svn.nmap.org/nmap/nselib/rpc.lua

Script Arguments

mount.version

number If set overrides the detected version of mountd

rpc.protocol

table If set overrides the preferred order in which protocols are tested. (ie. "tcp", "udp")

nfs.version

number If set overrides the detected version of nfs

Functions

calc_fsinfo_table (fsinfo, nfsversion, human)

Calculate and return the fsinfo filesystem table

calc_fsstat_table (stats, nfsversion, human)

Calculate and return the fsstat filesystem table

calc_pathconf_table (pconf, nfsversion)

Return the pathconf filesystem table

Callit (self, comm, program, protocol, version)

Calls the portmap callit call and returns the raw response

ChkProgram (self)

Checks if the rpc program is supported

ChkVersion (self)

Checks if the rpc program version is supported

Connect (self, host, port, timeout)

Connects to the remote program

CreateHeader (self, xid, procedure, auth)

Creates a RPC header

DecodeHeader (self, data, pos)

Decodes the RPC header (without the leading 4 bytes as received over TCP)

Dir (host, port, path)

Retrieves a list of files from the NFS export

Disconnect (self)

Disconnects from the remote program

Dump (self, comm)

Dumps a list of RCP programs from the portmapper

EncodePacket (self, xid, proc, auth, data)

Encodes a RPC packet

Export (self, comm)

Requests a list of NFS export from the remote server

ExportStats (host, port, path)

Retrieves NFS storage statistics

FmodeToOctalString (mode)

Converts a numeric ACL mode to a string in an octal number format.

format_nfsfattr (attr, mactime)

Converts the NFS file attributes to a string.

FpermToString (mode)

Converts a numeric ACL to its character equivalent eg. (rwxr-xr-x)

FtypeToChar (mode)

Converts a numeric ACL mode to a file type char

FtypeToString (mode)

Converts a numeric ACL mode to a file type string

GetAdditionalBytes (self, data, pos, needed)

Checks if data contains enough bytes to read the needed amount

GetAttr (self, comm, file_handle)

Gets mount attributes (uid, gid, mode, etc ..) from a remote NFS share

GetAttrDecode (self, comm, data, pos)

Attempts to decode the attributes section of the reply

GetAttributes (host, port, path)

Retrieves NFS Attributes

GetPort (self, comm, program, protocol, version)

Queries the portmapper for the port of the selected program, protocol and version

GetPortForProgram (host, port, program, protocol)

Queries the portmapper for a port for the specified RPC program

GetProgramInfo (host, port, program, max_version)

Get RPC program information

Mount (self, comm, path)

Attempts to mount a remote export in order to get the filehandle

MountPath (host, port, path)

Mounts a remote NFS export and returns the file handle

new (self, program, version)

Creates a new rpc Comm object

NfsClose (nfs_comm)

Closes the NFS connection

NfsOpen (host, port)

Connects to a remote NFS server

ProgNameToNumber (prog_name)

Converts a RPC program name to its equivalent number

ProgNumberToName (num)

Converts the RPC program number to its equivalent name

ReadDir (self, comm, file_handle)

Reads the contents inside a NFS directory

ReadDirDecode (self, comm, data, pos)

Decodes the READDIR section of a NFS ReadDir response

ReceivePacket (self)

Reads the response from the socket

RpcInfo (host, port)

Queries the portmapper for a list of programs

SetCheckProgVer (self, check)

Sets the verification of the specified program and version support before trying to connecting.

SetProgID (self, progid)

Sets the RPC program ID to use.

SetVersion (self, version)

Sets the rpc program version

ShowMounts (host, port)

Lists the NFS exports on the remote host This function abstracts the RPC communication with the portmapper from the user

SizeToHuman (size, blocksize)

Converts the size in bytes to a human readable format

StatFs (self, comm, file_handle)

Gets filesystem stats (Total Blocks, Free Blocks and Available block) on a remote NFS share

StatFsDecode (self, comm, data, pos)

Attempts to decode the StatFS section of the reply

unmarshall_nfsattr (data, pos, nfsversion, number)

Unmarshall NFS file attributes

unmarshall_nfsfileid3 (data, pos)

Unmarshall NFSv3 fileid field of the NFS attributes

unmarshall_nfstime (data, pos)

Unmarshall NFS time

Unmount (self, comm, path)

Attempts to unmount a remote export in order to get the filehandle

UnmountPath (mnt_comm, path)

Unmounts a remote mounted NFS export

Functions

calc_fsinfo_table (fsinfo, nfsversion, human)

Calculate and return the fsinfo filesystem table

Parameters

fsinfo
table returned by the NFSv3 FSINFO call
nfsversion
the version of the remote NFS server
human
if set show the size in the human readable format.

Return value:

fs table that contains the remote filesystem information.
calc_fsstat_table (stats, nfsversion, human)

Calculate and return the fsstat filesystem table

Parameters

stats
table returned by the NFSv3 FSSTAT or NFSv2 STATFS calls
nfsversion
the version of the remote NFS server
human
if set show the size in the human readable format.

Return value:

df table that contains the remote filesystem attributes.
calc_pathconf_table (pconf, nfsversion)

Return the pathconf filesystem table

Parameters

pconf
table returned by the NFSv3 PATHCONF call
nfsversion
the version of the remote NFS server

Return value:

fs table that contains the remote filesystem pathconf information.
Callit (self, comm, program, protocol, version)

Calls the portmap callit call and returns the raw response

Parameters

self
 
comm
object handles rpc program information and low-level packet manipulation
program
string name of the program
protocol
string containing either "tcp" or "udp"
version
number containing the version of the queried program

Return values:

  1. status true on success, false on failure
  2. data string containing the raw response
ChkProgram (self)

Checks if the rpc program is supported

Parameters

self
 

Return values:

  1. status boolean true on success, false on failure
  2. string containing error message (if status is false)
ChkVersion (self)

Checks if the rpc program version is supported

Parameters

self
 

Return values:

  1. status boolean true on success, false on failure
  2. string containing error message (if status is false)
Connect (self, host, port, timeout)

Connects to the remote program

Parameters

self
 
host
table
port
table
timeout
[optional] socket timeout in ms

Return values:

  1. status boolean true on success, false on failure
  2. string containing error message (if status is false)
CreateHeader (self, xid, procedure, auth)

Creates a RPC header

Parameters

self
 
xid
number. If no xid was provided, a random one will be used.
procedure
number containing the procedure to call. Defaults to 0.
auth
table containing the authentication data to use. Defaults to NULL authentication.

Return values:

  1. status boolean true on success, false on failure
  2. string of bytes on success, error message on failure
DecodeHeader (self, data, pos)

Decodes the RPC header (without the leading 4 bytes as received over TCP)

Parameters

self
 
data
string containing the buffer of bytes read so far
pos
number containing the current offset into data

Return values:

  1. pos number containing the offset after the decoding
  2. header table containing xid, type, state, verifier and ( accept_state or denied_state )
Dir (host, port, path)

Retrieves a list of files from the NFS export

Parameters

host
table
port
table
path
string containing the nfs export path

Return values:

  1. status true on success, false on failure
  2. table of file table entries as described in decodeReadDir
Disconnect (self)

Disconnects from the remote program

Parameters

self
 

Return values:

  1. status boolean true on success, false on failure
  2. string containing error message (if status is false)
Dump (self, comm)

Dumps a list of RCP programs from the portmapper

Parameters

self
 
comm
object handles rpc program information and low-level packet manipulation

Return values:

  1. status boolean true on success, false on failure
  2. result table containing RPC program information or error message on failure. The table has the following format:
    table[program_id][protocol]["port"] = <port number>
    table[program_id][protocol]["version"] = <table of versions>
    table[program_id][protocol]["addr"] = <IP address, for RPCv3 and higher>
    Where o program_id is the number associated with the program o protocol is one of "tcp", "udp", "tcp6", or "udp6", or another netid reported by the system.
EncodePacket (self, xid, proc, auth, data)

Encodes a RPC packet

Parameters

self
 
xid
number containing the transaction ID
proc
number containing the procedure to call
auth
table containing authentication information
data
string containing the packet data

Return value:

packet string containing the encoded packet data
Export (self, comm)

Requests a list of NFS export from the remote server

Parameters

self
 
comm
object handles rpc program information and low-level packet manipulation

Return values:

  1. status success or failure
  2. entries table containing a list of share names (strings)
ExportStats (host, port, path)

Retrieves NFS storage statistics

Parameters

host
table
port
table
path
string containing the nfs export path

Return values:

  1. status true on success, false on failure
  2. statfs table with the fields transfer_size, block_size, total_blocks, free_blocks and available_blocks
FmodeToOctalString (mode)

Converts a numeric ACL mode to a string in an octal number format.

Parameters

mode
number containing the ACL mode

Return value:

string containing the octal ACL mode
format_nfsfattr (attr, mactime)

Converts the NFS file attributes to a string.

An optional second argument is the mactime to use

Parameters

attr
table returned by NFS GETATTR or ACCESS
mactime
to use, the default value is mtime Possible values: mtime, atime, ctime

Return value:

string containing the file attributes
FpermToString (mode)

Converts a numeric ACL to its character equivalent eg. (rwxr-xr-x)

Parameters

mode
number containing the ACL mode

Return value:

string containing the ACL characters
FtypeToChar (mode)

Converts a numeric ACL mode to a file type char

Parameters

mode
number containing the ACL mode

Return value:

char containing the file type
FtypeToString (mode)

Converts a numeric ACL mode to a file type string

Parameters

mode
number containing the ACL mode

Return value:

string containing the file type name
GetAdditionalBytes (self, data, pos, needed)

Checks if data contains enough bytes to read the needed amount

If it doesn't it attempts to read the remaining amount of bytes from the socket. Unlike socket.receive_bytes, reading less than needed is treated as an error.

Parameters

self
 
data
string containing the current buffer
pos
number containing the current offset into the buffer
needed
number containing the number of bytes needed to be available

Return values:

  1. status success or failure
  2. data string containing the data passed to the function and the additional data appended to it or error message on failure
GetAttr (self, comm, file_handle)

Gets mount attributes (uid, gid, mode, etc ..) from a remote NFS share

Parameters

self
 
comm
object handles rpc program information and low-level packet manipulation
file_handle
string containing the filehandle to query

Return values:

  1. status true on success, false on failure
  2. attribs table with the fields type, mode, nlink, uid, gid, size, blocksize, rdev, blocks, fsid, fileid, atime, mtime and ctime
  3. errormsg if status is false
GetAttrDecode (self, comm, data, pos)

Attempts to decode the attributes section of the reply

Parameters

self
 
comm
object handles rpc program information and low-level packet manipulation
data
string containing the full statfs reply
pos
number pointing to the statfs section of the reply

Return values:

  1. pos number containing the offset after decoding
  2. statfs table with the following fields: type, mode, nlink, uid, gid, size, blocksize, rdev, blocks, fsid, fileid, atime, mtime and ctime
GetAttributes (host, port, path)

Retrieves NFS Attributes

Parameters

host
table
port
table
path
string containing the nfs export path

Return values:

  1. status true on success, false on failure
  2. statfs table with the fields transfer_size, block_size, total_blocks, free_blocks and available_blocks
GetPort (self, comm, program, protocol, version)

Queries the portmapper for the port of the selected program, protocol and version

Parameters

self
 
comm
object handles rpc program information and low-level packet manipulation
program
string name of the program
protocol
string containing either "tcp" or "udp"
version
number containing the version of the queried program

Return value:

number containing the port number
GetPortForProgram (host, port, program, protocol)

Queries the portmapper for a port for the specified RPC program

Parameters

host
table
port
table
program
string containing the RPC program name
protocol
string containing either "tcp" or "udp"

Return values:

  1. status true on success, false on failure
  2. table containing the portmapper information as returned by Portmap.Dump
GetProgramInfo (host, port, program, max_version)

Get RPC program information

Parameters

host
table
port
table
program
string containing the RPC program name
max_version
(optional) number containing highest version to retrieve

Return values:

  1. status true on success, false on failure
  2. info table containing port, port.number port.protocol and version
Mount (self, comm, path)

Attempts to mount a remote export in order to get the filehandle

Parameters

self
 
comm
object handles rpc program information and low-level packet manipulation
path
string containing the path to mount

Return values:

  1. status success or failure
  2. fhandle string containing the filehandle of the remote export
MountPath (host, port, path)

Mounts a remote NFS export and returns the file handle

This is a high level function to be used by NSE scripts To close the mounted NFS export use UnmountPath() function

Parameters

host
table
port
table
path
string containing the path to mount

Return values:

  1. on success a Comm object which can be used later as a parameter by low level Mount functions, on failure returns nil.
  2. on success the filehandle of the NFS export as a string, on failure returns the error message.
new (self, program, version)

Creates a new rpc Comm object

Parameters

self
 
program
name string
version
number containing the program version to use

Return value:

a new Comm object
NfsClose (nfs_comm)

Closes the NFS connection

This is a high level function to close NFS connections This function must be used to close the NFS connection opened by the NfsOpen() call

Parameters

nfs_comm
object returned by NfsOpen()

Return values:

  1. true on success or nil on failure
  2. error message on failure
NfsOpen (host, port)

Connects to a remote NFS server

This is a high level function to open NFS connections To close the NFS connection use NfsClose() function

Parameters

host
table
port
table

Return values:

  1. on success a Comm object which can be used later as a parameter by low level NFS functions, on failure returns nil.
  2. error message on failure.
ProgNameToNumber (prog_name)

Converts a RPC program name to its equivalent number

Parameters

prog_name
string containing the name of the RPC program

Return value:

num number containing the program ID
ProgNumberToName (num)

Converts the RPC program number to its equivalent name

Parameters

num
number containing the RPC program identifier

Return value:

string containing the RPC program name
ReadDir (self, comm, file_handle)

Reads the contents inside a NFS directory

Parameters

self
 
comm
object handles rpc program information and low-level packet manipulation
file_handle
string containing the filehandle to query

Return values:

  1. status true on success, false on failure
  2. table of file table entries as described in decodeReadDir
ReadDirDecode (self, comm, data, pos)

Decodes the READDIR section of a NFS ReadDir response

Parameters

self
 
comm
object handles rpc program information and low-level packet manipulation
data
string containing the buffer of bytes read so far
pos
number containing the current offset into data

Return values:

  1. pos number containing the offset after the decoding
  2. entries table containing two table entries attributes and entries. The attributes entry is only present when using NFS version 3. The entries field contain one table for each file/directory entry. It has the following fields file_id, name and cookie
ReceivePacket (self)

Reads the response from the socket

Parameters

self
 

Return values:

  1. status true on success, false on failure
  2. data string containing the raw response or error message on failure
RpcInfo (host, port)

Queries the portmapper for a list of programs

Parameters

host
table
port
table

Return values:

  1. status true on success, false on failure
  2. table containing the portmapper information as returned by Portmap.Dump
SetCheckProgVer (self, check)

Sets the verification of the specified program and version support before trying to connecting.

Parameters

self
 
check
boolean to enable or disable checking of program and version support.
SetProgID (self, progid)

Sets the RPC program ID to use.

Parameters

self
 
progid
number Program ID to set.
SetVersion (self, version)

Sets the rpc program version

Parameters

self
 
version
 

Return value:

status boolean true
ShowMounts (host, port)

Lists the NFS exports on the remote host This function abstracts the RPC communication with the portmapper from the user

Parameters

host
table
port
table

Return values:

  1. status true on success, false on failure
  2. result table of string entries or error message on failure
SizeToHuman (size, blocksize)

Converts the size in bytes to a human readable format

An optional second argument is the size of a block

Parameters

size
in bytes
blocksize
represents the number of bytes per block Possible values are: 1024 or 1000 Default value is: 1024

Usage:

size_tohuman(1024) --> 1024.0B
size_tohuman(926548776) --> 883.6M
size_tohuman(246548, 1024) --> 240.8K
size_tohuman(246548, 1000) --> 246.5K

Return value:

string containing the size in the human readable format
StatFs (self, comm, file_handle)

Gets filesystem stats (Total Blocks, Free Blocks and Available block) on a remote NFS share

Parameters

self
 
comm
object handles rpc program information and low-level packet manipulation
file_handle
string containing the filehandle to query

Return values:

  1. status true on success, false on failure
  2. statfs table with the fields transfer_size, block_size, total_blocks, free_blocks and available_blocks
  3. errormsg if status is false
StatFsDecode (self, comm, data, pos)

Attempts to decode the StatFS section of the reply

Parameters

self
 
comm
object handles rpc program information and low-level packet manipulation
data
string containing the full statfs reply
pos
number pointing to the statfs section of the reply

Return values:

  1. pos number containing the offset after decoding
  2. statfs table with the following fields: transfer_size, block_size, total_blocks, free_blocks and available_blocks
unmarshall_nfsattr (data, pos, nfsversion, number)

Unmarshall NFS file attributes

Parameters

data
The data being processed.
pos
The position within data
nfsversion
 
number
The NFS version.

Return values:

  1. pos The new position
  2. table The decoded file attributes table.
unmarshall_nfsfileid3 (data, pos)

Unmarshall NFSv3 fileid field of the NFS attributes

Parameters

data
The data being processed.
pos
The position within data

Return values:

  1. pos The new position
  2. uint64 The decoded fileid
unmarshall_nfstime (data, pos)

Unmarshall NFS time

Parameters

data
The data being processed.
pos
The position within data

Return values:

  1. pos The new position
  2. table The decoded NFS time table.
Unmount (self, comm, path)

Attempts to unmount a remote export in order to get the filehandle

Parameters

self
 
comm
object handles rpc program information and low-level packet manipulation
path
string containing the path to mount

Return values:

  1. status success or failure
  2. error string containing error if status is false
UnmountPath (mnt_comm, path)

Unmounts a remote mounted NFS export

This is a high level function to be used by NSE scripts This function must be used to unmount a NFS point mounted by MountPath()

Parameters

mnt_comm
object returned from a previous call to MountPath()
path
string containing the path to unmount

Return values:

  1. true on success or nil on failure
  2. error message on failure