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:

status true on success, false on failure
data string containing the raw response

ChkProgram (self)

Checks if the rpc program is supported

Parameters

self

Return values:

status boolean true on success, false on failure
string containing error message (if status is false)

ChkVersion (self)

Checks if the rpc program version is supported

Parameters

self

Return values:

status boolean true on success, false on failure
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:

status boolean true on success, false on failure
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:

status boolean true on success, false on failure
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:

pos number containing the offset after the decoding
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:

status true on success, false on failure
table of file table entries as described in decodeReadDir

Disconnect (self)

Disconnects from the remote program

Parameters

self

Return values:

status boolean true on success, false on failure
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:

status boolean true on success, false on failure
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:

status success or failure
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:

status true on success, false on failure
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:

status success or failure
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:

status true on success, false on failure
attribs table with the fields type, mode, nlink, uid, gid, size, blocksize, rdev, blocks, fsid, fileid, atime, mtime and ctime
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:

pos number containing the offset after decoding
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:

status true on success, false on failure
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:

status true on success, false on failure
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:

status true on success, false on failure
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:

status success or failure
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:

on success a Comm object which can be used later as a parameter by low level Mount functions, on failure returns nil.
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:

true on success or nil on failure
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:

on success a Comm object which can be used later as a parameter by low level NFS functions, on failure returns nil.
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:

status true on success, false on failure
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:

pos number containing the offset after the decoding
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:

status true on success, false on failure
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:

status true on success, false on failure
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:

status true on success, false on failure
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:

status true on success, false on failure
statfs table with the fields transfer_size, block_size, total_blocks, free_blocks and available_blocks
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:

pos number containing the offset after decoding
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:

pos The new position
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:

pos The new position
uint64 The decoded fileid

unmarshall_nfstime (data, pos)

Unmarshall NFS time

Parameters

data: The data being processed.
pos: The position within data

Return values:

pos The new position
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:

status success or failure
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:

true on success or nil on failure
error message on failure

Library rpc

Script Arguments

Functions

Functions

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return value:

Parameters

Return values:

Parameters

Return values:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return value:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return value:

Parameters

Return values:

Parameters

Return values:

Parameters

Return value:

Parameters

Return value:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Library `rpc`