YARA Connector and Manager User Guide for EDR

Carbon Black EDR (Endpoint Detection and Response) is the new name for the product formerly called CB Response.

The VMware Carbon Black EDR Yara Connector provides an integration with the Yara malware detection and classification tool. Yara Manager provides a web-based user interface, integrated with the VMware Carbon Black EDR server to configure, control and assess the status of the Yara Connector.

Installing YARA Agent (CentOS/RHEL 6/7/8)

YARA Integration has two parts — a primary, and one or more minions. The primary service must be installed on the same system as EDR, while minions are usually installed on other systems (but can also be on the primary system). The YARA connector uses Celery to distribute work to remote (or local) minions. You must install and configure a broker (for example, Redis that is accessible to both the primary and remote minion instances.

The connector reads YARA rules from a configured directory to efficiently scan binaries as they are recognized by the EDR server. The generated threat information is used to produce an intelligence feed for ingest by the EDR Server.

Install the CbOpenSource repository if it does not already exist:

cd /etc/yum.repos.d
curl -O https://opensource.carbonblack.com/CbOpenSource.repo

Install the RPM:
```
yum install python-cb-yara-connector
```

Create YARA Connector Config

The installation process creates a sample configuration file: /etc/cb/integrations/cb-yara-connector/yaraconnector.conf.example

Copy this sample template to /etc/cb/integrations/cb-yara-connector/yaraconnector.conf You will probably have to edit this configuration file on every system (primary and minions) to supply any missing information:

Two operating modes support the two roles: mode=primary and mode=minion. Both modes require a broker for Celery communications. Minion systems must change the mode to minion
Remote minion systems require the primary’s URL for cb_server_url (local minions need no modification); they also require the token of a global admin user for cb_server_token.
Remote minions will require the URL of the primary’s Redis server.

The daemon will attempt to load the PostgreSQL credentials from the Carbon Black EDR server’s cb.conf file, if available, falling back to the PostgreSQL connection information in the primary’s configuration file by using the postgres_xxxx keys in the config. The REST API location and credentials are specified in the cb_server_url and cb_server_token keys, respectively.

EDR PostgreSQL Database settings, required for ‘primary’ and ‘primary+minion’ systems. The server will attempt to read from the local cb.conf file first and fall back to these settings if it cannot do so.

postgres_host=127.0.0.1
postgres_username=cb
postgres_password=<POSTGRES PASSWORD GOES HERE>
postgres_db=cb
postgres_port=5002

EDR server settings, required for ‘primary’ and ‘primary+minion’ systems. For remote workers, the cb_server_url must be that of the primary.

cb_server_url=https://127.0.0.1
cb_server_token=<API TOKEN GOES HERE>

You must configure broker= which sets the broker and results_backend for Celery. Set this appropriately as per the Celery documentation.

URL of the Redis server, defaulting to the local EDR server Redis for the primary. If this is a minion system, alter to point to the primary system. If you are using a standalone Redis server, both primary and minions must point to the same server.

broker_url=redis://127.0.0.1

Create YARA rules

The YARA connector monitors the directory /etc/cb/integrations/cb-yara-connector/yara_rules for files with the extension “.yar”, each specifying one or more YARA rule. Rules must have a meta section with a score = [1-10] tag to appropriately score matching binaries. This directory is configurable in the configuration file. C-style comments are supported.

Sample YARA Rule File

// Sample rule to match binaries over 100kb in size
rule matchover100kb {
    meta:
        score = 10
    condition:
        filesize > 100KB
}

Controlling the YARA Agent

CentOS / Red Hat 6

Action	Command
Start the service	service cb-yara-connector start
Stop the service	service cb-yara-connector stop
Display service status	service cb-yara-connector status

CentOS / Red Hat 7/8

Action	Command
Start the service	systemctl start cb-yara-connector
Stop the service	systemctl stop cb-yara-connector
Display service status	systemctl status -l cb-yara-connector
Displaying verbose logs	journalctl -u cb-yara-connector

Command-line Options

usage: yaraconnector [-h] --config-file CONFIG_FILE [--log-file LOG_FILE]
                     [--output-file OUTPUT_FILE] [--working-dir WORKING_DIR]
                     [--pid-file PID_FILE] [--daemon]
                     [--validate-yara-rules] [--debug]

Yara Agent for Yara Connector

optional arguments:
  -h, --help            show this help message and exit
  --config-file CONFIG_FILE
                        location of the config file
  --log-file LOG_FILE   file location for log output
  --output-file OUTPUT_FILE
                        file location for feed file
  --working-dir WORKING_DIR
                        working directory
  --pid-file PID_FILE   pid file location - if not supplied, will not write a
                        pid file
  --daemon              run in daemon mode (run as a service)
  --validate-yara-rules
                        only validate the yara rules, then exit
  --debug               enabled debug level logging

`--config-file`

Provides the path of the configuration file to be used (REQUIRED)

`--log-file`

Provides the path of the YARA log file. If this is not supplied, the path defaults to local/yara_agent.log in the current YARA package.

`--output-file`

Provides the path containing the feed description file. If this is not supplied, the path defaults to feed.json in the same location as the configured feed_database_dir folder.

`--validate-yara-rules`

If supplied, YARA rules are validated and the script will exit.

Troubleshooting

Some systems may experience an issue getting the Yara feed to appear on the EDR Threat Intelligence page. The underlying issue has to do with Redis configuration, and is documented with a solution in this knowledge base article.

However, you may still need to add the feed manually, which is done using the following steps:

Go to the Threat Intelligence page (click on “Threat Intelligence” in navigation panel on the left side of the EDR console),
Click “Add New Feed”
In the “Feed URL” field, use file://var/cb/data/cb-yara-connector/feed.json
Click Save.

YARA Agent Build Instructions

The dockerfile in the top-level of the repo contains a CentOS 7 environment for running, building, and testing the connector.

The provided script docker-build-rpm.sh uses docker to build the project and put the RPM(s) in ${PWD}/RPMS.

Dev install

Use Git to retrieve the project, create a new virtual environment using Python 3.6+, and use pip to install the requirements:

git clone https://github.com/carbonblack/cb-yara-connector
pip3 install -r requirements.txt

The GitHub repository is here.

Support

View all API and integration offerings on the Developer Network along with reference documentation, video tutorials, and how-to guides.
Use the Developer Community Forum to discuss issues and get answers from other API developers in the VMware Carbon Black Community.
Report bugs and change requests to Carbon Black Support

Give Feedback

New survey coming soon!

Last modified on January 3, 2022

Carbon Black EDR

Page Contents