|
Dr.Web Firewall for Linux supports interaction via program interpreter in Lua (the required version of interpreter is supplied together with the product). Scripts written in Lua, can be used by the component for preliminary connection scanning before it is send to SpIDer Gate for analysis.
Connection analysis connections using the script in Lua is performed, if the Dr.Web Firewall for Linux settings (in the InterceptHookPath parameter), the path to the file with the script of the connection scanning written in Lua for is specified. Otherwise, connection processing is performed by using the default settings and processing rules specified in the component settings (the RuleSet* parameters).
Requirements for the script of connection processing
The file must contain global function, that is the entry point in the connection scanning module (Dr.Web Firewall for Linux calls this function for processing newly received connection). The function of processing should match the following call conventions:
1.Function name—intercept_hook; 2.The only argument—table Lua context (provides the access to information from function on the processed connection, see description of the table below); 3.The only return value—value from the table Lua drweb.firewall.verdict (see description of the table below). Example of the correct definition of the Lua script, which will unconditionally return verdict PASS (skip) to the Dr.Web Firewall for Linux for all the connections:
--Load the drweb. firewall module and provide access to it via the fw variable
local fw = require "drweb.firewall"
--Entry point, that is the function of connection scanning written by the user
function intercept_hook(ctx)
return fw.verdict.PASS -- do not scan the connection
end
|
Table context
The table of the context type is used to transfer data on the processed connection to the intercept_hook function. The data can be used to determine what to do with the connection (skip it without scanning, disconnect or send for checking by SpIDer Gate). Dr.Web Firewall for Linux fills in data into the table. Some data in the table is already known by the time the intercept_hook functions is executed, other information (so called “lazy” data) will be evaluated directly upon request of the corresponding field of the table.
|
In fact, all the fields in the context table are functions, that is why some of them can cause Lua exceptions if it is impossible to calculate the requested value.
|
Fields in the context table (in the examples below the name of the object is ctx which is an argument of the intercept_hook function):
Field
|
Description
|
src_ip
|
Returns a string representation of the IP addresses of an intercepted connection initiator.
Example:
log.debug('Source IP: ' .. ctx.src_ip) -- Outputs "Source IP: 127.0.0.1"
|
dst_ip
|
Returns a string representation of the IP addresses of an intercepted connection destination point.
Example:
log.debug('Destination IP: ' .. ctx.dst_ip) -- Outputs "Destination IP: 127.0.0.1"
|
src_port
|
Returns source port of intercepted connection as Integer.
Example:
log.debug('Source port: ' .. ctx.src_port) -- Outputs "Source port: 58876"
|
dst_port
|
Returns destination port of intercepted connection as Integer.
Example:
log.debug('Destination port: ' .. ctx.dst_port) -- Outputs "Destination port: 8080"
|
exe_path
|
Returns a path to the executable file that sent intercepted package as a string or makes exception in case of an error (if it is impossible to determine the process sender of the package).
It makes sense only to intercept outgoing connections, i.e. when ctx. divert == drweb. firewall. divert. OUTPUT.
Example:
log.debug('Exe path: ' .. ctx.exe_path) -- Outputs "Exe path: /usr/bin/firefox"
|
divert
|
Returns the type of an intercepted connection (outgoing, incoming, transit) — one of the values in the drweb.firewall.divert table (see below).
Example:
if ctx.divert == fw.divert.OUTPUT then
log.debug('Intercepted output connection; exe path is ' .. ctx.exe_path)
end
|
|
in_iface_name
|
Returns the name of the interface from which the intercepted packet was received as a string. Makes an exception if the name of the interface cannot be determined for this type of connection.
Example:
log.debug('Input interface name: ' .. ctx.in_iface_name) -- Input interface name: lo
|
out_iface_name
|
Returns the name of the interface to which the intercepted packet was directed as a string. Makes an exception if the name of the interface cannot be determined for this type of connection.
Example:
log.debug('Output interface name: ' .. ctx.in_iface_name) -- Output interface name: eth0
|
hwaddr
|
Returns a MAC address of the device that sent the intercepted package as a string in the AA:BB:CC:DD:EE:FF format.
Example:
log.debug('MAC: ' .. ctx.hwaddr) -- MAC: 74:d4:35:5b:2c:40
|
uid
|
Returns UID of the connection owner, who sent the intercepted package as Integer. In case of an error (if it is impossible to establish the connection owner) makes an exception
Example:
log.debug('Owner UID: ' .. tostring(ctx.uid))) -- Owner UID: 1000
|
gid
|
Returns GID of the connection owner, who sent the intercepted package as Integer. In case of an error (if it is impossible to establish the connection owner) makes an exception
Example:
log.debug('Owner GID: ' .. tostring(ctx.gid))) -- Owner GID: 100
|
user
|
Returns the name of the connection owner, who sent the intercepted package as a string. In case of an error (if it is impossible to establish the connection owner) makes an exception
Example:
log.debug('Owner: ' .. ctx.user) -- Owner: username
|
group
|
Returns the name of the group of the connection owner, who sent the intercepted package as a string. In case of an error (if it is impossible to establish the connection owner) makes an exception
Example:
log.debug('Owner's group: ' .. ctx.group) -- Owner's group: usergroup
|
Available plug-ins
The following specific modules (listed in the table below) can be imported to communicate with Dr.Web Firewall for Linux in program space in Lua.
Name of the module
|
Function
|
Note
|
drweb.firewall
|
Module provides tables with constants used to specify the type of the connection and verdict made by the module for the connection (value drweb.firewall.verdict returned by the intercept_hookfunction)
|
The module is required for import
|
drweb.log
|
Module provides functions to save messages from program in Lua in the Dr.Web Firewall for Linux log.
|
—
|
drweb.util
|
Module provides auxiliary features that could be used in the program processing of the connections for checking various conditions
|
—
|
Contents of the drweb. firewall module
1.Table verdict—contains possible return codes of the intercept_hook function, considered by Dr.Web Firewall for Linux as a verdict on processing of the intercepted messages. The table contents:
Key
|
Value
|
Verdict description
|
PASS
|
missing
|
To skip the connection without its scanning by SpIDer Gate
|
CHECK
|
missing
|
Scan the connection with the help of SpIDer Gate
|
DROP
|
missing
|
Discard the package that initiates the connection, making destination address a "black hole"
|
REJECT
|
missing
|
Discard the connection (the client that initiates the connection, receives the RST TCP package and an error Connection refused)
|
2.Table divert—contains possible direction types of the intercepted connection. This table is a field of the context table. The table contents:
Key
|
Value
|
Description of the connection type
|
OUTPUT
|
missing
|
Outgoing connection (initiated by the client on the local host, connecting to the remote host)
|
INPUT
|
missing
|
Incoming connection (initiated by the client on the remote host, connecting to an application on the local host)
|
FORWARD
|
missing
|
Transit connection (initiated by the client on the remote host, connecting to an application on the remote host, that is transits the local host)
|
Note that the connection sent from a client on the local host to the application also on the local host, depending on the Dr.Web Firewall for Linux settings can be classified both INPUT and OUTPUT in the context.divert field. Anyway, the context.src_ip and context.dst_ip addresses are the same for such a connection (description of the context table context see below).
Contents of the drweb.log module
Provides the following functions to save messages from program in Lua in the Dr.Web Firewall for Linux log.
•debug(message)—Writes a string message in the Dr.Web Firewall for Linux log on the DEBUG level. •info(message)—Writes a string message in the Dr.Web Firewall for Linux log on the INFO level. •notice(message)—Writes a string message in the Dr.Web Firewall for Linux log on the NOTICE level. •warning(message)—Writes a string message in the Dr.Web Firewall for Linux log on the WARNING level. •error(message)—Writes a string message in the Dr.Web Firewall for Linux log on the ERROR level. Example:
local log = require 'drweb.log'
log.notice('Hello, world!') -- outputs a string on the NOTICE level
|
Contents of the drweb.util module
Provides the following auxiliary functions to be used in the processing module in Lua:
1.in_subnet(address, subnet)—returns true if address is in subnet, false—otherwise. •address is the IP IPv4 address in the string representation, for example: '192.168.1.13'. •subnet is a subnet in the <network address>/<network mask> format (for example, '127.0.0.1/255.0.0.0') or in the CIDR format: <network address >/<prefix length> (for example, '127.0.0.1/8'). Example:
local log = require 'drweb.log'
local util = require 'drweb.util'
log.debug(tostring(util.in_subnet('127.0.0.1', '127.0.0.0/8'))) -- true
log.debug(tostring(util.in_subnet('192.168.0.1', '127.0.0.0/255.0.0.0'))) -- false
|
| 