HOMER LUA Scripting

HOMER + LuaJIT (HEPjit)

One of hottest features in HOMER 7 is lightspeed packet manipulation using LuaJIT 💥

This feature delivers unprecedented power and flexibility in processing HEP messages to extract custom headers, anonymize or encrypt user data, tag traffic based on custom logic and beyond only limited by your imagination and skills - all performing at native speed!

This idea has been incubating for a few years and @adubovikov now released it to heplify-server ❤️

---

So how does this work?

Requirements

• heplify-server w/ LuaJIT (git)
• liblua5.1-dev

Configuration

A few simple steps are required to enable and configure your first HEP Lua script.

Heplify-Server

TOML

Enable scripting and configure your entrypoint LuaJIT script, by default inside the lua directory.

ScriptEnable   = true
ScriptFile     = "lua/heplify.lua"

ScriptFile

The entrypoint LuaJIT script will be called for each matching HEP packet on its way to the core. The following default example provides a few usage examples for HEP Type 1 (SIP) to extract a custom header using Regex, Add custom tags and Replace existing message fields, all commented -- inline.

-- this function will be executed first
function init()

	local protoType = HEP.api.getHEPProtoType()

	-- Check if we have SIP payload
	if protoType ~= 1 then
		return
	end

	-- get All SIP parsed variables FromUser, ToUser, CallID
	local variables = HEP.api.getParsedVariables()
	-- original SIP message Payload
	local raw = HEP.api.getRawMessage()

	--[[ "applyHeader":        dec.applyHeader,
		"logData":            dec.logData,
		"setCustomHeaders":   dec.setCustomHeaders,
		"getParsedVariables": dec.getParsedVariables,
		"getHEPProtoType":    dec.getHEPProtoType,
		"getHEPSrcIP":        dec.getHEPSrcIP,
		"getHEPSrcPort":      dec.getHEPSrcPort,
		"getHEPDstIP":        dec.getHEPDstIP,
		"getHEPDstPort":      dec.getHEPDstPort,
		"getHEPTimeSeconds":  dec.getHEPTimeSeconds,
		"getHEPTimeUseconds": dec.getHEPTimeUseconds,
		"getHEPObject":       dec.getHEPObject,
		"getRawMessage":      dec.getRawMessage,
		"print":              fmt.Println,
	--]]

	-- HEP.api.logData("ERROR", "check:", raw)
	-- HEP.api.logData("DEBUG", "data", variables)

	-- Create lua table 
	local headers = {}

        -- Attach a custom tag/header
	headers["X-test"] = "Inject a Tag/Header"


	-- Extract CSEQ using regex and store to headers array
	local name, value = raw:match("(CSeq):%s+(.-)\n")

	if name == "CSeq" then
		headers[name] = value
	end

        -- attach to HEP message
	HEP.api.setCustomHeaders(headers)
	
	-- Modify or Anonymize any header and value from Standard Headers List (below)
	-- Or encrypt or replace the full SIP messsage (RAW) with an entirely different content.
        -- HEP.api.applyHeader("FromUser", "Anonymized")
	-- HEP.api.applyHeader("RAW", "SIP 2/0")

	return 

end

Add Fields to Mapping

In order to display and search any added field, implement in Mapping for the desired transaction type:

{
        "id": "CSeq",
        "type": "string",
        "index": "secondary",
        "name": "CSeq Extraction",
        "form_type": "input",
        "position": 99,
        "sid_type": true,
        "hide": false
    }

• Checkout the list of standard preparsed headers
• Thinking of complex logic and routing? The entrypoint script can also include and use sub-scripts.

Done

That's it, You're ready to go!

If you find this powerful feature interesting and use it in your setup, please report any bugs and contribute your scripts or changes back to the community to grow a fantastic library of HEPxperiments!

---

Standard Header List

The following headers can be directly manipulated.
For custom extractions, use Regex against the RAW header.

        case header == "Via":
	case header == "FromUser":
	case header == "FromHost":
	case header == "FromTag":
	case header == "ToUser":
	case header == "ToHost":
	case header == "ToTag":
	case header == "Call-ID":
	case header == "X-CID":
	case header == "ContactUser":
	case header == "ContactHost":
	case header == "User-Agent":
	case header == "Server":
	case header == "AuthorizationUsername":
	case header == "Proxy-AuthorizationUsername":
	case header == "PAIUser":
	case header == "PAIHost":
	case header == "RAW":
``