Processing Connections in Lua

In this section:

•General Information.

•Requirements for the Script of Connection Processing.

•Examples.

•Tables in Use.

•Available Auxiliary Modules.

General Information

Dr.Web Firewall for Linux supports interaction via program interpreter in Lua (version 5.3.4 is used and is supplied together with Dr.Web for UNIX Mail Servers). Scripts written in Lua can be used by the component for preliminary connection scanning before it is send to SpIDer Gate for analysis.

Connections will be analyzed with the Lua script, if the path to this script is specified in the Dr.Web Firewall for Linux settings (in the InterceptHook parameter). Otherwise, connection processing is performed by using the default settings and processing rules specified in the component settings (the RuleSet* parameters).

For more examples of Lua scripts for connection processing, follow the link:
https://github.com/DoctorWebLtd/drweb-lua-examples/tree/master/firewall.

Requirements for the Script of Connection Processing

The script must contain a global function, which is the entry point in the connection scanning module (Dr.Web Firewall for Linux calls this function for processing a newly received connection). The function should match the following call conventions:

•function name—intercept_hook;

•the only argument—the Lua context table (provides the access to information from function on the processed connection, see description of the table below);

•the only return value—one of the string values from the table below:

Value

Verdict description

pass

Skip the connection without checking it by SpIDer Gate

check

Check the connection with the help of SpIDer Gate

reject

Discard the connection (the client who initiated the connection will receive the TCP package with an RST flag)

drop

Disconnect (the client that initiated the connection will receive no acknowledgement)

Examples
 

1.The script always returns the pass verdict (skip) for all the connections lest the connections be checked by Dr.Web Firewall for Linux:

-- Function of connection scanning written by the user
function intercept_hook(ctx)
  return "pass" -- do not scan the connection
end

2.With the help of the script given below Dr.Web Firewall for Linux checks all the connections being established with the following exceptions:

•outgoing local connections from applications running with user rights from the drweb group;

•connections initiated from privileged ports (regardless of the connection owner and its direction);

•connections originating from IP addresses of the local network:

function intercept_hook(ctx)
  -- Do not scan connections, initiated from the local
  -- host (divert == "output") by application under the name of
  -- "drweb" (group == "[drweb]")
  if ctx.divert == "output" and ctx.group == "drweb" then
    return "pass"
  end

  -- Do not scan connections, initiated from
  -- privileged ports (range is from 0 to 1024)
  if ctx.src.port >= 0 and ctx.src.port <= 1024 then
    return "pass"
  end

  -- Do not scan connections from local network IP addresses
  -- (IP address range 127.0.0.1/8)
  if ctx.src.ip.belongs("127.0.0.0/8") then
    return "pass"
  end

  -- Connection is scanned by default
  return "check"
end

Tables Used in Scripts

1. InterceptContext Table

The table is used to transfer data on the processed connection to the intercept_hook function. On the basis of this data one of the following action can be performed to the connection:

•skip without checking;

•disrupt the connection;

•send the connection to SpIDer Gate for checking.

Dr.Web Firewall for Linux fills the table with data. Some data in the table is already available by the time the intercept_hook functions are executed, other data (so called “lazy” data) will be calculated directly upon request of the corresponding field of the table.

Field

Description

Data type

src

Address and port of the client that initiated the connection

Example:

if ctx.src.port >= 0 and ctx.src.port <= 1024 then
  return "pass"
end

TcpEndpoint table

dst

Address and port of the server, the connection to which was initiated by the client

Example:

if ctx.dst.ip.belongs("10.20.30.41/8") then
  return "reject"
end

TcpEndpoint table

divert

The type of intercepted connection:

•"output"—outgoing connection;

•"input"—incoming connection;

•"forward"—transit connection.

Example:

if ctx.divert == "forward" then
  return "check"
end

String

iface_in

The name of the interface from which the connection was initiated.

If the name of the interface was not identified, it has the nil value.

String

iface_out

