Skip to main content

Object T.async

The T.async interface provides methods to help you do long running I/O tasks that do not block the fast packet pipeline path. For introduction to Async scripting operations. See Async operations introduction

Purpose of T.async

To execute long running I/O tasks in a separate worker pool to prevent blocking the Trisul streaming pipelines. The default worker thread pool size is 1, it can be increased at the script level by TrisulPlugin.request_async_workers parameter

Methods

functionparameterswhat it does
catfrom_file,to_fileAppend one file to another
copyfrom_file,to_fileCopy one file to another
rmfilename : stringDelete a file
copybufferfrom_buffer (a Buffer object), to_fileAppend buffer content bytes to the target file
schedulea LUA schedule blockRuns the LUA functions in the block asynchronosly and re-enter the fast path at a later time when results are ready

Function T.async.cat

Appends file1 to file2.

Purpose

Append content of file1 to the end of file2. If file2 does not exist, it is created.

Parameters

from_filefilename stringsource filename. In file reassemly scripts, this typically in the ramfs.
to_filefilename stringdestination file. if it doesnt exist it is created.

Return value

None

Usage

..
T.async.cat("/tmpfs/k/file1.data", "/home/nsm/files/file123.dat")
..

Function T.async.copy

Copies file1 to file2.

Purpose

Copies file1 to file2. Creates file2 if it does not exist, overwrites it if it does.

Parameters

from_filefilename stringsource filename.
to_filefilename stringdestination file.

Return value

None


Function T.async.rm

Deletes the file.

Purpose

Deletes the file, if present.

Parameters

filenamefilename stringfilename to delete from the filesytem

Return value

None


Function T.async.copybuffer

Operations on writing Buffer contents to files.

Purpose

Write contents of a buffer object to disk.

Parameters

NameInfoDescription
buffA Buffer objectan object usually passed by Trisul into your LUA script
filenamefilename stringfilename to write to. File is created if it doesnt exist
position (optional)seelpos numberOptional At what position do you want to write the buffer. If this parameter is not specified the default mode of copybuffer is to append to the end of the file

Return value

None

Usage

..

-- appends to the end of the file T.async.copybuffer( payload_buffer, "/home/nsm/files/file123.dat")

T.async.copybuffer( payload_buffer, "/home/nsm/files/file123.dat")

-- writes at specifed position used by (reassembly scripts)
..
T.async.copybuffer( payload_buffer, "/home/nsm/files/file123.dat", seekpos )

Function T.async:schedule

T.async methods cp,cat,rm,copybuffer described above accomplish very specific tasks. Using the T.async:schedule method described below you can run any arbitrary LUA code out of the main packet pipeline.

T.async:schedule
Imagine your LUA script needed to look up a dictionary of Malware online, you would write the LUA code to do that and use the schedule method to push it out of the fast path.

Methods

T.async:schedule expects a table with the following fields

datastringa string that is passed on to the onexecute function below
onexecutefunction( in_data)called on SLOWPATH A function that accepts the data string specified. This function executes in a separate thread/task from the packet pipeline. You do your processing and optionally return a ‘response’ string. See rules below
onresultfunction(engine, in_data, out_data)called on FASTPATH if your script in onexecute on the separate thread returns string, Trisul will re-enter the fast path and call the onresult function with the result string. You can then update the engine parameter by adding metrics, generating alerts, or interact with Trisul in any way

Usage

This small snippet shows the usage

Task: calculate sha1sum of extracted file

onfile_http  = function ( engine, timestamp, flowkey,
path, req_header, resp_header, length )


T.async:schedule(
{
-- send the file path
--
data = path,

--
-- [ on slow path, another thread ]
-- calc sha1sum on the file
-- and return the string
--
onexecute = function( indata)
local h = io.popen("sha1sum "..path)
local sha1 = h:read("*a")
h:close()
return sha1
end,

--
-- [ back on fast path]
--
onresult = function(engine, req, response)
print("The SHA1 sum of "..path.." IS " .. response)
end
}
)

end,