Introduction to Cylance SYSLOGs
Why Syslogs?
Cylance offers two main ways of getting information about your Cylance instance. You can either use the CylancePROTECT REST API or Cylance syslogs. It may be appealing to go with the familiarity of REST APIs, however, syslogs offer a key advantage over the REST API. You don’t need to constantly poll for updates with syslogs. Instead, syslogs push to you over a TCP port, which can allow you to get information about your Cylance instance streamed directly to you.
The Standard we follow
Cylance syslogs follow the RFC-5424 standard. You can read up on it to learn the specifics of the standard, but a summary is provided here.
The basic format of an RFC-5424 syslog is shown below:
<PRI>VERSION TIMESTAMP HOSTNAME APPNAME - PROCID [STRUCTURED_DATA] MESSAGE
PRI: A number 1 to 3 digits long that uniquely identifies the facility and severity of the syslog.
Version: The version number of the syslog protocol specification.
TIMESTAMP: A timestamp of when the syslog was sent.
HOSTNAME: The hostname of the computer sending the syslog.
APPNAME: The name of the application sending the syslog.
PROCID: Used to identify the process name or ID associated with the syslog system.
STRUCTURED_DATA: More information on this is provided later in the blog.
MESSAGE: The main message of the syslog.
Many of these fields are optional and can be replaced by a ‘-‘ representing a nil value. The exceptions are pri and version. In Cylance syslogs, the procid field is left as a ‘-‘.
The Standard: Structured Data
Structured data (SD) is used to add meta information to the syslog. It should follow the following standard to be easily parsable.
[foo@bar field1="value1" field2="value2"][bar@baz field1="value2"]
foo@bar and bar@baz are identifiers within their respective SD entries which are enclosed by square brackets. The fields and values are relevant only to the SD entry that they are in. For example, field1="value1" in the foo@bar entry is separate from the field1="value2" in the bar@baz entry.
There must be no space between the opening square bracket and the identifier. There must also be no spaces in between SD entries, otherwise, the entries after the space will be interpreted as part of the message. You don’t need to worry about this part, though, because Cylance will take care of that for you generating the syslogs.
Cylance syslogs use the SD field to place the custom token as the identifier of the SD. There are no field value pairs in the SD field of Cylance syslogs.
Certain characters, while allowed by the Cylance Protect console, make the SD identifiers and field names of the syslogs more difficult to parse. These characters include blank spaces, square brackets ([]), quotes ("), or equal signs (=). We recommend you avoid these characters in your custom token.
How to get Syslogs from your CylancePROTECT Instance
So how do you actually get these syslogs? Navigate to your CylancePROTECT console and use the gears icon to navigate to Settings > Application.
On this page, you should find the following section which configures your console’s syslog settings.
Here, you can set everything you need to get syslogs working for you. Select which types of syslogs you would like to receive by selecting the check boxes at the top. For the protocol, we will be using TCP. For ease of testing, you may want to leave the TLS/SSL unselected or your syslog will arrive encrypted. The IP/Domain and the Port are the IP/Domain and port for your server which will be receiving these syslogs. You can set the Severity and Facility to whatever you think appropriate for your use case. Finally, put in a custom token. Remember to try to avoid troublesome characters such as spaces, equal signs, quotes, and square brackets!
Getting Syslogs to your Development environment
Syslogs must be sent to an IP address/port open to protect.cylance.com. For a typical production server open to inbound traffic (domain/ip open), this is not an issue, however, how do I get syslogs sent to my localhost development environment that is behind a firewall? Your options are:
Develop on a server with a public IP address/domain - outside the firewall
Open a port on your network and port forward it – talk to your firewall admin
Use a network forwarding program such as https://ngrok.com/ that allows you to forward inbound/outbound TCP traffic from your localhost machine to a public access point.
Forwarding TCP Syslogs using NGROK
Set up an account with Ngrok and install it on your machine. You will need to authenticate it with your Ngrok auth token, but once you have Ngrok all set up, you can run the following command to receive syslogs.
ngrok tcp --region=us <LOCAL_PORT>
Where <LOCAL_PORT> is the port on your local machine where you’ll be getting incoming syslogs. In the example below, this is 20514.
Note that this command will provide you a different domain and port (the parts in the red box in the above image) every time. This means that you must change the IP/Domain and Port fields in your CylancePROTECT console every time, shown in the below image.
If you would like to have a constant domain and port, you must upgrade to the paid version of Ngrok. Then, you can run the following command.
ngrok tcp --region=us --remote-addr= <NGROK_ADDRESS>:<NGROK_PORT> <LOCAL_PORT>
The <NGROK_ADDRESS> and <NGROK_PORT> are assigned to you by Ngrok and you can get them from the Ngrok Dashboard and then clicking on “Reserve Address” in the “Reserved TCP Addresses” section.
You must also fill in the IP/Domain and the Port information in the CylancePROTECT syslog settings with the <NGROK_ADDRESS> and <NGROK_PORT>, respectively.
With all this set up, you can click on the “Test Connection” button and you should receive the following syslog on your local machine at the <LOCAL_PORT> you specified earlier.
<118>1 2022-07-21T15:12:11.769142Z sysloghost CylancePROTECT - - [CUSTOM_TOKEN] Test Connection Message.
You can also test your syslogs configuration by changing various settings in your CylancePROTECT console which will trigger Audit Log syslog events.
Syslogs are an incredibly useful way of getting information from Cylance because of their push rather than pull nature. In other words, as long as you’re listening for any incoming syslogs, you'll be up to date on any changes to your Cylance system. In my next blog, I’ll be going into more detail on how to extract meaningful information from syslogs once you have received them, so stay tuned!
