Cobra setup¶

We use the static analysis tool Cobra, originally developed at NASA/JPL, and designed for ensuring compliance with coding standards for safety-critical codebases and detecting bugs early on. Cobra is a very powerful tool, albeit it comes with a learning curve.

Setup instructions¶

To get started, please note that if you are using Windows, Cobra only works with Cygwin and the Cygwin shell, so install that first if you haven’t. On Unix-based OS’s it should work with any shell. Additionally, you must run all of the following commands in the Firmware/ folder of the repository, otherwise it will not work! Lastly, you will need wget and zip/unzip installed (via your system package manager or Cygwin).

We assume you have already cloned the laser research repository. You will first need to navigate to the Firmware/ folder. Afterwards, clone the Cobra repository, which contains the rules Cobra uses for static analysis, and initialize a bin/ folder (required for running Cobra):

# assuming you are initially in the root of the laser repo
cd Firmware/
git clone https://github.com/nimble-code/Cobra cobra/sources
mkdir cobra/bin

You will then need to download the Cobra executables (available for Cygwin and Linux) or compile from source (required for other OS’s, including macOS). If you want to compile from source, please see the instructions on the official Cobra repository; here, we will only cover using the pre-built executables. They can be downloaded off the latest Cobra release off GitHub. Currently, this is version 5.3, hence we will give instructions for this version. To extract the binaries, use the following commands:

# ONLY for cygwin
wget https://github.com/nimble-code/Cobra/releases/download/version-5.3/bin_cygwin.zip
unzip -j bin_cygwin.zip -d cobra/bin
rm -f bin_cygwin.zip

# ONLY for linux
wget https://github.com/nimble-code/Cobra/releases/download/version-5.3/bin_linux.zip
unzip -j bin_linux.zip -d cobra/bin
rm -f bin_linux.zip

Afterwards, it is necessary to configure Cobra so that it can find its rules. To do so, run:

# the below two commands need to be run
# every time you are using Cobra in the Firmware/
# folder *unless* if you manually set the COBRA
# environment variable and add $COBRA/bin to your PATH
export COBRA=`pwd`/cobra
export PATH=$PATH:$COBRA/bin

# once you have the above two steps
# completed, the `cobra` command should be available
cobra -configure $COBRA/sources # configure cobra

If the commands were ran successfully, a file is created called ~/.cobra. You should also be able to run cobra -lib, which should show the below output:

$ cobra -lib
predefined checks include:
  basic.cobra
  binop.cobra
  cert_c.cobra
  cert_java.cobra
  cwe.cobra
  duplicates.cobra
  extern.cobra
  iridex.cobra
  jpl.cobra
  local_unsafe.cobra
  metrics.cobra
  misra1997.cobra
  misra2004.cobra
  misra2012.cobra
  p10.cobra
  p10_old.cobra
  param_use.cobra
  reverse_null.cobra
  stats.cobra
  suspicious.cobra
  tokenize.cobra

You can now use Cobra to statically-check all the firmware code according to a specific ruleset, as shown below:

# Perform a basic check (this often returns nothing)
cobra -f basic *.[ch]

# Perform a check according to JPL's coding standards
# (should be much more extensive in output)
cobra -f jpl *.[ch]

Ruleset¶

We are currently deciding on which ruleset to use. Some promising ones include the various MISRA standard rulesets and the JPL ruleset, which are well-known and have been used for years for safety-critical systems.