Package: cbc-syslog
Carbon Black Cloud Syslog Connector 2.xIntroductionThe Carbon Black Cloud Syslog connector lets administrators forward alerts and audit logs from their Carbon Black Cloud instance to local, on-premise systems or other cloud applications.Still need CBC Syslog 1.x? Checkout thelegacybranchIf you are looking to migrate from CBC Syslog 1.x to 2.x take a look at themigration doc.FeaturesGenerates templated messages to support any desired syslog format or send the entire raw JSON messageSupports multi-tenancy of one or more Carbon Black Cloud organizations into a single syslog streamUse local File, HTTP, TCP, encrypted (TCP over TLS), or UDP transport protocols to send dataRequirementsThe following python packages are required to use CBC Syslogcarbon-black-cloud-sdkJinja2psutiltomli >= 1.1.0; python_version < '3.11'Note:tomliis only required for python versions before 3.11 as tomlib has been included in the standard python libraryInstallationYou can install the Syslog Connector using eitherPyPIor GitHub.PyPI Installationpip install cbc-syslogGitHub InstallationClone the repository using SSH or HTTPSSSH
 git clone git@github.com:carbonblack/cbc-syslog.git

 HTTPS
 git clone https://github.com/carbonblack/cbc-syslog.gitChange to the CBC Syslog directorycd cbc-syslogInstall python packagepip install .Running cbc_syslog_forwarderThe scriptcbc_syslog_forwarderis installed into the OS bin directory for easy access from any directory>>> cbc_syslog_forwarder --help
usage: cbc_syslog_forwarder [-h] [--log-file LOG_FILE] [-d] [-v] {poll,history,convert,setup,check} ...

positional arguments:
  {poll,history,convert,setup,check}
                        The action to be taken
    poll                Fetches data from configured sources and forwards to configured output since last poll attempt
    history             Fetches data from specified source for specified time range and forwards to configured output
    convert             Convert CBC Syslog 1.0 conf to new 2.0 toml
    setup               Setup wizard to walkthrough configuration
    check               Check config for valid API keys with correct permissions