The name of the interface to which the packets were sent after the connection had been initiated.

If the name of the interface was not identified, it has the nil value.

String

uid

The ID of the user who initiated the outgoing connection.

If the connection type (divert) is not "output", or UID cannot be identified, it has nil value.

Number

gid

The ID of the group on behalf of which the outgoing connection was initiated.

If the connection type (divert) is not "output", or GID cannot be identified, it has the nil value.

Number

user

The name of the user who initiated the outgoing connection.

If the connection type (divert) is not "output", or UID cannot be identified, it has the nil value.

String

group

The name of the group on behalf of which the outgoing connection was initiated.

If the connection type (divert) is not "output", or UID cannot be identified, it has the nil value.

String

pid

The ID of the process which initiated the outgoing connection.

If the connection type (divert) is not "output", or PID cannot be identified, it has the nil value.

Number

exe_path

Executable path to the application file which initiated the outgoing connection.

If the connection type (divert) is not "output", or executable path cannot be identified, it has the nil value.

String

Overridden metamethods: None

2. TcpEndpoint Table

The table describes the address of connection point (client or server).

Field

Description

Data type

ip

IP address

The IpAddress table

port

Port number

Number

Overridden metamethods:

•__tostring—a function that converts TcpEndpoint to a string, for example: "127.0.0.1:443" (IPv4) or "[::1]:80" (IPv6);

•__concat—a function that concatenates TcpEndpoint to a string

Available Auxiliary Modules

For interconnection with Dr.Web for UNIX Mail Servers in program space in Lua the following specific modules can be imported.

Name of the module

Function

drweb

The module that provides functions to record messages from the Lua program to the log of the Dr.Web for UNIX Mail Servers component which has launched the Lua program and the means of asynchronous execution of Lua procedures

drweb.lookup

The module that provides tools to request data from external sources by calling the Dr.Web LookupD module

Contents of the drweb Module

1.Functions

The module provides a set of functions.

•Storing messages from the Lua program in the Dr.Web for UNIX Mail Servers component log:

▫log(<level>, <message>) writes the <message> string to the Dr.Web for UNIX Mail Servers log on the <level> level (the required level is defined using one of the following values (string): debug, info, notice, warning, error);

▫debug(<message>) writes the <message> string to the Dr.Web for UNIX Mail Servers log at the debug level;

▫info(<message>) writes the <message> string to the Dr.Web for UNIX Mail Servers log at the info level;

▫notice(<message>) writes the <message> string to the Dr.Web for UNIX Mail Servers log at the notice level;

▫warning(<message>) writes the <message> string to the Dr.Web for UNIX Mail Servers log at the warning level;

▫error(<message>) writes the <message> string to the Dr.Web for UNIX Mail Servers log at the error level.

•Managing the synchronization of Lua procedures:

▫sleep(<sec.>) pauses the execution of a Lua procedure instance for a specified number of seconds;

▫async(<Lua function>[, <argument list>]) launches the specified function asynchronously and passes to it the specified argument list. The async function call completes immediately, and the return value (the Future table) allows you to obtain the result of the <Lua function>.

•Storing the information about an IP address in the form of the IpAddress table:

▫ip(<address>) indicates an IP address sent as the <address> string in the form of the IpAddress table. Either IPv4 or IPv6 addresses can be used.

•Uploading external data from a text file:

▫load_set(<file path>) generates a table with the true values from the contents of a specified text file; strings read from the file are used as keys. Empty strings and strings with white spaces will be ignored;

▫load_array(<path to file>) generates a string array from the contents of a specified text file. Empty strings and strings consisting only of white spaces are ignored.

2.Tables

•The Future table describes the pending result of performing a function using the async function.

Field

Description

Data type

wait

A function that returns the result of the function started using the async function. If the function has not completed its execution yet, it waits for the completion and returns its result. If the function is completed before wait is called, the result is returned immediately. If the started function fails, the wait call generates the same error.

Function

Overridden metamethods: None

