Compute Functions

These functions perform some computations on parsed values before setting to the event attributes.

1. add

2. calculateDomainEntropy

3. calculateLatency

4. compIntfSecVal

5. combineMsgId

6. compare

7. decodeBase64

8. decodeHex

9. divide

10. normalizeMAC

11. resolveDNSName

12. scale

13. shiftTimeSec

14. swap

15. unzip

16. URLDecode

add

Description: This function adds two numbers and stores the sum in an event attribute.

Syntax:

<setEventAttribute attr="Arg3">
      add(Arg1, Arg2)
</setEventAttribute>

Arg1: Variable storing the first value.

Arg2: Variable storing the second value.

Arg3: Variable where the sum of Arg1 and Arg2 would be saved.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<setEventAttribute attr="totBytes">
      add($sentBytes, $recvBytes)
</setEventAttribute>

Given sentBytes = 10 and recvBytes = 30, this function sets totBytes = 40.

calculateDomainEntropy

Description: This function calculates entropy of the event field using the Shannon entropy function. Entropy indicates how random the value looks based on words in an English dictionary. Names like "asdfjklqwerty.org", "8xhj9vzk.biz" have high entropy.

Syntax:

<setEventAttribute attr="Arg2">
        calcDomainEntropy(Arg1)
</setEventAttribute>

Arg1: Variable whose entropy would be calculated.

Arg2: Variable where the domain entropy of Arg1 would be saved.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

The following function calculates the destName field and sets it to domainEntropy field.

<setEventAttribute attr="domainEntropy">
        calcDomainEntropy($destName)
</setEventAttribute>

calculateLatency

Description: This function compares 2 timestamps and calculate the latency (difference) between the two. The values are in seconds.

Syntax:

<setEventAttribute attr="Arg3">
     calculateLatency(Arg1, Arg2)
</setEventAttribute>

Arg1: Variable storing first time stamp.

Arg2: Variable storing second time stamp.

Arg3: Variable where (Arg1-Arg2) would be saved.

If Arg1 is later than Arg2, then Arg3 in set to seconds. Otherwise, Arg3 is set to 0.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

The following function computes the latency between phRecvTime and deviceTime. If phRecvTime is later than deviceTime, the latency in set to seconds. Otherwise, latency is set to 0.

<setEventAttribute attr="latency">
     calculateLatency($phRecvTime, $deviceTime)
</setEventAttribute>

compIntfSecVal

Description: This function is specific for Cisco ASA Firewalls where each interface has a Security Level and FortiSIEM knows about it by discovering the configuration from Cisco ASA firewalls. This function compares the Security Level of srcIntf and destIntf. The result may be "LESS", "GREATER" or "EQUAL".

Syntax:

<setEventAttribute attr="Arg3">
           compIntfSecVal(Arg1, Arg2)
</setEventAttribute>

Arg1: Variable storing first interface name.

Arg2: Variable storing second interface name.

Arg3: Variable where security level comparison result is saved.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<setEventAttribute attr="_result">
           compIntfSecVal($srcIntf, $destIntf)
</setEventAttribute>

combineMsgId

Description: This function combines two or more strings into one string. Strings need to double quoted.

Syntax:

<setEventAttribute attr="ArgN">
           combineMsgId(Arg1,Arg2,Arg3, …)
</setEventAttribute>

Arg1: First string – can be a Variable storing the string value or a specific string with double quotes, e.g. "PH-".

Arg2: Second string – can be a Variable storing the string value or a specific string with double quotes, e.g. "PH-".

…

ArgN: Variable storing the concatenated result.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<setEventAttribute attr="eventType">
           combineMsgId("PH-", $_evIdPrefix, "-", $_evIdSuffix)
</setEventAttribute>

Given

_evIdPrefix: prefix

_evIdSuffix: suffix

This function sets eventType to PH-prefix-suffix.

compare

Description: This function compares 2 numbers and returns strings GREATER, EQUAL or LESS.

Syntax:

<setEventAttribute attr="Arg3">compare(Arg1, Arg2)</setEventAttribute>

Arg1: Variable storing the first numeric value.

Arg2: Variable storing the second numeric value.

Arg3: Variable storing the comparison result.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

In the following example:

• If confidence > 66 then eventSeverity will be set to 9.

• If confidence is between 33 and 66 then eventSeverity will be set to 5.

• else eventSeverity will be set to 1.

<when test="exist confidence">
  <setEventAttribute attr="_result">compare($confidence, 66)</setEventAttribute>
  <choose>
     <when test="$_result = 'GREATER'">
            <setEventAttribute attr="eventSeverity">9</setEventAttribute>
    </when>
    <otherwise>
            <setEventAttribute attr="_result">compare($confidence, 33)</setEventAttribute>
            <when test="$_result = 'GREATER'">
                 <setEventAttribute attr="eventSeverity">5</setEventAttribute>
            </when>
            <setEventAttribute attr="eventSeverity">1</setEventAttribute>
    </otherwise>
  </choose>
</when>

decodeBase64

Description: This function decodes a base64 encoded string.

Syntax:

<setEventAttribute attr="Arg2">decodeBase64(Arg1)</setEventAttribute>

Arg1: Variable storing the base64 encoded string.

Arg2: Variable storing the decoded value.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<setEventAttribute attr="msg">decodeBase64($_msg)</setEventAttribute>

Input:

_msg: bWVzc2FnZQ==

Output:

msg: message

decodeHex

Description: This function converts UTF-8 string in HEX form to its original form.

Syntax:

<setEventAttribute attr="Arg2">decodeHex(Arg1)</setEventAttribute>

Arg1: Variable storing the UTF-8 string in HEX form.

Arg2: Variable storing the decoded string.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<setEventAttribute attr="command">decodeHex($_command)</setEventAttribute>

Input:

_command: 61776B007B7072696E742024312C24332C24342C24362C2431327D

Output:

command: touch .test_file2

divide

Description: This function returns the result of division of two numbers.

Syntax:

<setEventAttribute attr="Arg3">
      compare(Arg1, Arg2)
</setEventAttribute>

Arg1: Variable storing the first numeric value.

Arg2: Variable storing the second numeric value.

Arg3: Variable storing the division result.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<setEventAttribute attr="memUtil">
     divide($usedMem, $totalMem)
</setEventAttribute>

Input:

usedMem: 1000

totalMem: 10000

Output:

memUtil: 0.1

normalizeMAC

Description: This function normalizes MAC address string to the form 01:23:45:67:89:ab

Syntax:

<setEventAttribute attr="Arg2">
         normalizeMAC(Arg1)
</setEventAttribute>

Arg1: Variable storing the unnormalized MAC address.

Arg2: Variable storing the normalized MAC address.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<setEventAttribute attr="hostMACAddr">
         normalizeMAC($_mac)
</setEventAttribute>

Input:

_mac: 1-2-3-4-ab-c

Output:

hostMACAddr: 01:02:03:04:ab:0c

resolveDNSName

Description: This function resolves a host name or FQDN to IP address. The resolution is done first by looking up FortiSIEM CMDB. If it fails and the variable use_dns_lookup is set to yes in phoenix_config.txt, then DNS Server, defined on the host, is used. Note that this may result in event latency. If use_dns_lookup is set to no, then DNS lookup is not attempted.

Syntax:

<setEventAttribute attr="Arg2">
      resolveDNSName(Arg1)
</setEventAttribute>

Arg1: Variable storing the host name or FQDN.

Arg2: Variable storing the resolved IP Address.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<setEventAttribute attr="destIpAddr">
      resolveDNSName($destName)
</setEventAttribute>

CMDB   Host1 -> 10.1.1.1

Input:

destName: Host1

Output:

destIpAddr: 10.1.1.1

scale

Description: This function calculates the product of two or more numbers.

Syntax:

<setEventAttribute attr="Arg3">
    scale(Arg1, Arg2)
</setEventAttribute>

Arg1: Variable storing the value to be scaled.

Arg2: Scaling factor (integer).

Arg3: Variable where the result is stored.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<setEventAttribute attr="durationMSec">
    scale($_durationSec, 1000)
</setEventAttribute>

Input:

_durationSec = 5

Output:

durationMSec = 5000

shiftTimeSec

Description: This function shifts time backward by a duration.

Syntax:

<setEventAttribute attr="Arg6">
    scale(Arg1, Arg2,Arg3,Arg4,Arg5)
</setEventAttribute>

Arg1: Variable storing the month value (1-12 in MM format).

Arg2: Variable storing the day value (1-31 in DD format).

Arg3: Variable storing the year value (YYYY format).

Arg4: Variable storing the time value (HH:MM:SS format).

Arg5: Variable storing the duration to be shifted in seconds.

Arg6: Variable where the result is stored as Unix epoch.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<setEventAttribute attr="logonTime">
     shiftTimeSec($_mon, $_day, $_year, $_time, $_durationSec)
</setEventAttribute>

Input:

_mon: 1

_day: 1

_year: 2000

_time: 01:00:10

_durationSec: 10

Output:

logonTime: epoch int of "01:00:00 01/01/2000"

swap

Description: This function swap the values of 2 variables.

Syntax:

<swap>$srcIntfName, $destIntfName</swap>

Arg1: Variable storing the first value.

Arg2: Variable storing the second value.

After swap, Arg1 has Arg2's old value and Arg2 has Arg1's old value.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<swap>$srcIntfName, $destIntfName</swap>

Before execution:

srcIntfName: Ethernet1

destIntfName: Ethernet2

After execution:

srcIntfName: Ethernet2

destIntfName: Ethernet1

unzip

Description: This function unzips a zip-formatted string.

Syntax:

<setEventAttribute attr="Arg2">unzip($Arg1)</setEventAttribute>

Arg1: Variable storing the zip-formatted string.

Arg2: Variable storing the unzipped string.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<setEventAttribute attr="msg">unzip($_zipMsg)</setEventAttribute>

Assuming _zipMsg field is zipped string, after execution, msg is set to the unzipped string.

URLDecode

Description: This function decodes URL-encoded string.

Syntax:

<setEventAttribute attr="httpFullRequest">
        URLDecode($httpFullRequest)
</setEventAttribute>

Arg1: Variable storing the URL-encoded string.

Arg2: Variable storing the decodes string.

Note: Variable can be a local variable or a FortiSIEM event attribute.

Example:

<setEventAttribute attr="httpFullRequest">
        URLDecode($httpFullRequest)
</setEventAttribute>

Suppose

httpFullRequest: https://www.example.com/search?q=my%20search%20term

After execution:

httpFullRequest: https://www.example.com/search?q=my search term