options:
  -h, --help            show this help message and exit
  --log-file LOG_FILE, -l LOG_FILE
                        Log file location
  -d, --debug           Set log level to debug
  -v, --verbose         Set log level to infoThecbc_syslog_forwarderpoll command is designed to be executed in a cronjob or scheduled task for continual syslog forwardingMac/Linux:Create a file to save the cronjob such assyslog-job.txt. Cronjobs use theUNIX cron formatfor specifying the schedule for the job to be executed5  *  *  *  *  cbc_syslog_forwarder --log-file /some/path/cbc-syslog.log poll /some/path/my-config.tomlTo start the job once the file is created run the following commandcrontab syslog-job.txtWindows:Windows uses Task Scheduler for running scheduled applications.Search forTask SchedulerClick onActionthenCreate TaskName your Scheduled TaskClick on theActionsTab and ClickNewUnderProgram/scriptentercbc_syslog_forwarder.UnderAdd argumentsprovide the arguments you use to run the poll command with absolute paths to any filesClick OKClick on theTriggerstab and ClickNewNow is the time to schedule your Task. Fill out the information as needed and Click OkYour Task has been created! To test your Scheduled Task, follow these instructions below:Search for Task SchedulerClick on the folderTask Scheduler Libraryon the left hand columnSelect the Task you want to TestSelectRunon the Actions column on the right hand column.For more information on windows task scheduler checkouthow-create-automated-task-using-task-schedulerCreate a Config fileIf you are creating a CBC Syslog toml file for the first time checkout the setup wizard which walks you through the basic configuration steps.cbc_syslog_forwarder setup my-config.tomlFor more information on each section follow the guide below:Create a CUSTOM API key in at least one Carbon Black Cloud instance with the following permissionsorg.alerts READandorg.audits READFor more information on creating a CUSTOM API key see theCarbon Black Cloud User GuideCreate a toml file - e.g. my-config.tomlFor a detailed breakdown of all the supported configurations see examples/cbc-syslog.toml.exampleCreate the general section[general]
 backup_dir = "/some/dir"
 output_type = "file/http/tcp/tcp+tls/udp"
 output_format = "json/template"a. Specify an absolute path inbackup_dirto a directory where unsent messages and previous state can be saved in the case of failureb. Decide how you would like to send the messages inoutput_typefromfile,http,tcp,tcp+tlsorudpc. Decide youroutput_formatfromjsonortemplateBased on theoutput_typeyou have choosen you'll need to configure one of the following output destinationsExamples outputsfile_path = "/some/dir"

 http_out = "https://example.com"
 http_headers =  "{ \"content-type\": \"application/json\" }"
 https_ssl_verify = true

 tcp_out = "1.2.3.5:514"

 udp_out = "1.2.3.5:514"a.  If you selectedtcp+tlsyou'll need to configure thetlssection based on your destination's expected certs[tls]
 ca_cert =
 cert =
 key =
 key_password =
 tls_verify =If you choosejsonforoutput_formatskip to step 6 otherwise see 4aExample CEF template[alerts_template]
 template = "{{datetime_utc}} localhost CEF:1|{{vendor}}|{{product}}|{{product_version}}|{{reason_code}}|{{reason}}|{{severity}}|{{extension}}"
 type_field = "type"
 time_format = "%b %d %Y %H:%m:%S"
 time_fields = ["backend_timestamp"]

 [alerts_template.extension]
 default = "cat={{type}}\tact={{sensor_action}}\toutcome={{run_state}}"
 CB_ANALYTICS = "cat={{type}}\tact={{sensor_action}}\toutcome={{run_state}}\tframeworkName=MITRE_ATT&CK\tthreatAttackID={{attack_tactic}}:{{attack_technique}}"

 [audit_logs_template]
 template = "{{datetime_utc}} localhost CEF:1|{{vendor}}|{{product}}|{{product_version}}|Audit Logs|{{description}}|1|{{extension}}"
 time_format = "%b %d %Y %H:%m:%S"
 time_fields = ["eventTime"]

 [audit_logs_template.extension]
 default = "rt={{eventTime}}\tdvchost={{orgName}}\tduser={{loginName}}\tdvc={{clientIp}}\tcs4Label=Event_ID\tcs4={{eventId}}"a. You'll need to create a template for each data type you plan to enableb. Each data template supports a basetemplatealong with the option to specify anextensionwhich can be used customize each message based on the values of the specifiedtype_fieldIn the example above thetype_fieldfor alerts is set totypewhich enables a different extension to be selected based on the alert fieldtypeNote:If a value is not specified in the extension then the default option will be used. The values are CASE_SENSITIVEc. If you need to modify the format of a timestamp then you can specify a python strftime format intime_formatas well as thetime_fieldsthat need to be modifiedFor more information on strftime formats seehttps://strftime.org/d. SeeSearch Fields - Alertfor the full list of Alert fieldsConfigure one or more Carbon Black Cloud OrganizationsExample Organization[SourceName1]
 server_url = defense.conferdeploy.net
 org_key = ABCD1234
 custom_api_id = ABCDE12345
 custom_api_key = ABCDEFGHIKLMNO1234567890
 alerts_enabled = true
 audit_logs_enabled = truea. Theserver_urlshould match the hostname of your Carbon Black Cloud environmentb. Theorg_keycan be found on the API Access page in the Carbon Black Cloud console from step 1c. Use the CUSTOM API key from step 1d. Enable the desired data you would like to send for the organizationIf you setalerts_enabledtotruethen you will need to configure one or morealert_rulesEachalert_rulesis a separate request for alerts such that you can configure custom criteria for a desired usecase. SeeSearch Fields - Alertfor the fields markedSearchable.Example Alert Rules[[SourceName1.alert_rules]]
 type = [ "WATCHLIST", "DEVICE_CONTROL" ]
 minimum_severity = 7

 [[SourceName1.alert_rules]]
 type = [ "CB_ANALYTICS" ]
 minimum_severity = 3The key is the alert field you want to filter by and the value is a list of values you want to filter exceptminimum_severitywhich is a single integer. Each value is OR'd for a key and values are AND'd across keys e.g.type:( WATCHLIST OR DEVICE_CONTROL) AND minimum_severity: 7If you want to fetchALLalerts then use the followingalert_rules[[SourceName1.alert_rules]]
 minimum_severity = 1Creating a custom message with templatesThe configuration file provides the ability to define a template for each data type as well as the ability to create a custom extension which can be defined based on a configurable field to make a unique message for a data's sub typeThe templates use jinja2 for rendering customizable messages. You can provide the text to be included as well as variable data by wrapping the field name in double curly braces e.g.{{field_name}}.Template Configuration Propertiestemplatedefines the base syslog header which will be included for all messages of the data typeNote:Make sure to include{{extension}}inside thetemplatevalue in order for the extension template to be rendered as part of the messagetype_fielddefines the field in the data that should be used to define which extension should be rendered. The value in the extensions are case sensistivetime_formatandtime_fieldsprovides you the ability to customize the way the timestamps are formatte and which fields to modify. This utilizes python strftime formatting, for more information on strftime formats seehttps://strftime.org/Example:[alerts_template]
template = "{{datetime_utc}} localhost CEF:1|{{vendor}}|{{product}}|{{product_version}}|{{reason_code}}|{{reason}}|{{severity}}|{{extension}}"
type_field = "type"
time_format = "%b %d %Y %H:%m:%S"
time_fields = ["backend_timestamp"]Extensiondefaultdefines the extension which will be utilized if no field is specified fortype_fieldor a value was not specified in the extensionAny other key in the extension dictionary will be interpretted as a possible value to be matched for thetype_field. The values are case sensistiveExample:[alerts_template.extension]
default = "cat={{type}}\tact={{sensor_action}}\toutcome={{run_state}}"
CB_ANALYTICS = "cat={{type}}\tact={{sensor_action}}\toutcome={{run_state}}\tframeworkName=MITRE_ATT&CK\tthreatAttackID={{attack_tactic}}:{{attack_technique}}"FieldsThe following fields are available for building the Syslog header{{datetime_utc}}- Uses current time with format e.g. 1985-04-12T23:20:50.52Z{{datetime_legacy}}- Uses current time with format e.g. Jan 18 11:07:53{{vendor}}- CarbonBlack{{product}}- CBCSyslog{{product_version}}- Current CBC Syslog version e.g. 2.0.2For the available Alert fields seeSearch Fields - AlertsFor the available Audit Log fields seeAudit Log EventsCustomer SupportIf you want to report an issue or request a new feature please open an issue onGitHubIf you are struggling to setup the tool and your an existing Carbon Black Cloud customer reach out toSupportfrom your product console or your sales contact. Support tickets can also be submitted through ourUser Exchange community.For other helpful resources check out our contact us pagehttps://developer.carbonblack.com/contact