3. Flow User Scripts

The Flows User Scripts API is only available from the Flow User Scripts Hooks.

Functions

function getStatus()

Get the complete status bitmap of the flow, which includes all the current problems of the flow.

Return

the flow status bitmap

function setStatus(table flow_status_type, int flow_score, int cli_score, int srv_score)

Set a bit into the flow status bitmap, effectively marking the flow as misbehaving.

Return

true if the flow status was updated, false if the flow status is unchanged.

Parameters

• flow_status_type: the flow status to set. The possible values can be obtained by printing flow_consts.status_types
• flow_score: the score (a quantitative indicator of the problem) to associate to this status
• cli_score: the score increment on the client host.
• srv_score: the score increment on the server host.

function clearStatus(table flow_status_type)

Clear a bit into the flow status bitmap.

Parameters

• flow_status_type: the flow status to clear. The possible values can be obtained by printing flow_consts.status_types

function triggerStatus(table flow_status_type, table status_info, int flow_score, int cli_score, int srv_score)

Set a bit into the flow status bitmap, and trigger an alert.

Parameters

• flow_status_type: the flow status to set. The possible values can be obtained by printing flow_consts.status_types
• status_info: a string message or lua table to associate to this status
• flow_score: the score (a quantitative indicator of the problem) to associate to this status
• cli_score: the score increment on the client host.
• srv_score: the score increment on the server host.

function isStatusSet(int status_key)

Check if a a bit into the flow status bitmap is set.

Return

true if the provided status is set, false otherwise

Parameters

• status_key: the numberic ID of the status, e.g. flow_consts.status_types.status_blacklisted.status_key

function getFullInfo()

Get full information about the flow.

Return

a table with flow information, see Flow::lua

Note

This call is expensive and should be avoided. Use the other API methods when possible.

function isClientUnicast()

Check if the client of the flow is a unicast IP address.

Return

true if the client is unicast, false otherwise

function isServerUnicast()

Check if the server of the flow is a unicast IP address.

Return

true if the server is unicast, false otherwise

function isUnicast()

Check if both the client and the server of the flow are unicast IP addresses.

Return

true if the flow is unicast, false otherwise

function isRemoteToRemote()

Check if both the client and the server are remote hosts.

Return

true if the flow is remote to remote, false otherwise

function isLocalToRemote()

Check if the client is a local host and the server is a remote host.

Return

true if the flow is local to remote, false otherwise

function isRemoteToLocal()

Check if the client is a remote host and the server is a local host.

Return

true if the flow is remote to local, false otherwise

function isLocal()

Check if both the client and the server are local hosts.

Return

true if the flow is local, false otherwise

function isBlacklisted()

Check if the flow is blacklisted.

Return

true if blacklisted, false otherwise

function isTwhOK()

Check if the flow is TCP and the three way handshake is completed.

Return

true if the flow is TCP and the 3WH is completed, false otherwise

function isBidirectional()

Check if the flow has seen packets in both the directions.

Return

true if the flow is bidirectional, false otherwise

function getKey()

Get the unique flow key.

Return

the unique flow key.

function getFirstSeen()

Get the flow start Unix timestamp.

Return

the flow first seen.

function getLastSeen()

Get the Unix timestamp of the last time traffic for the flow was seen.

Return

the flow last seen.

function getDuration()

Get the total duration in seconds of the flow.

Return

the flow duration.

function getPacketsSent()

Get the client to server packets sent.

Return

the packets sent.

function getPacketsRcvd()

Get the client to server packets received.

Return

the packets received.

function getPackets()

Get the total packets seen for the flow.

Return

the total flow packets.

function getBytesSent()

Get the client to server bytes sent.

Return

the bytes sent.

function getBytesRcvd()

Get the client to server bytes received.

Return

the bytes received.

function getBytes()

Get the total bytes seen for the flow.

Return

the total flow bytes.

function getGoodputBytes()

Get the total goodput bytes seen for the flow.

Return

the total goodput flow bytes.

function getClientKey()

Get the unique key of the client.

Return

the client key.

function getServerKey()

Get the unique key of the server.

Return

the server key.

function getnDPICategoryName()

Get the detected nDPI category name of the flow.

Return

the flow nDPI category name.

function getnDPIProtocolName()

Get the detected nDPI protocol name of the flow.

Return

the flow nDPI protocol name.

function getnDPICategoryId()

Get the detected nDPI category ID of the flow.

Return

the flow nDPI category ID.

function getnDPIMasterProtoId()

Get the detected nDPI master protocol ID of the flow.

Return

the flow nDPI master protocol ID.

function getnDPIAppProtoId()

Get the detected nDPI application protocol ID of the flow.

Return

the flow nDPI application protocol ID.

function getDnsQuery()

Get the DNS query of the flow.

Return

the flow DNS query if found, an empty string otherwise.

function getClientCountry()

Get the client country code.

Return

the client country code if detected, nil otherwise.

function getServerCountry()

Get the server country code.

Return

the server country code if detected, nil otherwise.

function getTLSVersion()

Get the TLS version as number.

Return

the TLS version number if detected, 0 otherwise.

function getnDPIMatchPacket()

Get the nDPI matching packet.

Return

the lenght and payload of the packet matching nDPI

function getScore()

Get the total flow score (see flow.setStatus).

Return

the flow score.

function isPassVerdict()

Check if the flow traffic is not blocked.

Return

true if the flow traffic is not blocked, false otherwise.

Note

This requires nEdge.