•The IpAddress table describes an IP address.

Field

Description

Data type

belongs

Function checks an IP address stored in the IpAddress table for belonging to specified subnets (IP address ranges).

Accepts a single argument—a string that looks like: "<IP address>" or "<IP address>/<mask>", where <IP address>—a host address or a network address (for example, 127.0.0.1), and <mask>—a subnetwork mask (can be specified as an IP address, for example, 255.0.0.0, or in the numerical form, for example, 8).

Returns a Boolean value:

•true indicates that the address matches at least one of the specified IP addresses or belongs to at least one of the specified subnets (the range of IP addresses);

•false—if the address does not match any one of the specified addresses or does not belong to any of the specified subnets

Function

Overridden metamethods:

•__tostring is a function that transforms IpAddress into a string, for example, 127.0.0.1 (IPv4) or ::1 (IPv6);

•__concat is a function that joins IpAddress to a string;

•__eq is a function that checks the equality of two IpAddress;

•__band is a function that allows to apply a mask, for example: dw.ip('192.168.1.2') & dw.ip('255.255.254.0')

3.Examples

•Logging messages generated by a procedure initiated asynchronously:

local dw = require "drweb"

-- This function returns a string received as an argument
-- after the delay of two seconds
function out_msg(message)
 dw.sleep(2)
 return message
end

-- "Main" function
function intercept(ctx)
 -- Output the string at the notice level to the log of Dr.Web for UNIX Mail Servers
 dw.notice("Intercept function started.")

 -- Run two instances of the out_msg function asynchronously
 local f1 = dw.async(out_msg, "Hello,")
 local f2 = dw.async(out_msg, " world!")

 -- Wait for the completion of the instances of the function
 -- out_msg and log their results
 -- Dr.Web for UNIX Mail Servers at the debug level
 dw.log("debug", f1.wait() .. f2.wait())
end

•Creating a scheduled procedure:

local dw = require "drweb"

-- Store the Future table as a futurе global variable to
-- prevent its removal by the garbage collector
future = dw.async(function()
   while true do
     -- Log the following message each day
     dw.sleep(60 * 60 * 24)
     dw.notice("A brand new day began")
   end
end)

•Transform the string to the IP address:

local dw = require "drweb"

local ipv4 = dw.ip("127.0.0.1")
local ipv6 = dw.ip("::1")
local mapped = dw.ip("::ffff:127.0.0.1")

 

Contents of the drweb.lookup Module

1.Functions

The module provides the following functions:

•lookup(<request>, <parameters>) requests data from an external storage available via the Dr.Web LookupD module. The <request> argument must correspond to a section in the Dr.Web LookupD settings (the <type>@<tag>string). The <parameters> argument is optional and describes substitutions to be used to generate a request. The following automatically permitted markers can be used:

▫$u, $U is automatically replaced with user—the user name sent by the client component;

▫$d, $D is automatically replaced with domain—the domain name sent by the client component.

Arguments are set as a table, which keys and values must be strings. The function returns an array of strings that are results of the request;

•check(<checked string>, <request>, <parameters>) returns true if <checked string> is found in the external repository, available via the Dr.Web LookupD module. The <request> and <parameters> arguments are equivalent to the arguments of the lookup function (see above). The <checked string> argument must be a string or a table with a __tostring metamethod (i.e. that can be transformed into a string).

2.Examples

•Log a list of users retrieved from the LookupD.LDAP.users data source:

local dw = require "drweb"
local dwl = require "drweb.lookup"

-- "Main" function
function intercept(ctx)
 -- Store the string in the Dr.Web for UNIX Mail Servers log at the notice level
 dw.notice("Intercept function started.")

 -- Store in the Dr.Web for UNIX Mail Servers log results of requesting
 -- the 'ldap@users' data source
 for _, s in ipairs(dwl.lookup("ldap@users", {user="username"})) do
   dw.notice("Result of request to 'ldap@users': " .. s)
 end

end