How to Install and Configure VMware Carbon Black Cloud Syslog Connector

1. Log in to the Linux server that the syslog connector is being installed on using SSH.
   Note: For information about connecting through SSH, reference Securing networks .
2. Validate the server is up to date by running sudo yum update.
3. A repository must be added to install PIP, as PIP may not be in the core operating system repositories. Type sudo yum install epel-release and then press Enter.
   
   Note: If epel-release is not found, add the repository by running the following commands:

   • sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-[VERSION].noarch.rpm
   • sudo rpm -ql epel-release

   Ensure that the [VERSION] matches the release of Red Hat Enterprise Linux or CentOS that you are running:

   • If running Red Hat Enterprise Linux 8 or CentOS 8: sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
   • If running Red Hat Enterprise Linux 7 or CentOS 7: sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
4. Type Y and then press Enter.
5. Install PIP by typing sudo yum install python3 and then pressing Enter.
   
6. Install Python3 build utilities by typing sudo yum install gcc python3-devel and then pressing Enter.
   
7. Update all packages within the host operating system by typing sudo yum update and then pressing Enter.
   

1. Log in as an account with sudo access on the server that the connector is being installed on.
2. Open Terminal.
3. Type pip3 install cbc-syslog and then press Enter.
   
   Note:

   • This example leverages PIP3 on CentOS 8. The command may slightly vary depending on the version of Python, and as a result, the version of PIP that is being used.
   • If installing without root, the default install location is:
     • /usr/lib/python{version}/site-packages/cbc_syslog
   • If installing with root, the default install location is:
     • /usr/local/lib/python{version}/site-packages/cbc_syslog

An administrator must configure both VMware Carbon Black Cloud and the Syslog Connector itself. Click the appropriate process for more information.

VMware Carbon Black Cloud

VMware Carbon Black Cloud must be configured to use the syslog connector. An administrator must first Generate API and SIEM Keys, then Generate Notifications for API. Click the appropriate process for more information.

Generate API and SIEM Keys

1. In a web browser, go to [REGION].conferdeploy.net.
   Note: [REGION] = Region of tenant

   • Americas = https://defense-prod05.conferdeploy.net/
   • Europe = https://defense-eu.conferdeploy.net/
   • Asia Pacific = https://defense-prodnrt.conferdeploy.net/
   • Australia and New Zealand = https://defense-prodsyd.conferdeploy.net
2. Sign In to the VMware Carbon Black Cloud.
   
3. In the left menu pane, expand Settings and then click API Access.
   
4. Select Add API Key.
   
5. From the Add API Key menu:
   1. Populate a Name.
   2. Populate a Description.
   3. Select an Access Level type.
   4. Populate external Authorized IP addresses that should request information from VMware Carbon Black Cloud.
   5. Click Save.
   
6. From API Credentials:
   1. Click the clipboard icon to the right of the API ID to copy the ID to the clipboard.
   2. Record the API ID.
   3. Click the clipboard icon to the right of the API Secret Key to copy the key to the clipboard.
   4. Record the API Secret Key.
   5. Click the X in the upper-right corner.
   
7. Select Add API Key.
   
8. From the Add API Key menu:
   1. Populate a Name.
   2. Populate a Description.
   3. Select an Access Level type.
   4. Populate external Authorized IP addresses that should request information from VMware Carbon Black Cloud.
   5. Click Save.
   
9. From API Credentials:
   1. Click the clipboard icon to the right of the API ID to copy the ID to the clipboard.
   2. Record the API ID.
   3. Click the clipboard icon to the right of the API Secret Key to copy the key to the clipboard.
   4. Record the API Secret Key.
   5. Click the X in the upper-right corner.
   

Generate Notifications for API

Information is sent to the previously configured API through notifications that are set within the VMware Carbon Black Cloud console.

1. In a web browser, go to [REGION].conferdeploy.net.
   Note: [REGION] = Region of tenant

   • Americas = https://defense-prod05.conferdeploy.net/
   • Europe = https://defense-eu.conferdeploy.net/
   • Asia Pacific = https://defense-prodnrt.conferdeploy.net/
   • Australia and New Zealand = https://defense-prodsyd.conferdeploy.net
2. Sign In to the VMware Carbon Black Cloud.
   
3. In the left menu pane, expand Settings and then click Notifications.
   
4. Click Add Notification.
   
