NSS Feed Output Format

This article provides guidelines and information about the fields that you can include in the NSS output for web logs and for firewall logs. Enter the desired fields in the Field Output Format field.

Guidelines

Following are some guidelines to get you started. Note that the applicability of the recommendations may vary based on the capabilities of your SIEM.

  • An NSS can include up to 50 fields per transaction.
  • The fields must be in the order you want them to appear in the output. Consider using name-value pairs if your SIEM can support it. Some SIEMs, such as Splunk, can automatically parse name-value formats and auto-detect field names regardless of the order.
  • The Zscaler service hex encodes all non-printable ASCII characters that are in URLs when it sends the logs to the NSS. Any URL character that is less than and equal to 0x20 or equal to and above 0x7F will be encoded as %HH. This ensures that your SIEM will be able to parse the URLs in case they contain control characters. For example, a \n character in a URL is encoded as 0A, and a space is encoded as %20.
  • Use tabs as field delimiters. Avoid using commas and spaces because they could be in some output values. For example, department names might contain spaces or URLs might contain commas. If you must use commas or other characters as delimiters, enter those characters in the Feed Escape Character field when you define an NSS feed. The service will encode the characters that you enter in this field. For example, if you enter a comma, the service will encode it as %2C.
  • The following special characters generate control outputs:
    \t = Tab
    \n = Newline
    \r = Carriage Return
  • You do not need to add \n after the last field to indicate that it is the last entry. Zscaler automatically adds a blank line (line feed) after the last field.
  • The field names specified will be substituted by the corresponding value when NSS sends logs to the SIEM.
    • %s{<fieldname>} will display the string name
      Example: %s{time}
    • %d{<fieldname>} will print a number in decimal format
      Example: %d{yyyy}
    • %x{<fieldname>} will print a number in hexadecimal (base-16) format
      Example: %x{recordid}
      Following are some examples:
      • "%s{time}","%s{login}","%s{proto}"\n will result in a log entry that looks like: “Mon Sep 10 10:50:46 2012”,”jdoe@example.com”, “HTTP”
      • %s{time}\t%s{login}\t%s{proto}\n will result in a log entry that looks like: 
        Mon Sep 10 10:50:46 2012jdoe@example.comHTTP
  • Field names are case-sensitive.
  • Special characters must be escaped with \{} or % . For example: %s{login}: \{%s{hostname}\} will generate a log entry similar to the following: user@example.com: {www.zscaler.com}
  • You can optionally include static text strings in the output. For example: %s{time} GMT will produce: Mon Sep 10 10:50:46 2012 GMT
  • You can also specify the padding if you want constant width strings. For instance:
    • %d{hh}:%d{mm}:%d{ss} will produce 21:5:0
    • %02d{hh}:%02d{mm}:%02d{ss} will produce 21:05:00
  • % must be escaped with another %
  • You can break up a long output format into multiple lines for readability. 
    For example, the following format string: 
    %s{time}\t%s{proto}\t%s{url}\t%s{login}\t%s{dept}\t%s{urlcat}\t%s{urlsupercat}\t%s{urlclass}\t%s{location}\t%s{ua}\n
    Can be specified as:
    %s{time}\t%s{proto}\t%s{url}\t
    %s{login}\t%s{dept}\t
    %s{urlcat}\t%s{urlsupercat}\t%s{urlclass}\t
    %s{location}\t%s{ua}\n

Field Categories

The following categories provide fields you can include in the NSS output: