Skip to main content
Version: 3.2

Cribl Expressions

Native Cribl LogStream function methods can be found under C.*, and can be invoked from any Function that allows for expression evaluations. For example, to create a field that is the SHA1 of a another field's value, you can use the Eval Function with this Evaluate Fields pair:

NameValue Expression
myNewFieldC.Mask.sha1(myOtherField)

Where fields' names contain special characters, you can reference them using the __e['<field‑name‑here>'] convention. For details, see Fields with Non-Alphanumeric Characters.

C.Crypto – Data Encryption and Decryption Functions

C.Crypto.decrypt (method) Crypto.decrypt(value: string): string Decrypt all occurrences of ciphers in the given value. Instances that cannot be decrypted (for any reason) are left intact. @param – value – string in which to look for ciphers. @returns – value with ciphers decrypted.

C.Crypto.encrypt (method) Crypto.encrypt(value: any, keyclass: number, keyId?: string, defaultVal?: string): string Encrypt the given value with the keyId, or with a keyId picked up automatically based on keyclass.

@param {string | Buffer} value – what to encrypt. @param – keyclass – if keyId isn't specified, pick one at the given keyclass. @param – keyId - encryption keyId, takes precedence over keyclass. @param – defaultVal – what to return if encryption fails for any reason; if unspecified, the original value is returned. @returns – if encryption succeeds, the encrypted value; otherwise, defaultVal if specified; otherwise, value.

C.Crypto.createHmac (method) Crypto.createHmac(value: string | Buffer, secret: string, algorithm: string = 'sha256', outputFormat: 'base64' | 'hex' | 'latin1' = 'hex'): string Generates an HMAC that can be added to events, or can be used to validate events that contain an HMAC. (Available in LogStream v.3.1.2+.) @param – value – The data to encrypt, as a string. (When the outputFormat is invalid or undefined, this parameter is returned as the digest, via a Buffer.) @param} – secret – The secret key used to generate the MAC, as a string. @param – algorithm – The hash algorithm used to generate the MAC, as a string. Defaults to 'sha256'. Run openssl list -digest-algorithms toΒ see the list of available algorithms. @param – outputFormat – One of 'base64', 'hex', or 'latin1'. Defaults to 'hex'. @returns – The calculated HMAC digest on success; otherwise, value.

C.Decode – Data Decoding Functions

C.Decode.base64 (method) Decode.base64(val: string, resultEnc?: string): any Performs base64 decoding of the given string. Returns a string or Buffer, depending on the resultEnc value, which defaults to 'utf8'. @param – val – value to base64-decode. @param – resultEnc – encoding to use to convert the binary data to a string. Defaults to 'utf8'. UseΒ 'utf8‑valid' to validate that result is valid UTF8; use 'buffer' if you need the binary data in a Buffer.

C.Decode.gzip (method) Decode.gzip(value: any, encoding?: string): string Gunzip the supplied value. @param – value – the value to gunzip. @param – encoding – encoding of value, for example: 'base64', 'hex', 'utf-8', 'binary'. Default is 'base64'. If data is received as Buffer (from gzip with encoding:'none'), decoding is skipped.

C.Decode.hex (method) Decode.hex(val: string): number Performs hex to number conversion. (Returns NaN if value cannot be converted to a number.) @param – val – hex string to parse to a number (e.g., "0xcafe").

C.Decode.uri (method) Decode.uri(val: string): string Performs URI-decoding of the given string. @param – val – value to URI-decode.

C.Encode – Data Encoding Functions

C.Encode.base64 (method) Encode.base64(val: any, trimTrailEq?: boolean): string Returns a base64 representation of the given string or Buffer. @param – val – value to base64-encode. @param – trimTrailEq – whether to trim any trailing =.

C.Encode.gzip (method) Encode.gzip(value: string, encoding?: string): any Gzip, and optionally base64-encode, the supplied value. @param – value – the value to gzip. @param – encoding – encoding of value, for example: 'base64', 'hex', 'utf-8', 'binary', 'none'. Default is 'base64'. If 'none' is specified, data will be returned as a Buffer.

C.Encode.hex (method) Encode.hex(val: string | number): string Rounds the number to an integer and returns its hex representation (lowercase). If a string is provided, it will be parsed into a number or NaN. @param – val – value to convert to hex.

C.Encode.uri (method) Encode.uri(val: string): string Returns the URI-encoded representation of the given string. @param – val – value to uri encode.

C.env – Environment

C.env (property) env: {[key: string]: string;} Returns an object containing Cribl LogStream's environment variables.

C.Lookup – Inline Lookup Functions

C.Lookup – Exact Lookup (property) Lookup: (file: string, primaryKey?: string, otherFields?: string[], ignoreCase?: boolean) => InlineLookup Returns an instance of a lookup to use inline. Example invocation: C.Lookup('lookup_name.csv', 'IP_field_name_in_lookup_file').match(host)