5. From the Add Notification menu:
   1. Populate a Name.
   2. Determine When do you want to be notified.
   3. Select the appropriate Policy to be notified on.
   4. Populate an Email to be notified at and optionally select to Send only 1 email for each threat type per day.
   5. Populate the API Keys with the API ID that was previously generated.
   6. Click Add.
   
   Note: Customers with Carbon Black Enterprise EDR can also specify watchlists that are sent through SIEM. This allows for a more targeted approach to information gathering.

Syslog Connector

1. Connect to the server hosting the Syslog Connector through SSH.
   Note:

   • For information about connecting through SSH using CentOS 8, reference Securing networks.
   • For information about connecting through SSH with CentOS 7, reference Configuration Files.
2. Generate a backup directory for the syslog output by typing sudo mkdir /tmp/output/ and then press Enter.
   
3. Create the configuration file by typing sudo touch /tmp/cbsyslog-config.txt and then press Enter.
   
4. Create the log file by typing sudo touch /tmp/cbsyslog-log.log and then press Enter.
   
5. Open the previously created configuration file using nano with sudo privileges by typing sudo nano /tmp/cbsyslog-config.txt and then press Enter.
   
6. Copy the following text and then Paste it into the text editor.

   [general]
   # Template for syslog output.
   # This is a jinja 2 template
   # NOTE: The source variable corresponds to the Carbon Black Cloud Server used to retrieve results
   template = {{source}} {{version}}|{{vendor}}|{{product}}|{{dev_version}}|{{signature}}|{{name}}|{{severity}}|{{extension}}
   
   #Location of the Backup Directory
   #This will be the location of back up files in the event that results fail to send to Syslog
   back_up_dir = /tmp/output/
   
   # This sets the default severity level for POLICY_ACTION notifications.  By default it is 4.
   # 0 - Emergency: System is unusable.
   # 1 - Alert: Action must be taken immediately.
   # 2 - Critical: Critical conditions.
   # 3 - Error: Error conditions.
   # 4 - Warning: Warning conditions.
   # 5 - Notice: Normal but significant condition.
   # 6 - Informational: Informational messages.
   # 7 - Debug: Debug-level messages.
   policy_action_severity = 4
   
   # Output format of the data sent. Currently support json or cef formats
   # Warning: if using json output_format, we recommend NOT using UDP output_type
   output_format=cef
   
   # Configure the specific output.
   # Valid options are: 'udp', 'tcp', 'tcp+tls', 'http'
   #  udp     - Have the events sent over a UDP socket
   #  tcp     - Have the events sent over a TCP socket
   #  tcp+tls - Have the events sent over a TLS+TCP socket
   #  http    - Have the events sent over a HTTP connection
   output_type=tcp
   # tcpout=IP:port - ie 1.2.3.5:514
   tcp_out=
   # udpout=IP:port - ie 1.2.3.5:514
   #udp_out=
   # httpout=http/https endpoint - ie https://server.company.com/endpoint
   # http_headers= {'key1': 'value1', 'key2': 'value2'} - ie {'content-type': 'application/json'}
   # https_ssl_verify = True or False
   #http_out=
   #http_headers= {'content-type': 'application/json'}
   #https_ssl_verify=True
   # Override ca file for self signed certificates when using https
   # This is typically a .pem file
   #requests_ca_cert=/usr/share/cb/integrations/cbc-syslog/cert.pem
   
   [tls]
   # Specify a file containing PEM-encoded CA certificates for verifying the peer server when using TLS+TCP syslog
   #ca_cert = /etc/cb/integrations/cbc-syslog/ca.pem
   # Optionally specify a file containing PEM-encoded client certificate for verifying this client when using TLS+TCP syslog
   # If cert is specified, key is a required parameter
   #cert = /etc/cb/integrations/cbc-syslog/cert.pem
   # Optionally specify a file containing PEM-encoded private key for verifying this client when using TLS+TCP syslog
   # If key is specified, cert is a required parameter
   #key = /etc/cb/integrations/cbc-syslog/cert.key
   # Optionally specify the password to decrypt the given private key when using TLS+TCP syslog
   #key_password = p@ssw0rd1
   # Uncomment tls_verify and set to "false" in order to disable verification of the peer server certificate
   #tls_verify = true
   
   [CarbonBlackCloudServer1]
   # Carbon Black Cloud API Connector ID
   api_connector_id = EXAMP13
   # Carbon Black Cloud API Key
   api_key = EXAMP13EXAMP13EXAMP13
   # Carbon Black Cloud SIEM Connector ID
   siem_connector_id = EXAMP131234
   # Carbon Black Cloud SIEM Key
   siem_api_key = EXAMP13EXAMP13EXAMP13
   # Carbon Black Cloud Server URL
   # NOTE: this is not the url to the web ui, but to the API URL
   # For more than one Carbon Black Cloud Server, add another server using the following template including the stanza
   #[CarbonBlackCloudServer2]
   #api_connector_id = KJARWBZ111
   #api_key = CQF35EIH2WDF69PTWKGC4111
   #server_url = https://defense-prod05.conferdeploy.net
   

