Library `msrpc`

By making heavy use of the smb library, this library will call various MSRPC functions. The functions used here can be accessed over TCP ports 445 and 139, with an established session. A NULL session (the default) will work for some functions and operating systems (or configurations), but not for others.

To make use of these function calls, a SMB session with the server has to be established. This can be done manually with the smb library, or the function start_smb can be called. A session has to be created, then the IPC$ tree opened.

Next, the interface has to be bound. The bind() function will take care of that.

After that, you're free to call any function that's part of that interface. In other words, if you bind to the SAMR interface, you can only call the samr_ functions, for lsa_ functions, bind to the LSA interface, etc. Although functions can technically be called in any order, many functions depend on the value returned by other functions. I indicate those in the function comments, so keep an eye out. SAMR functions, for example, require a call to connect4.

Something to note is that these functions, for the most part, return a whole ton of stuff in a table; basically, everything that is returned by the function. Generally, if you want to know exactly what you have access to, either display the returned data with a print_table-type function, or check the documentation (Samba 4.0's .idl files (in samba_4.0/source/librpc/idl; see below for link) are what I based the names on).

The parameters for each function are converted to a string of bytes in a process called "marshalling". Functions here take arguments that match what a user would logically want to send. These are marshalled by using functions in the msrpctypes module. Those functions require a table of values that isn't very use friendly; as such, it's generated, when possible, in the functions in this module. The value returned, on the other hand, is returned directly to the user; I don't want to limit what data they can use, and it's difficult to rely on servers to format it consistently (sometimes a null is returned, and other times an empty array or blank string), so I put the onus on the scripts to deal with the returned values.

When implementing this, I used Wireshark's output significantly, as well as Samba's .idl files for reference: http://websvn.samba.org/cgi-bin/viewcvs.cgi/branches/SAMBA_4_0/source/librpc/idl/. I'm not a lawyer, but I don't expect that this is a breach of Samba's copyright -- if it is, please talk to me and I'll make arrangements to re-license this or to remove references to Samba.

Revised 07/25/2012 - added Printer Spooler Service (spoolss) RPC functions and constants [Aleksandar Nikolic]

Author:

Ron Bowes <ron@skullsecurity.net>

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

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

Functions

atsvc_jobadd (smbstate, server, command, time): Calls the function JobAdd, which schedules a process to be run on the remote machine.
bind (smbstate, interface_uuid, interface_version, transfer_syntax): Bind to a MSRPC interface.
call_function (smbstate, opnum, arguments): Call a MSRPC function on the remote server, with the given opnum and arguments.
call_lanmanapi (smbstate, opnum, paramdesc, datadesc, data): LANMAN API calls use different conventions than everything else, so make a separate function for them.
DNSSERVER_Query (smbstate, server_name, zone, operation): Issues type specific information queries to server. This method is obsoleted by R_DnssrvQuery2.
enum_shares (host): Attempts to enumerate the shares on a remote system using MSRPC calls. Without a user account, this will likely fail against a modern system, but will succeed against Windows 2000.
epmapper_lookup (smbstate, handle): Lookup endpoint mapper for endpoints
get_pad (data, align, pad_byte): Makes a pad for alignment
get_server_stats (host): Retrieves statistical information about the given server.
get_share_info (host, name): Attempts to retrieve additional information about a share. Will fail unless we have administrative access.
get_user_list (host): Gets the best possible list of user accounts on the remote system using every available method.
lsa_close (smbstate, handle): Call the close function, which closes a session created with a lsa_openpolicy-style function
lsa_enum_users (host): Attempt to enumerate users using LSA functions.
lsa_lookupnames2 (smbstate, policy_handle, names): Call the LsarLookupNames2 function, to convert the server's name into a sid.
lsa_lookupsids2 (smbstate, policy_handle, sids): Call the LsarLookupSids2 function, to convert a list of SIDs to their names
lsa_openpolicy2 (smbstate, server): Call the LsarOpenPolicy2 function, to obtain a "policy handle". This must be done before calling many of the LSA functions.
lsa_SidType_tostr (val): A proxy to a msrpctypes function that converts a SidType to an English string.
rap_netserverenum2 (smbstate, domain, server_type, detail_level): Queries the (master) browser service for a list of server that it manages
RRAS_marshall_RequestBuffer (RB_PCBIndex, RB_ReqType, RB_Buffer): The RequestBuffer is a generic information container used by the RasRpcSubmitRequest method to set or retrieve information on RRAS server. This method performs serialization of RequestBuffer structure. Note: This structure is not an IDL specification and as such is not translated into NDR.
RRAS_SubmitRequest (smbstate, pReqBuffer, dwcbBufSize): The RasRpcSubmitRequest method retrieves or sets the configuration data on RRAS server.
samr_AcctFlags_tostr (val): A proxy to a msrpctypes function that converts a AcctFlags to an English string.
samr_close (smbstate, handle): Call the close function, which closes a handle of any type (for example, domain_handle or connect_handle)
samr_connect4 (smbstate, server): Call the connect4 function, to obtain a "connect handle".
samr_enum_users (host): Attempt to enumerate users using SAMR functions.
samr_enumdomainaliases (smbstate, domain_handle): Call the EnumDomainAliases function, which retrieves a list of groups for a given domain
samr_enumdomains (smbstate, connect_handle): Call the enumdomains function, which returns a list of all domains in use by the system.
samr_enumdomainusers (smbstate, domain_handle): Call EnumDomainUsers, which returns a list of users only. To get more information about the users, the QueryDisplayInfo() function can be used.
samr_getaliasmembership (smbstate, alias_handle, args): Call the GetAliasMembership function. Sends the "raw" data, without marshaling.
samr_getmembersinalias (smbstate, alias_handle): Call the GetMembersInAlias function, which retrieves a list of users in a group.
samr_lookupdomain (smbstate, connect_handle, domain): Call the LookupDomain function, which converts a domain's name into its sid, which is required to do operations on the domain.
samr_lookupnames (smbstate, domain_handle, names): Call the EnumDomainAliases function, which retrieves a list of groups for a given domain
samr_openalias (smbstate, domain_handle, rid): Call the OpenAlias function, which gets a handle to a group.
samr_opendomain (smbstate, connect_handle, sid): Call OpenDomain, which returns a handle to the domain identified by the given sid. This is required before calling certain functions.
samr_PasswordProperties_tostr (val): A proxy to a msrpctypes function that converts a PasswordProperties to an English string.
samr_querydisplayinfo (smbstate, domain_handle, index, count): Call QueryDisplayInfo, which returns a list of users with accounts on the system, as well as extra information about them (their full name and description).
samr_querydomaininfo2 (smbstate, domain_handle, level): Call QueryDomainInfo2, which grabs various data about a domain.
service_create (host, servicename, path): Create a "service" on a remote machine.
service_delete (host, servicename): Delete a service on the remote machine based on its name. I don't recommend deleting any services that you didn't create.
service_start (host, servicename, args): Start a service on the remote machine based on its name. For example, to start the registry service, this can be called on "RemoteRegistry".
service_stop (host, servicename): Stop a service on the remote machine based on its name. For example, to stop the registry service, this can be called on "RemoteRegistry".
spoolss_abort_printer (smbstate, printer_handle): Call the RpcAbortPrinter() function whose opnum is 21.
spoolss_end_doc_printer (smbstate, printer_handle): Call the EndDocPrinter() function whose opnum is 23.
spoolss_open_printer (smbstate, printer): Call the RpcOpenPrinterEx() function whose opnum is 69.
spoolss_start_doc_printer (smbstate, printer_handle, filename): Call the RpcStartDocPrinter() function whose opnum is 17.
spoolss_write_printer (smbstate, printer_handle, data): Call the RpcWritePrinter() function whose opnum is 19.
srvsvc_netpathcanonicalize (smbstate, server, path): Call the NetPathCanonicalize() function, which is the target of ms08-067.
srvsvc_netpathcompare (smbstate, server, path1, path2, pathtype, pathflags): Call the NetPathCompare() function, which indirectly calls NetPathCanonicalize(), the target of ms08-067. I'm currently only using this to trigger ms08-067.
srvsvc_netservergetstatistics (smbstate, server): Calls the NetServerGetStatistics function, which grabs a bunch of statistics on the server. This function requires administrator access to call.
srvsvc_netsessenum (smbstate, server): Call the NetSessEnum function, which gets a list of active sessions on the host. For this function, a session is defined as a connection to a file share.
srvsvc_netshareenumall (smbstate, server): Call the MSRPC function netshareenumall on the remote system.
srvsvc_netsharegetinfo (smbstate, server, share, level): Call the MSRPC function netsharegetinfo on the remote system. This function retrieves extra information about a share on the system.
srvsvc_ShareType_tostr (val): A proxy to a msrpctypes function that converts a ShareType to an English string.
start_smb (host, path, disable_extended, overrides): This is a wrapper around the SMB class, designed to get SMB going quickly for MSRPC calls.
stop_smb (state): A wrapper around the smb.stop function.
string_uuid_to_exe (uuid): Helper function that maps known UUIDs to corresponding exe/services.
svcctl_closeservicehandle (smbstate, handle): Calls the function CloseServiceHandle, which releases a handle.
svcctl_controlservice (smbstate, handle, control): Calls the function ControlService, which can send various commands to the service.
svcctl_createservicew (smbstate, handle, service_name, display_name, path): Calls the function CreateServiceW, which creates a service on the remote machine. This should be deleted with DeleteService when finished.
svcctl_deleteservice (smbstate, handle): Calls the function DeleteService, which deletes a service on the remote machine. This service has to opened with OpenServiceW or similar functions.
svcctl_openscmanagera (smbstate, machinename): Calls the function OpenSCManagerA, which gets a handle to the service manager. Should be closed with CloseServiceHandle when finished.
svcctl_openscmanagerw (smbstate, machinename, access_mask): Calls the function OpenSCManagerW, which gets a handle to the service manager. Should be closed with CloseServiceHandle when finished.
svcctl_openservicew (smbstate, handle, name, access_mask): Calls the function OpenServiceW, which gets a handle to the service. Should be closed with CloseServiceHandle when finished.
svcctl_queryservicestatus (smbstate, handle, control): Calls the function QueryServiceStatus, which gets the state information about the service.
svcctl_startservicew (smbstate, handle, args): Calls the function StartServiceW, which starts a service. Requires a handle created by OpenServiceW.
uuid_to_string (uuid): Helper function to convert binary UUID representation to usual string.
winreg_closekey (smbstate, handle): Calls the function CloseKey, which closes an opened handle. Strictly speaking, this doesn't have to be called (Windows will close the key for you), but it's good manners to clean up after yourself.
winreg_enumkey (smbstate, handle, index, name): Calls the Windows registry function EnumKey, which returns a single key under the given handle, at the index of 'index'.
winreg_openhkcu (smbstate): Call the OpenHKCU function, to obtain a handle to the HKEY_CURRENT_USER hive
winreg_openhklm (smbstate): Call the OpenHKLM function, to obtain a handle to the HKEY_LOCAL_MACHINE hive
winreg_openhkpd (smbstate): Call the OpenHKPD function, to obtain a handle to the hidden HKEY_PERFORMANCE_DATA hive
winreg_openhku (smbstate): Call the OpenHKU function, to obtain a handle to the HKEY_USERS hive
winreg_openkey (smbstate, handle, keyname): Calls the function OpenKey, which obtains a handle to a named key.
winreg_queryinfokey (smbstate, handle): Calls the function QueryInfoKey, which obtains information about an opened key.
winreg_queryvalue (smbstate, handle, value): Calls the function QueryValue, which returns the value of the requested key.

Functions

atsvc_jobadd (smbstate, server, command, time)

Calls the function JobAdd, which schedules a process to be run on the remote machine.

This requires administrator privileges to run, and the command itself runs as SYSTEM.

Parameters

smbstate: The SMB state table.
server: The IP or Hostname of the server (seems to be ignored but it's a good idea to have it)
command: The command to run on the remote machine. The appropriate file(s) already have to be there, and this should be a full path.
time: [optional] The time at which to run the command. Default: 5 seconds from when the user logged in.

bind (smbstate, interface_uuid, interface_version, transfer_syntax)

Bind to a MSRPC interface.

Two common interfaces are SAML and SRVSVC, and can be found as constants at the top of this file. Once this function has successfully returned, any MSRPC call can be made (provided it doesn't depend on results from other MSRPC calls).

Parameters

smbstate: The SMB state table
interface_uuid: The interface to bind to. There are constants defined for these (SAMR_UUID, etc.)
interface_version: The interface version to use. There are constants at the top (SAMR_VERSION, etc.)
transfer_syntax: The transfer syntax to use. I don't really know what this is, but the value was always the same on my tests. You can use the constant at the top (TRANSFER_SYNTAX), or just set this parameter to 'nil'.

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values, none of which are especially useful.

call_function (smbstate, opnum, arguments)

Call a MSRPC function on the remote server, with the given opnum and arguments.

I opted to make this a local function for design reasons -- scripts shouldn't be directly calling a function, if a function I haven't written is needed, it ought to be added to this file.

Anyways, this function takes the opnum and marshalled arguments, and passes it down to the SMB layer. The SMB layer sends out a SMB_COM_TRANSACTION packet, and parses the result. Once the SMB stuff has been stripped off the result, it's passed down here, cleaned up some more, and returned to the caller.

There's a reason that SMB is sometimes considered to be between layer 4 and 7 on the OSI model. :)

Parameters

smbstate: The SMB state table (after bind has been called).
opnum: The operating number (ie, the function). Find this in the MSRPC documentation or with a packet logger.
arguments: The marshalled arguments to pass to the function. Currently, marshalling is all done manually.

Return values:

status true or false
If status is false, result is an error message. Otherwise, result is a table of values, the most useful one being 'arguments', which are the values returned by the server. If the packet is fragmented, the fragments will be reassembled and 'arguments' will represent all the arguments; however, the rest of the result table will represent the most recent fragment.

call_lanmanapi (smbstate, opnum, paramdesc, datadesc, data)

LANMAN API calls use different conventions than everything else, so make a separate function for them.

Parameters

smbstate
opnum
paramdesc
datadesc
data

DNSSERVER_Query (smbstate, server_name, zone, operation)

Issues type specific information queries to server. This method is obsoleted by R_DnssrvQuery2.

Parameters

smbstate

The smb object.

server_name

String that designates a fully qualified domain name of the target server. The server MUST ignore this value.

zone

String that designates the name of the zone to be queried. For operations specific to a particular zone, this field MUST contain the name of the zone. For all other operations, this field MUST be nil.

operation

String that designates the name of the operation to be performed on the server. These are two sets of allowed values for pszOperation:

zone == nil -> see DNSSERVER_ConfInfo table.
zone == "some_zone" -> see DNSSERVER_ZoneInfo table.

Return value:

(status, result)

status == true ->

that indicates the type of result['data']. ** result['data'] - A DNSSRV_RPC_UNION blob that contains a ** result['type_id'] - Integer that on success contains a value of type DNS_RPC_TYPEID data-structure as indicated by result['type_id'].

status == false ->

** result - Is a error message that caused the fuzz.

[MS-DNSP] 3.1.4.2 R_DnssrvQuery (Opnum 1)

####################################################################--

enum_shares (host)

Attempts to enumerate the shares on a remote system using MSRPC calls. Without a user account, this will likely fail against a modern system, but will succeed against Windows 2000.

Parameters

host: The host object.

Return values:

Status (true or false).
List of shares (if status is true) or an an error string (if status is false).

epmapper_lookup (smbstate, handle)

Lookup endpoint mapper for endpoints

Queries the remote endpoint mapper and parses data into a table with following values: *'new_handle' *'annotation' *'uuid' *'exe' *'tcp_port' *'udp_port' *'ip_addr' *'ncalrpc' *'ncacn_np' *'netbios' *'ncacn_http'

Parameters

smbstate: The SMB state table.
handle: Handle to use for query.

Return value:

(status,lookup_result) If status is false, lookup_result contains an error string, otherwise it's a lookup response table.

get_pad (data, align, pad_byte)

Makes a pad for alignment

Parameters

data: Data which needs to be padded for the sake of alignment.
align: Integer representing the alignment boundary.
pad_byte: The value for pad byte.

Return value:

Returns the amount of pad calculated by (align-datalen%align)%align. ####################################################################--

get_server_stats (host)

Retrieves statistical information about the given server.

This function requires administrator privileges to run, and is present on all Windows versions, so it's a useful way to check whether or not an account is administrative.

Parameters

host: The host object

Return values:

status true or false
If status is false, data is an error message; otherwise, data is a table of information about the server.

get_share_info (host, name)

Attempts to retrieve additional information about a share. Will fail unless we have administrative access.

Parameters

host: The host object.
name

Return values:

Status (true or false).
A table of information about the share (if status is true) or an an error string (if status is false).

get_user_list (host)

Gets the best possible list of user accounts on the remote system using every available method.

TODO: Caching, store this in the registry

Parameters

host: The host object.

Return value:

(status, result, names) If status is false, result is an error message; otherwise, result is an array of users indexed by username and names is a sorted array of names.

lsa_close (smbstate, handle)

Call the close function, which closes a session created with a lsa_openpolicy-style function

Parameters

smbstate: The SMB state table
handle: The handle to close

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is potentially a table of values, none of which are likely to be used.

lsa_enum_users (host)

Attempt to enumerate users using LSA functions.

Parameters

host: The host object.

Return value:

status, result -- if status is false, result is an error message; otherwise, result is an array of tables, each containing the following elements:

name
rid
domain
typestr
source

lsa_lookupnames2 (smbstate, policy_handle, names)

Call the LsarLookupNames2 function, to convert the server's name into a sid.

Parameters

smbstate: The SMB state table
policy_handle: The policy handle returned by lsa_openpolicy2
names: An array of names to look up. To get a SID, only one of the names needs to be valid.

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values. The most useful result is 'domains', which is a list of domains known to the server. And, for each of the domains, there is a 'name' entry, which is a string, and a 'sid' entry, which is yet another object which can be passed to functions that understand SIDs.

lsa_lookupsids2 (smbstate, policy_handle, sids)

Call the LsarLookupSids2 function, to convert a list of SIDs to their names

Parameters

smbstate: The SMB state table
policy_handle: The policy handle returned by lsa_openpolicy2
sids: The SIDs to look up (will probably be the server's SID with "-[rid]" appended

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values. The element 'domains' is identical to the lookupnames2() element called 'domains'. The element 'names' is a list of strings, for the usernames (not necessary a 1:1 mapping with the RIDs), and the element 'details' is a table containing more information about each name, even if the name wasn't found (this one is a 1:1 mapping with the RIDs).

lsa_openpolicy2 (smbstate, server)

Call the LsarOpenPolicy2 function, to obtain a "policy handle". This must be done before calling many of the LSA functions.

Parameters

smbstate: The SMB state table
server: The IP or Hostname of the server (seems to be ignored but it's a good idea to have it)

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values, the most useful one being 'policy_handle', which is required to call other functions.

lsa_SidType_tostr (val)

A proxy to a msrpctypes function that converts a SidType to an English string.

I implemented this as a proxy so scripts don't have to make direct calls to msrpctypes functions.

Parameters

val: The value to convert.

Return value:

A string that can be displayed to the user.

rap_netserverenum2 (smbstate, domain, server_type, detail_level)

Queries the (master) browser service for a list of server that it manages

Parameters

smbstate: The SMB state table (after bind has been called).
domain: (optional) string containing the domain name to query
server_type: number containing a server bit mask to use to filter responses
detail_level: number containing either 0 or 1

RRAS_marshall_RequestBuffer (RB_PCBIndex, RB_ReqType, RB_Buffer)

The RequestBuffer is a generic information container used by the RasRpcSubmitRequest method to set or retrieve information on RRAS server. This method performs serialization of RequestBuffer structure. Note: This structure is not an IDL specification and as such is not translated into NDR.

Parameters

RB_PCBIndex
RB_ReqType
RB_Buffer

Return value:

Returns a blob of RequestBuffer structure.

[MS-RRASM] 2.2.1.2.218 RequestBuffer

####################################################################--

RRAS_SubmitRequest (smbstate, pReqBuffer, dwcbBufSize)

The RasRpcSubmitRequest method retrieves or sets the configuration data on RRAS server.

Parameters

smbstate

The smb object.

pReqBuffer

The buffer MUST be large enough to hold the RequestBuffer structure and RequestBuffer.RB_Buffer data. RequestBuffer.RB_Reqtype specifies the request type which will be processed by the server and RequestBuffer.RB_Buffer specifies the structure specific to RB_Reqtype to be processed.

RequestBuffer.RB_PCBIndex<code> MUST be set to the unique port identifier
whose information is sought for <code>ReqTypes REQTYPE_GETINFO

and REQTYPE_GETDEVCONFIG. For other valid ReqTypes, RequestBuffer.RB_PCBIndex MUST be set to zero.

dwcbBufSize

Integer representing the size of pRegBuffer in bytes.

Return value:

(status, result)

status == true -> result is a blob that represent a pRegBuffer .
status == false -> result is a error message that caused the fuzz.
[MS-RRASM] 3.3.4.5 RasRpcSubmitRequest (Opnum 12)

####################################################################--

samr_AcctFlags_tostr (val)

A proxy to a msrpctypes function that converts a AcctFlags to an English string.

I implemented this as a proxy so scripts don't have to make direct calls to msrpctypes functions.

Parameters

val: The value to convert.

Return value:

A string that can be displayed to the user.

samr_close (smbstate, handle)

Call the close function, which closes a handle of any type (for example, domain_handle or connect_handle)

Parameters

smbstate: The SMB state table
handle: The handle to close

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is potentially a table of values, none of which are likely to be used.

samr_connect4 (smbstate, server)

Call the connect4 function, to obtain a "connect handle".

This must be done before calling many of the SAMR functions.

Parameters

smbstate: The SMB state table
server: The IP or Hostname of the server (seems to be ignored but it's a good idea to have it)

Return values:

status true or false
If status is false, result is an error message. Otherwise, result is a table of values, the most useful one being 'connect_handle', which is required to call other functions.

samr_enum_users (host)

Attempt to enumerate users using SAMR functions.

Parameters

host: The host object.

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is an array of tables, each of which contain the following fields:

name
fullname
description
rid
domain
typestr
source
flags[]

samr_enumdomainaliases (smbstate, domain_handle)

Call the EnumDomainAliases function, which retrieves a list of groups for a given domain

Parameters

smbstate: The SMB state table
domain_handle: The domain_handle, returned by samr_opendomain

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values.

samr_enumdomains (smbstate, connect_handle)

Call the enumdomains function, which returns a list of all domains in use by the system.

Parameters

smbstate: The SMB state table
connect_handle: The connect_handle, returned by samr_connect4()

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values, the most useful one being 'domains', which is a list of the domains.

samr_enumdomainusers (smbstate, domain_handle)

Call EnumDomainUsers, which returns a list of users only. To get more information about the users, the QueryDisplayInfo() function can be used.

Parameters

smbstate: The SMB state table
domain_handle: The domain_handle, returned by samr_opendomain

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values, the most useful one being 'names', which is a list of usernames in that domain.

samr_getaliasmembership (smbstate, alias_handle, args)

Call the GetAliasMembership function. Sends the "raw" data, without marshaling.

Parameters

smbstate: The SMB state table
alias_handle: The alias_handle, already marshaled
args: Actual data to send, already marshaled

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values.

samr_getmembersinalias (smbstate, alias_handle)

Call the GetMembersInAlias function, which retrieves a list of users in a group.

Parameters

smbstate: The SMB state table
alias_handle: The alias_handle, returned by samr_openalias

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values.

samr_lookupdomain (smbstate, connect_handle, domain)

Call the LookupDomain function, which converts a domain's name into its sid, which is required to do operations on the domain.

Parameters

smbstate: The SMB state table
connect_handle: The connect_handle, returned by samr_connect4
domain: The name of the domain (all domain names can be obtained with samr_enumdomains)

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values, the most useful one being 'sid', which is required to call other functions.

samr_lookupnames (smbstate, domain_handle, names)

Call the EnumDomainAliases function, which retrieves a list of groups for a given domain

Parameters

smbstate: The SMB state table
domain_handle: The domain_handle, returned by samr_opendomain
names

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values.

samr_openalias (smbstate, domain_handle, rid)

Call the OpenAlias function, which gets a handle to a group.

Parameters

smbstate: The SMB state table
domain_handle: The domain_handle, returned by samr_opendomain
rid: The RID of the alias

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values.

samr_opendomain (smbstate, connect_handle, sid)

Call OpenDomain, which returns a handle to the domain identified by the given sid. This is required before calling certain functions.

Parameters

smbstate: The SMB state table
connect_handle: The connect_handle, returned by samr_connect4
sid: The sid for the domain, returned by samr_lookupdomain

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values, the most useful one being 'domain_handle', which is used to call other functions.

samr_PasswordProperties_tostr (val)

A proxy to a msrpctypes function that converts a PasswordProperties to an English string.

I implemented this as a proxy so scripts don't have to make direct calls to msrpctypes functions.

Parameters

val: The value to convert.

Return value:

A string that can be displayed to the user.

samr_querydisplayinfo (smbstate, domain_handle, index, count)

Call QueryDisplayInfo, which returns a list of users with accounts on the system, as well as extra information about them (their full name and description).

I found in testing that trying to get all the users at once is a mistake, it returns ERR_BUFFER_OVERFLOW, so instead I'm only reading one user at a time. My recommendation is to start at index = 0, and increment until you stop getting an error indicator in result['return'].

Parameters

smbstate: The SMB state table
domain_handle: The domain handle, returned by samr_opendomain
index: The index of the user to check; the first user is 0, next is 1, etc.
count: [optional] The number of users to return; you may want to be careful about going too high. Default: 1.

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values, the most useful ones being 'names', a list of all the usernames, and 'details', a further list of tables with the elements 'name', 'fullname', and 'description' (note that any of them can be nil if the server didn't return a value). Finally, 'flags' is the numeric flags for the user, while 'flags_list' is an array of strings, representing the flags.

samr_querydomaininfo2 (smbstate, domain_handle, level)

Call QueryDomainInfo2, which grabs various data about a domain.

Parameters

smbstate: The SMB state table
domain_handle: The domain_handle, returned by samr_opendomain
level: The level, which determines which type of information to query for. See the @return section for details.

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values, and the values that are returned are dependent on the 'level' settings: Level 1: 'min_password_length' (in characters) 'password_history_length' (in passwords) 'password_properties' 'password_properties_list' (array of strings) 'max_password_age' (in days) 'min_password_age' (in days) Level 8 'create_time' (1/10ms since 1601) 'create_date' (string) Level 12 'lockout_duration' (in minutes) 'lockout_window' (in minutes) 'lockout_threshold' (in attempts)

service_create (host, servicename, path)

Create a "service" on a remote machine.

This service is linked to an executable that is already on the system. The name of the service can be whatever you want it to be. The service is created in the "stopped" state with "manual" startup, and it ignores errors. The 'servicename' is what people will see on the system while the service is running, and what'll stay there is something happens that the service can't be deleted properly.

Note that this (and the other "service" functions) are highly invasive. They make configuration changes to the machine that can potentially affect stability.

The reason that this and the other "service" functions don't require a smbstate object is that I wanted them to be independent. If a service fails to start, I don't want it to affect the program's ability to stop and delete the service. Every service function is independent.

Parameters

host: The host object.
servicename: The name of the service to create.
path: The path and filename on the remote system.

Return values:

status true or false
error message if status is false

service_delete (host, servicename)

Delete a service on the remote machine based on its name. I don't recommend deleting any services that you didn't create.

Parameters

host: The host object.
servicename: The name of the service to delete.

Return value:

(status, err) If status is false, err is an error message; otherwise, err is undefined.

service_start (host, servicename, args)

Start a service on the remote machine based on its name. For example, to start the registry service, this can be called on "RemoteRegistry".

If you start a service on a machine, you should also stop it when you're finished. Every service running is extra attack surface for a potential attacker

Parameters

host: The host object.
servicename: The name of the service to start.
args: [optional] The arguments to pass to the service. Most built-in services don't require arguments.

Return value:

(status, err) If status is false, err is an error message; otherwise, err is undefined.

service_stop (host, servicename)

Stop a service on the remote machine based on its name. For example, to stop the registry service, this can be called on "RemoteRegistry".

This can be called on a service that's already stopped without hurting anything (just keep in mind that an error will be returned).

Parameters

host: The host object.
servicename: The name of the service to stop.

Return value:

(status, err) If status is false, err is an error message; otherwise, err is undefined.

spoolss_abort_printer (smbstate, printer_handle)

Call the RpcAbortPrinter() function whose opnum is 21.

http://msdn.microsoft.com/en-us/library/cc244757%28v=prot.13%29

Parameters

smbstate: The SMB state table
printer_handle: Printer handle returned by spoolss_open_printer()

Return value:

(status, result) If status is false, result is an error message.

spoolss_end_doc_printer (smbstate, printer_handle)

Call the EndDocPrinter() function whose opnum is 23.

http://msdn.microsoft.com/en-us/library/cc244783%28v=prot.10%29

Parameters

smbstate: The SMB state table
printer_handle: Printer handle returned by spoolss_open_printer()

Return value:

(status, result) If status is false, result is an error message.

spoolss_open_printer (smbstate, printer)

Call the RpcOpenPrinterEx() function whose opnum is 69.

http://msdn.microsoft.com/en-us/library/cc244809%28v=prot.13%29.aspx

Parameters

smbstate: The SMB state table
printer: Printer share name

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a printer handle.

spoolss_start_doc_printer (smbstate, printer_handle, filename)

Call the RpcStartDocPrinter() function whose opnum is 17.

http://msdn.microsoft.com/en-us/library/cc244828%28v=prot.10%29.aspx

Parameters

smbstate: The SMB state table
printer_handle: Printer handle returned by spoolss_open_printer()
filename: Name of the file to print to

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a print job id.

spoolss_write_printer (smbstate, printer_handle, data)

Call the RpcWritePrinter() function whose opnum is 19.

http://msdn.microsoft.com/en-us/library/cc244831%28v=prot.10%29

Parameters

smbstate: The SMB state table
printer_handle: Printer handle returned by spoolss_open_printer()
data: Actual data to write to a file

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is number of bytes written.

srvsvc_netpathcanonicalize (smbstate, server, path)

Call the NetPathCanonicalize() function, which is the target of ms08-067.

Parameters

smbstate: The SMB state table
server: The IP or Hostname of the server (seems to be ignored but it's a good idea to have it)
path: The path to canonicalize

Return value:

(status, result, error_result) If status is false, result is an error message and error_result is the result table. Otherwise, result is a table of values.

srvsvc_netpathcompare (smbstate, server, path1, path2, pathtype, pathflags)

Call the NetPathCompare() function, which indirectly calls NetPathCanonicalize(), the target of ms08-067. I'm currently only using this to trigger ms08-067.

The string used by Metasploit and other free tools to check for this vulnerability is '\AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\..
'. On vulnerable systems, this will be accepted and this function will return '0'. On patched systems, this will be rejected and return ERROR_INVALID_PARAMETER.

Note that the srvsvc.exe process occasionally crashes when attempting this.

Parameters

smbstate: The SMB state table
server: The IP or Hostname of the server (seems to be ignored but it's a good idea to have it)
path1: The first path to compare
path2: The second path to compare
pathtype: The pathtype to pass to the function (I always use '1')
pathflags: The pathflags to pass to the function (I always use '0')

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values containing 'return'.

srvsvc_netservergetstatistics (smbstate, server)

Calls the NetServerGetStatistics function, which grabs a bunch of statistics on the server. This function requires administrator access to call.

Note: Wireshark 1.0.3 doesn't parse this packet properly.

Parameters

smbstate: The SMB state table
server: The IP or name of the server (I don't think this is actually used, but it's good practice to send it).

Return value:

A table containing the following values: * 'start' The time when statistics collection started (or when the statistics were last cleared). The value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. To calculate the length of time that statistics have been collected, subtract the value of this member from the present time. 'start_date' is the date as a string. * 'fopens' The number of times a file is opened on a server. This includes the number of times named pipes are opened. * 'devopens' The number of times a server device is opened. * 'jobsqueued' The number of server print jobs spooled. * 'sopens' The number of times the server session started. * 'stimedout' The number of times the server session automatically disconnected. * 'serrorout' The number of times the server sessions failed with an error. * 'pwerrors' The number of server password violations. * 'permerrors' The number of server access permission errors. * 'syserrors' The number of server system errors. * 'bytessent' The number of server bytes sent to the network. * 'bytesrcvd' The number of server bytes received from the network. * 'avresult' The average server result time (in milliseconds). * 'reqbufneed' The number of times the server required a request buffer but failed to allocate one. This value indicates that the server parameters may need adjustment. * 'bigbufneed' The number of times the server required a big buffer but failed to allocate one. This value indicates that the server parameters may need adjustment.

srvsvc_netsessenum (smbstate, server)

Call the NetSessEnum function, which gets a list of active sessions on the host. For this function, a session is defined as a connection to a file share.

Parameters

smbstate: The SMB state table
server: The IP or Hostname of the server (seems to be ignored but it's a good idea to have it)

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is an array of tables. Each table contains the elements 'user', 'client', 'active', and 'idle'.

srvsvc_netshareenumall (smbstate, server)

Call the MSRPC function netshareenumall on the remote system.

This function basically returns a list of all the shares on the system.

Parameters

smbstate: The SMB state table
server: The IP or Hostname of the server (seems to be ignored but it's a good idea to have it)

Return values:

status true or false
If status is false, result is an error message. Otherwise, result is a table of values, the most useful one being 'shares', which is a list of the system's shares.

srvsvc_netsharegetinfo (smbstate, server, share, level)

Call the MSRPC function netsharegetinfo on the remote system. This function retrieves extra information about a share on the system.

Parameters

smbstate: The SMB state table
server: The IP or Hostname of the server (seems to be ignored but it's a good idea to have it)
share
level

Return value:

(status, result) If status is false, result is an error message. Otherwise, result is a table of values, the most useful one being 'shares', which is a list of the system's shares.

srvsvc_ShareType_tostr (val)

A proxy to a msrpctypes function that converts a ShareType to an English string.

I implemented this as a proxy so scripts don't have to make direct calls to msrpctypes functions.

Parameters

val: The value to convert.

Return value:

A string that can be displayed to the user.

start_smb (host, path, disable_extended, overrides)

This is a wrapper around the SMB class, designed to get SMB going quickly for MSRPC calls.

This will connect to the SMB server, negotiate the protocol, open a session, connect to the IPC$ share, and open the named pipe given by 'path'. When this successfully returns, the 'smbstate' table can be immediately used for MSRPC (the bind function should be called right after).

Note that the smbstate table is the same one used in the SMB files (obviously), so it will contain the various results/information places in there by SMB functions.

Parameters

host: The host object.
path: The path to the named pipe; for example, msrpc.SAMR_PATH or msrpc.SRVSVC_PATH.
disable_extended: [optional] If set to 'true', disables extended security negotiations.
overrides: [optional] Overrides variables in all the SMB functions.

Return values:

status true or false
smbstate if status is true, or an error message.

stop_smb (state)

A wrapper around the smb.stop function.

I only created it to add symmetry, so client code doesn't have to call both msrpc and smb functions.

Parameters

state: The SMB state table.

string_uuid_to_exe (uuid)

Helper function that maps known UUIDs to corresponding exe/services.

Parameters

uuid

Return value:

Corresponding service and description as a string or nil.

svcctl_closeservicehandle (smbstate, handle)

Calls the function CloseServiceHandle, which releases a handle.