Skip to main content

Function Library — Text

C.Text covers text analysis and structured-text parsing for JavaScript scripts.

FunctionSignatureReturns
entropy(value)Shannon entropy in bits per byte
relativeEntropy(value, model)Divergence from a reference character model
hashCode(value)A 32-bit signed integer hash
isASCII(value)true where every byte is printable ASCII
isUTF8(value)true where the value is valid UTF-8
parseXml(xml, keepAttr, keepMetadata, nonValues)An object built from the XML
parseWinEvent(xml, nonValues)An object built from a Windows Event XML record
_WIN_EVENT_NON_VALUES—The default list of placeholder values parseWinEvent() discards

Details​

Entropy​

entropy() returns the Shannon entropy of the value in bits per byte, from 0 for a single repeated character up to 8. High entropy in a field that should hold readable text is the usual signal for encoded or encrypted content, and high entropy in a domain name is the usual signal for a domain-generation algorithm.

An empty value returns 0. A missing or null argument returns -1, which is outside the valid range and so distinguishable from any real measurement.

Flag a suspicious domain...

- script:
    lang: js
    source: |
        const h = C.Text.entropy(__e['dns.question.name']);
        if (h >= 0) {
          __e['dns.entropy'] = h;
          __e.suspicious = h > 4;
        }

relativeEntropy() compares the value against a reference character distribution rather than measuring it in isolation, which separates an unusual-looking but legitimate string from a generated one more reliably than raw entropy. It returns -1 where the model cannot be loaded.

Hashing​

hashCode() returns a 32-bit signed integer, suitable as a bucket key for sampling or partitioning.

warning

This is a djb2 hash, not Java's String.hashCode(). Values will not match those produced by a JVM, so do not use it to reproduce a hash computed elsewhere. It is also not a cryptographic hash — for that use the digest functions on the Masking page.

A missing or null argument hashes the literal text undefined or null rather than returning a sentinel, so guard the input where the distinction matters.

Encoding Tests​

isASCII() tests for printable ASCII — bytes 0x20 through 0x7E. Tabs, carriage returns and newlines are all outside that range, so a multi-line value returns false. isUTF8() tests for valid UTF-8 encoding. Both return false for a missing or null argument.

XML​

parseXml() converts an XML document into an object:

  • Attributes become keys prefixed with an underscore. Pass false as the second argument to drop them.
  • Text content sits under __text where the element also has attributes or child elements; an element with neither collapses to a plain string.
  • Repeated sibling elements become an array.
  • Values listed in the fourth argument are discarded rather than stored, which is how placeholder markers are removed.

Malformed XML, or nesting deeper than 1,000 levels, returns undefined.

Windows Events​

parseWinEvent() applies the same conversion but flattens the Windows Event Log structure that parseXml() would otherwise leave verbose: the Data elements under EventData and UserData become direct keys named by their Name attribute.

Its second argument lists the placeholder values to discard, defaulting to ["-"] — the value _WIN_EVENT_NON_VALUES holds. Windows also writes 0x0 as a placeholder in several fields, so pass both where you want them removed.

Parse a raw Windows Event record, discarding both placeholder forms...

- script:
    lang: js
    source: |
        const parsed = C.Text.parseWinEvent(__e._raw, ['0x0', '-']);
        if (parsed !== undefined) {
          __e.winlog = parsed;
        }

For routine Windows Event ingestion, prefer the XML processor and the dedicated device types — this function is for cases where the record arrives inside a field of a larger event.