7. To have the output sent using TCP, populate the host and port with output_type set to TCP.
   
   Note: The example image has the settings redacted.
8. Update the api_connector_id and api_key according to the API type’s API ID and API type’s API Secret Key.
   
   Note: For information about where the API and SIEM keys are created, reference the Generate API and SIEM Keys section above.
9. Update the siem_connector_id and siem_api_key according to the SIEM type’s API ID, and SIEM type’s API Secret Key.
   
   Note: For information about where the API and SIEM keys are created, reference the Generate API and SIEM Keys section above.
10. Save the file by holding CTRL, then press X. Confirm to save the file by pressing Y.
    
11. Confirm the filename by pressing Enter.
    

Administrators must Test and then Validate the output from the syslog connector. Click the appropriate process for more information.

Test

1. From the Linux server, open Terminal.
2. Type sudo python[VER] [INSTALLDIRECTORY]/cbc_syslog.py -l [LOGFILELOCATION] -c [CONFIGFILELOCATION] and then press Enter.
   Note:

   • [VER] = Version of Python
   • [INSTALLDIRECTORY] = Directory where the syslog connector is installed
   • [LOGFILELOCATION] = Location of the log file
   • [CONFIGFILELOCATION] = Location of the config file

Example:

sudo python3 /usr/local/lib/python3.6/site-packages/cbc_syslog/cbc_syslog.py -l /tmp/cbsyslog-log.log -c /tmp/cbsyslog-config.txt

This command performs a one-time run of the syslog connector that is based on the defined configuration file and outputs to the defined log file.

Once a test run is performed, inspect the output based on the log file that is generated in the test options. Inspect the log file to confirm the success or failure of the connection.

Validate

1. From the Linux server, open Terminal.
2. Type cat [LOGFILELOCATION] and then press Enter.
   Note: [LOGFILELOCATION] = Location of the log file

Example:

cat /tmp/cbsyslog-log.log

A successful run returns a response similar to:

Carbon Black Cloud Syslog 2.0
Carbon Black Cloud Syslog 2.0
Found 1 Carbon Black Cloud Servers in config file
Handling notifications for https://defense-prod05.conferdeploy.net
Sending Notifications
Done Sending Notifications
Sending Audit Logs
Done Sending Audit Logs

The receiving SIEM or Syslog instance outputs any events that have occurred since the notification was created within the VMware Carbon Black Cloud console.

Validate within the configured SIEM or Syslog server that information was properly captured. This varies with each application.

Automation of running the syslog connector to regularly pull information can be done with cron.

1. Generate a script that to be used for the automation by typing sudo nano /tmp/cbsyslogrun.sh and then press Enter.
   
   Note: The example generates a shell script of /tmp/cbsyslogrun.sh.
2. Copy the validation script that was used within the Validate section, then Paste that script within the text editor.
   
3. Press CTRL+X to exit.
4. On prompt to save, press Y to continue, saving the changes.
   
5. Update the script to allow for it to run as a script by typing sudo chmod a+x /tmp/cbsyslogrun.sh and then press Enter.
   
6. Open the crontab file to add the script as an automated task by typing sudo crontab -e and then press Enter.
7. Crontab leverages a VI-based syntax for editing text. Press the Insert key to add characters.
8. Type */[MINUTES] * * * * /tmp/cbsyslogrun.sh and then press ESC to cancel the text insertion phase.
   
   Note:

   • [MINUTES] = Number of minutes to wait before running the command again
   • In the example image, the example runs every 15 minutes.
9. Press the colon (:) key to enter a command.
10. Type wq and then press Enter to write and exit the crontab editor.
11. Confirm the change by typing sudo crontab -l and then press Enter.
12. Verify that the scheduled task (Step 7) appears in the list. If the task appears, the automation is configured. If the task does not appear, go to Step 13.
    
13. Type sudo systemctl start crond.service and then press Enter.
14. Type sudo systemctl enable crond.service and then press Enter.
15. Type sudo crontab -l and then press Enter.
    
16. Verify that the scheduled task appears in the list.