USM Appliance™

Default Functions Used in the USM Appliance Plugins

The USM Appliance Server must receive normalized events in a predefined format. USM Appliance provides a number of built-in functions you can used to convert the extracted data obtained from matching the regular expressions to the format expected in normalized USM Appliance event fields.

For example, time and date in USM Appliance is in the format of YYYY-MM-DD HH:MM:SS (for example, 2013-12-31 22:57:00), but different data sources may use different formats for time and date. You can use the normalize_date() function, which simplifies the process of normalizing events, by converting different time formats into the format accepted by the server.

Another function often used is resolv(), which translates hostnames into IPv4 addresses by performing DNS queries.




The following table provides a list of the built-in USM Appliance functions.

USM Appliance default plugin functions
Function Description
$CONCAT($val1, $val2, chars) Concatenates the values and characters passed as parameters
geoip_getCity(ipaddr) Gets the corresponding city according to the built-in GeoIP database.
geoip_getCountry(addr) Gets the corresponding country according to the built-in GeoIP database.
geoip_getCountryName(addr) Get country name from IP address.
geoip_getLatitude(addr) Get latitude from IP address.
geoip_getLongitude(addr) Get longitude from IP address.
geoip_getMetroCode(addr) Get metro code from IP address.
geoip_getPostalCode(addr) Get postal code from IP address if possible.
geoip_getRegionCode(addr) Get region code from IP address.
geoip_getRegionName(addr) Get region name from IP address.
geoip_getTimeZone(addr) Get timezone of the location this IP address is in.
resolv(host) Returns a IP representation of the host. The lookup is first performed on a local copy of the asset database on the sensor, then the configured resolver (usually DNS) is tried. A host not found will result in a value of
normalize_protocol(protocol) Returns protocol information.
normalize_date_american(datestring) Returns a UNIX epoch date.
normalize_date(datestring) Returns a UNIX epoch date.
upper(string) Returns a uppercase version of the string supplied.
sanitize(string) Converts occurrences of "\n“ into "\r“.
hextoint(string) Returns a int representation of a hex string.
translate(string) Returns the right side value from the translation table, where the left side is "string“. For details, see The Translation Section in Plugin Fundamentals.
translate2($value, $translation_table) Returns the right side value from the translation table named "translation_table", where the left side is the value contained in $value.