C.LookupCIDR – CIDR Lookup (property) LookupCIDR: (file: string, primaryKey?: string, otherFields?: string[]) => InlineLookup Returns an instance of a CIDR lookup to use inline.

C.LookupIgnoreCase – Case-insensitive Lookup (property) LookupIgnoreCase: (file: string, primaryKey?: string, otherFields?: string[]) => InlineLookup Returns an instance of a lookup (ignoring case) to use inline. Works identically to C.Lookup, except ignores the case of lookup values. (Equivalent to calling C.Lookup with its fourth ignoreCase? parameter set to true).

C.[LookupRegex](http://google.com) - Regex Lookup (property) LookupRegex: (file: string, primaryKey?: string, otherFields?: string[]) => InlineLookup Returns an instance of a Regex lookup to use inline.

(method) InlineLookup.match(value: string, fieldToReturn?: string): any @param – value – the value to look up. @param – fieldToReturn – name of the lookup file > field to return.

E.g., C.Lookup('lookup-exact.csv', 'foo').match('abc', 'bar') Return the value of field bar in the lookup table if field foo matches abc.

Example 1: C.LookupCIDR('lookup-cidr.csv', 'foo').match('192.168.1.1', 'bar') Return the value of field bar in the lookup table if the CIDR range in foo includes 192.168.1.1.

Example 2: C.LookupCIDR('lookup-cidr.csv', 'cidr').match(hostIP, 'location')

Example 3: C.LookupRegex('lookup-regex.csv', 'foo').match('manchester', 'bar') Return the value of field bar in the lookup table if the regex in foo matches the string manchester.

C.Mask – Data Masking Functions

C.Mask.CC (method) Mask.CC(value: string, unmasked?: number, maskChar?: string): string Check whether a value could be a valid credit card number, and mask a subset of the value. By default, all digits except the last 4 will be replaced with X. @param – value – a string whose digits to mask IFF it could be a valid credit card number. @param – unmasked – number of digits to leave unmasked: positive for left, negative for right, 0 for none. @param – maskChar – a string/char to replace a digit with.

C.Mask.IMEI (method) Mask.IMEI(value: string, unmasked?: number, maskChar?: string): string Check whether a value could be a valid IMEI number, and mask a subset of the value. By default, all digits except the last 4 will be replaced with X. @param – value – a string whose digits to mask IFF it could be a valid IMEI number. @param – unmasked – number of digits to leave unmasked: positive for left, negative for right, 0 for none. @param – maskChar – a string/char to replace a digit with.

C.Mask.isCC (method) Mask.isCC(value: string): boolean Checks whether the given value could be a valid credit card number, by computing the string's Lunh's checksum modulo 10 == 0. @param – value – a string to check for being a valid credit card number.

C.Mask.isIMEI (method) Mask.isIMEI(value: string): boolean Checks whether the given value could be a valid IMEI number, by computing the string's Lunh's checksum modulo 10 == 0. @param – value – a string to check for being a valid IMEI number

C.Mask.luhn (method) Mask.luhn(value: string, unmasked?: number, maskChar?: string): string Check that value Lunh's checksum mod 10 is 0, and mask a subset of the value. By default, all digits except the last 4 will be replaced with X. If the value's Lunh's checksum mod 10 is not 0, then the value is returned unmodified. @param – value – a string whose digits to mask IFF the value's Lunh's checksum mod 10 is 0. @param – unmasked – number of digits to leave unmasked: positive for left, negative for right, 0 for none. @param – maskChar – a string/char to replace a digit with.

C.Mask.LUHN_SUB (property) Mask.LUHN_SUB: any

C.Mask.luhnChecksum (method) Mask.luhnChecksum(value: string, mod?: number): number Generates the Luhn checksum (used to validate certain credit card numbers, IMEIs, etc.). By default, the modΒ 10 of the checksum is returned. Pass mod = 0 to get the actual checksum. @param – value – a string whose digits you want to perform the Lunh checksum on. @param – mod – return checksum modulo this number. If 0, skip modulo. Default is 10.

C.Mask.md5 (method) Mask.md5(value: string, len?: string | number): string Generate MD5 hash of a given value. @param – value – compute the hash of this. @param – len – length of hash to return: 0 for full hash, a +number for left or a -number for right substring. If a string is passed it's length will be used.

C.Mask.random (method) Mask.random(len?: string | number): string Generates a random alphanumeric string. @param – len – a number indicating the length of the result; or, if a string, use its length.

C.Mask.REDACTED (property) Mask.REDACTED: string The literal 'REDACTED'.

C.Mask.repeat (method) Mask.repeat(len?: string | number, char?: string): string Generates a repeating char/string pattern, e.g., XXXX. @param – len – a number indicating the length of the result; or, if a string, use its length. @param – char – pattern to repeat len times.

C.Mask.sha1 (method) Mask.sha1(value: string, len?: string | number): string Generate SHA1 hash of given value. @param – value - compute the hash of this. @param – len - length of hash to return: 0 for full hash, a +number for left, or a -number for right. substring. If a string is passed, its length will be used

C.Misc – Miscellaneous Utility Functions

C.Misc.zip() (method) Misc.zip(keys: string[], values: any[], dest?: any): any Set the given keys to the corresponding values on the given dest object. If dest is not provided, a new object will be constructed. @param – keys – field names corresponding to keys. @param – values – values corresponding to values. @param – dest – object on which to set field values. @returns – object on which the fields were set.

E.g., people = C.Misc.zip(titles, names) Sample data: titles=['ceo', 'svp', 'vp'], names=['foo', 'bar', 'baz'] Create an object called people, with key names from elements in titles, and with corresponding values from elements in names. Result: "people": {"ceo": "foo", "svp": "bar", "vp": "baz"}

C.Net – Network Functions

C.Net.cidrMatch() (method) Net.cidrMatch(cidrIpRange: string, ipAddress: string): boolean Determines whether the supplied IPv4 ipAddress is inside the range of addresses identified by cidrIpRange. For example: C.Net.cidrMatch ('10.0.0.0/24', '10.0.0.100') returns true. @param – cidrIpRange – IPv4 address range in CIDR format. E.g., 10.0.0.0/24. @param – ipAddress – The IPv4 IP address to test for inclusion in cidrIpRange.

C.Net.isIpV4AllInterfaces() (method) Net.isIpV4AllInterfaces(value: string): boolean Determine if the value supplied is the IPv4 all-interfaces address, typically used to bind to all IPv4 interfaces – i.e., '0.0.0.0'. (Available in LogStream v.3.1.2+.) @param – value – the IP address to test.

C.Net.isIpV6AllInterfaces() (method) Net.isIpV6AllInterfaces(value: string): boolean Determine if the value supplied is an IPv6 all-interfaces address, typically used to bind to all IPv6 interfaces – one of: '::', '0:0:0:0:0:0:0:0', or '0000:0000:0000:0000:0000:0000:0000:0000'. (Available in LogStream v.3.1.2+.) @param – value – the IP address to test.

C.Net.ipv6Normalize() (method) Net.ipv6Normalize(address: string): string Normalize an IPV6 address based on RFC draft-ietf-6man-text-addr-representation-04. @param – address – the IPV6 address to normalize.

C.Net.isPrivate() (method) Net.isPrivate(address: string): string Determine whether the supplied IPv4 address is in the range of private addresses per RFC1918. @param – address – address to test.

C.os – System Functions

C.confVersion Returns Cribl LogStream config version.

C.os.hostname() Returns hostname of the system running this Cribl LogStream instance.

C.Schema – Schema Functions

C.Schema() (property) Schema: (id: string) => SchemaValidator (method) SchemaValidator.validate(data: any): boolean Validates the given object against the schema. @param – data – object to be validated. @returns – true when schema is valid; otherwise, false.

Example: C.Schema('schema1').validate(myField) will validate if myField object conforms to schema1.

See Schema Library for more details.

C.Secret – Secrets‑Management Functions

C.Secret() (method) Secret(id: string, type: 'keypair') => IPairSecret (method) Secret(id: string, type: 'text') => ITextSecret (method) Secret(id: string, type: 'credentials') => ICredentialsSecret (method) Secret: (id: string, type?: string): ISecret Returns a secret matching a specified ID. @param id – ID of the secret. @param type – optional type of the secret. @returns the specified secret.

Example: C.Secret('victorias', 'text') will return a text secret with ID 'victorias' (or undefined if no such secret exists).

See Securing > Secrets for more details.

C.Text – Text Functions

C.Text.entropy() (method) Text.entropy(bytes: any): number Computes the Shannon entropy of the given buffer or string. @param – bytes – value to undergo Shannon entropy computation. @returns – the entropy value; or -1 in case of an error.

C.Text.hashCode() (method) Text.hashCode(val: string | Buffer | number): number Computes hashcode (djb2) of the given value. @param – val - value to be hashed. @returns – hashcode value.

C.Text.isASCII() (method) Text.isASCII(bytes: any): boolean Checks whether all bytes or chars are in the ASCII printable range. @param – bytes – value to check for character range. @returns – true if all chars/bytes are within ASCII printable range; otherwise, false.

C.Text.isUTF8() (method) Text.isUTF8(bytes: any): boolean Checks whether the given Buffer contains valid UTF8. @param – bytes – bytes to check. @returns – true if bytes are UTF8; otherwise, false.

C.Text.parseWinEvent (method) C.Text.parseWinEvent(xml: string, nonValues?: string[]): any Parses an XML string representing a Windows event into a compact, prettified JSON object. Works like C.Text.parseXml, but with Windows events, produces more-compact output. ForΒ a usage example, seeΒ Reducing Windows XML Events. @param – xml – an XML string; or an event field containing the XML. @param – nonValues – array of string values. Elements whose value equals any of the values in this array will be omitted from the returned object. DefaultsΒ to ['-'], meaning that elements whose value equals - will be discarded. @returns – an object representing the parsed Windows Event; or undefined if the input could not be parsed.

C.Text.parseXml (method) C.Text.parseXml(xml:string, keepAttr?:boolean, keepMetadata?:boolean, nonValues?:string[]): any Parses an XML string and returns a JSON object. Can be used with Eval Function to parse XML fields contained in an event, or with ad hoc XML. @param – xml – XML string, or an event field containing the XML. @param – keepAttr – whether or not to include attributes in the returned object. Defaults to true. @param – keepMetadata – whether or not to include metadata found in the XML. TheΒ keepAttr parameter must be set to true for this to work. Defaults to false. (Eligible metadata includes namespace definitions and prefixes, and XML declaration attributes such as encoding, version, etc.) @param – nonValues – array of string values. Elements whose value equals any of the values in this array will be omitted from the returned object. DefaultsΒ to [] (empty array), meaning discard no elements. @returns – an object representing the parsed XML; or undefined if the input could not be parsed. AnΒ input collection of elements will be parsed into an array of objects.

C.Text.relativeEntropy() (method) Text.relativeEntropy(bytes: any, modelName?: string): number Computes the relative entropy of the given buffer or string. @param – bytes – Value whose relative entropy to compute. @param – modelName – Optionally, override the default $CRIBL_HOME/data/lookups/model_relative_entropy_top_domains.csv model used to test the input. Create a custom lookup file with the same column and value structure as the default, and store it in the same path, as model_relative_entropy_<custom‑name>.csv. To reference it, pass your <custom‑name> substring as the modelName parameter. @returns – The relative entropy value, or -1 in case of an error.

When using modelName in a distributed deployment, the corresponding paths are $CRIBL_HOME/groups/<worker–group‑name>/data/lookups/. Creating your custom lookup file via LogStream's UI will automatically set the appropriate paths.

C.Time – Time Functions

C.Time.adjustTZ() (method) Time.adjustTZ(epochTime: number, tzTo: string, tzFrom?: string): number Adjust a timestamp from one timezone to another. @param – epochTime – UNIX epoch time. @param – tzTo – timezone to adjust to. @param – tzFrom – optional timezone of the timestamp. @returns – the adjusted timestamp, in UNIX epoch time (ms).

C.Time.clamp() (method) Time.clamp(date, earliest, latest, defaultDate?): number Constrains an event's parsed timestamp to realistic earliest and latest boundaries. @param – date – Timestamp originally parsed from event, in UNIX epoch time (ms) or JavaScript Date format. @param – earliest – earliest allowable timestamp, in UNIX epoch time (ms) or JS Date format. @param – latest – latest allowable timestamp, in UNIX epoch time (ms) or JS Date format. @param – defaultDate – optional default date, in UNIX epoch time (ms) or JS Date format, to substitute for values outside the earliest or latest boundaries.

C.Time.strftime() (method) Time.strftime(date: number | Date, format: string, utc?: boolean): string Format a Date object or number as a time string, using strftime specifier. @param – date – Date object or number (seconds since epoch) to format. @param – format – specifier to use to format the date. @param – utc – whether to output the time in UTC, rather than in local timezone. @returns – representation of the given date.

C.Time.strptime() (method) Time.strptime(str: string, format: string, utc?: boolean, strict?: boolean): Date Extract time from a string using strptime specifier. @param – str – string to parse to a timestamp (see strict flag). @param - format – strptime specifier. @param – utc – whether to interpret times as UTC, rather than as local time. @param – strict – whether to return null if there are any extra characters after timestamp. @returns – a parsed Date object, if successful; otherwise, null if the specifier did not match.

C.Time.timestampFinder() (method) Time.timestampFinder(utc?: boolean).find(<source‑field>): AutoTimeParser Extract time from the specified <source‑field>, using the same algorithm as the AutoΒ Timestamp Function and the Event Breaker Function. @param – utc – whether to output the time in UTC, rather than in local timezone. @param – <source‑field> – the field in which to search for the time. @returns – representation of the extracted time.

C.vars – Global Variables

See Global Variables Library for more details.

C.version – Cribl LogStream Version

(property) version: string Cribl LogStream Version.