KayBee¶
Installation¶
The installation of the kaybee tool consists in just downloading the appropriate
binary for your operating system.
Make sure it is executable; you might want to also ensure that it is in the $PATH, for your convenience.
For example, in Linux you would put the following line in your .bashrc file:
export PATH=$PATH:/usr/local/bin/kaybee
(please, make sure you adjust the path to the kaybee binary as necessary)
Alternatively, you can clone this repository and build it yourself (you will need go and make).
You can do so with the make command; inspecting the Makefile first is a good idea.
Configuration¶
The operation of the kaybee command is controlled via a configuration file and with
command flags and switches (these take priority over the configuration).
To create a configuration file, just run kaybee setup; you will have to edit it manually
to make it work with your particular setup (for example, the Steady endpoint is set to a dummy value
in the default configuration file, you will need to change that to import data from a Steady backend).
The configuration file, by default, is called kaybeeconf.yaml and is searched for
in the current directory and, if it is not there, in your home.
You can put the file in any location (and give it a different name), and
instruct kaybee to use it with the global flag -c. For example:
kaybee -c /path/to/your/configfile.yaml <command here...>
Editing such a configuration file is necessary because that's were you can specify the list of sources from which you intend to retrieve vulnerability data from and a few other things, the most important of which are covered in the following.
If you have just downloaded the tool, the easiest way to start configuring it is to run:
kaybee setup
which will create a template configuration file in the current folder. You will need to edit it to tailor it to your needs (it contains extensive comments to guide you). At the very least, you will need to configure one or more sources, as in this example:
sources:
- repo: https://github.com/sap/project-kb
branch: vulnerability-data
rank: 10
Please refer to the output of kaybee help and kaybee <command> help to
know what flags and options are available.
Retrieving vulnerability data¶
This is achieved with the command:
kaybee pull
The result will be a local clone of each of the sources. You can manually inspect their content and interact with them as with any other cloned git repository (that is what they are after all).
Unless you only consume data from one source, this is not very useful
per se: things get more interesting when you use kaybee to merge
the content of different sources, which is covered next.
Merging vulnerability data¶
The idea underlying project "KB" is to allow multiple independent parties to maintain their own vulnerability data repository, and then to allow users to define how the data from these sources is to be aggregated and reconciled.
This is achieved with the command:
kaybee merge
Unless instructed otherwise, the kaybee command will apply a conservative
policy (called strict) which will not attempt to reconcile statements
that refer to the same vulnerability. This is still useful in practice if
the vulnerabilities covered by different sources are mostly distinct; also,
because this policy is very conservative, it is suitable for unattended
executions of the tool (say, in a cron job that pulls and merges vulnerability
data on a regular basis). Other policies are possible, and at the time of writing
(June 2020), an experimental soft policy is under development: this policy
will allow statements to be reconciled and their contents to be merged automatically
(under certain conditions).
The tool can be instructed to use a particular policy by setting the corresponding
option in the configuration file, or via the command line flag -p, as in:
kaybee merge -p strict
kaybee merge -p soft
Exporting vulnerability data¶
The kaybee export command can be used to export statements to a number of formats.
For example, this command:
kaybee export -t xml
or the equivalent:
kaybee export --target xml
examines the content of the directory .kaybee/merged, which contains the results of
the last run of kaybee merge and exports the statements contained there to XML.
It is important to stress that the export capabilities of kaybee are very generic, and
allow users to write their own exporters to arbitrary text-based formats (called export targets, hence
the -t flag).
An example of a completely different export target is steady:
kaybee export -t steady
or equivavalently:
kaybee export --target steady
The result this time is a script (steady.sh) that can be executed to import
vulnerability data to an Eclipse Steady server.
To export a folder other than the default, one can use the --from option, like so:
kaybee export --target steady --from /path/to/the/statements/you/wish/to/export
Creating new vulnerability statements¶
You can use kaybee create to create a skeleton for you to edit.
Alternatively, you can take an existing statement as a reference, but this is more tedious and error prone.
A check command is planned, to validate a statement. Also, a more user-friendly GUI-based wizard
will probably come later on.
Publishing¶
To be written....