18.3.5. File

File information is exposed to Lua scripts with the suricata.file library, for example:

local filelib = require("suricata.file")

18.3.5.1. Setup

If your purpose is to create a logging script, initialize the script as:

function init (args)
   local needs = {}
   needs["type"] = "file"
   return needs
end

Currently the Lua file library is not implemented for rules.

18.3.5.2. API

18.3.5.2.1. File Object

File data is accessed through the file object, which must be obtained before use:

local file, err = filelib.get_file()
if file == nil then
    print(err)
end

18.3.5.2.2. File Methods

18.3.5.2.2.1. file_id()

Returns the ID number of the file.

Example:

local file = filelib.get_file()
local id = file:file_id()
print("File ID: " .. id)

18.3.5.2.2.2. tx_id()

Returns the transaction ID associated with the file.

Example:

local file = filelib.get_file()
local tx_id = file:tx_id()
print("Transaction ID: " .. tx_id)

18.3.5.2.2.3. name()

Returns the file name.

Example:

local file = filelib.get_file()
local name = file:name()
if name ~= nil then
    print("Filename: " .. name)
end

18.3.5.2.2.4. size()

Returns the file size.

Example:

local file = filelib.get_file()
local size = file:size()
print("File size: " .. size .. " bytes")

18.3.5.2.2.5. magic()

Returns the file type based on libmagic (if available). Will return nil if magic is not available.

Example:

local file = filelib.get_file()
local magic = file:magic()
if magic ~= nil then
    print("File type: " .. magic)
end

18.3.5.2.2.6. md5()

Returns the MD5 hash of the file (if calculated). Will return nil if the MD5 hash was not calculated.

Example:

local file = filelib.get_file()
local md5 = file:md5()
if md5 ~= nil then
    print("MD5: " .. md5)
end

18.3.5.2.2.7. sha1()

Returns the SHA1 hash of the file (if calculated). Will return nil if the SHA1 hash was not calculated.

Example:

local file = filelib.get_file()
local sha1 = file:sha1()
if sha1 ~= nil then
    print("SHA1: " .. sha1)
end

18.3.5.2.2.8. sha256()

Returns the SHA256 hash of the file (if calculated). Will return nil if the SHA256 hash was not calculated.

Example:

local file = filelib.get_file()
local sha256 = file:sha256()
if sha256 ~= nil then
    print("SHA256: " .. sha256)
end

18.3.5.2.2.9. get_state()

Returns the current state of the file.

Returns:

• State: "CLOSED", "TRUNCATED", "ERROR", "OPENED", "NONE", or

  "UNKNOWN"

Example:

local file = filelib.get_file()
local state = file:get_state()
if state ~= nil then
    print("File state: " .. state)
end

18.3.5.2.2.10. is_stored()

Returns true if the file has been stored to disk, false otherwise.

Example:

local file = filelib.get_file()
local stored = file:is_stored()
print("File stored: " .. tostring(stored))