Package: cbc-binary-toolkit
Carbon Black Cloud Binary ToolkitLatest Version:1.1.1Release Date:03/31/2021The Carbon Black Cloud Binary Toolkit provides a system of processing incoming SHA256 hashes by integrating with the Unified Binary Store (UBS) on the Carbon Black Cloud (CBC).Recent updatesView the latest release noteshere.LicenseUse of the Carbon Black API is governed by the license found inLICENSE.SupportView all API and integration offerings on theDeveloper Networkalong with reference documentation, video tutorials, and how-to guides.Use theDeveloper Community Forumto discuss issues and get answers from other API developers in the Carbon Black Community.Create a github issue for bugs and change requests. FormalCarbon Black Supportcoming with v1.0.RequirementsThe Carbon Black Cloud Binary Toolkit is designed to work on Python 3.6 and above.All requirements are installed as part ofpip install cbc-binary-toolkitor if you're planning on pushing changes to the Carbon Black Cloud Binary Toolkit, the following can be used after cloning the repopip install -r requirements.txtCarbon Black CloudEnterprise EDROS Specific RequirementsWindowsusers will need to haveMicrosoft Visual C++ 14.0 Build Toolsinstalled in order to compile yara-python.Linuxusers will need to have the python developer package installed in order to compile yara-python. If you receive compile errors, make sure you are on the latest gcc compiler version.Linux DistributionCommandAmazon Linux/Centos/RHELyum install python3-develUbuntuapt-get install python3-devOpenSUSE/SUSEzypper install python3-develPython Packagesargparsecarbon-black-cloud-sdkpython-dateutilpyyamlrequestsschemayara-pythonPerformance MetricsFor details on the expected performance for the CBC Binary Toolkit see the Performance Metrics wiki pagehere.The wiki page will be updated with any changes or additional tests that may be run in the future.Getting StartedThere are two ways to use the Carbon Black Cloud Binary Toolkit. You can either run the Binary Analysis Tool using out-of-the-box functionality, or you can use the Toolkit to develop your own tool for processing binaries.First you will need to install the Binary Toolkit with the following command:pip install cbc-binary-toolkitRunning Binary Analysis toolThe cbc-binary-analysis tool provides out-of-the-box builtin resources for processing binaries and managing the analysis results. For more information see theUser Guidewiki page.usage: cbc-binary-analysis [-h] [-c CONFIG]
                           [-ll {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
                           {analyze,restart,clear} ...

positional arguments:
  {analyze,restart,clear}
                        Binary analysis commands
    analyze             Analyze a list of hashes by command line or file
    restart             Restart a failed job and pick up where the job crashed
                        or exited
    clear               Clear cache of analyzed hashes. All or by timestamp

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        Location of the configuration file (default .../carbonblackcloud/binary-toolkit/binary-analysis-config.yaml.example)
  -ll {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        The base log level (default INFO)Note:Run --help on any of the commands for up to date arguments.Using the Toolkit to develop your own toolsThe following python code snippet allows you to begin developing with the Carbon Black Cloud Binary toolkit. For more information see theDeveloper Guide.from cbc_binary_toolkit import *Developing Improvements for the Carbon Black Cloud Binary ToolkitUse the following steps if you want to provide additional examples, fix a bug, or add a feature to the Toolkit.Installing for Toolkit developmentYou will need to fork the repo in order to create pull requests when submitting code for review. For details on forking a repo, seehere.git clone https://github.com/{fork-name}/cbc-binary-toolkit
cd cbc-binary-toolkit
pip install -r requirements.txtIf you want to test/execute the console scripts from the repo then install the toolkit with the following command. This will install the toolkit in editable mode so changes to the repo modify the installed package. See themanual-testsdocument for more information on testing from a fresh install.pip install -e .Note: The above command needs to be run from the base folder of the repoRunning the Analysis toolIf you want to execute the analysis tool without installing the package you can run the tool directly using theanalysis_util.pyscript insrc/cbc_binary_toolkit_examples/toolsRunning the Toolkit testsTo check that your code changes didn't break any use cases, or fail our linters, the following will show you how to set up and run our tests:Install one or all of these versions of Python:Python 3.6.X, Python 3.7.X or Python 3.8.Xand make sure it is accessible to this project.For managing different versions of python, an easy solution is:pyenv(for UNIX based systems), orpyenv-win(for Windows based systems).Installtox(e.g.pip install toxorbrew install tox)Run the commandtox -e <the environment you want to run>from anywhere in the directory to run the tests and linter.Thetox.inifile shows that the tests are run against python versions3.6.x, 3.7.x and 3.8.xaspy36, py37, py38.Example:If you just runtox -e py37, it will run the tests against thePython 3.7.Xversion installed locally.But iftoxis run, it will try to run against all the versions listed in thetox.inifile (currently py36, py37, and py38).
If a version is not installed locally, it will just throw an error of:ERROR:  pyXX: InterpreterNotFound: pythonX.XIt will continue running against the versions that are installed.If there are any changes, you need to recreate the virtualenv that tox built. Just runtox --recreate -e <the environment you want to run>ortox --recreatefor all environments.If this error is thrown:ERROR: cowardly refusing to delete `envdir` (it does not look like a virtualenv):Delete the python env directory (py37) from .tox directory
and reruntox --recreate.Development FlowTo begin a code change, start by creating a branch off of the develop branch.git checkout develop
git checkout -b {branch-name}When the feature or bug fix is finished you will need to create a pull request to the CarbonBlack repo, the following will push your changes to Github.git push {remote} {branch-name}If your branch is behind the develop branch, you will need to rebase.git checkout {branch-name}
git rebase developNote:if your develop branch is out of sync with the CarbonBlack repo then you will need to sync your fork. For information on syncing your fork, seehere.