Ruby goes to Kiuwan

Kiuwan Code Analysis offers state of the art engines, supporting more than 22 programming languages and frameworks including: Java, Csharp, Javascript, ABAP and Hibernate among others.

But Kiuwan is more than a static analysis tool. Kiuwan can categorize your rules and create models according to your needs, plan your next steps with action plans to optimize your time with the ‘what if’ analysis, generate reports, and share the results in the cloud.

For those languages not natively supported, Kiuwan offers the possibility of importing the defects or vulnerabilities found with other engines, and from there get all the extra benefits it offers.
Ruby is one of those not supported languages (at least just yet). Brakeman is an open source engine designed to find security vulnerabilities in Ruby on Rails applications.

Here we will explain, step by step, what you need to do to integrate Brakeman with Kiuwan. Are you ready? Here we go.

Analyze Ruby application in only three steps

Integrating an external engine in Kiuwan requires three steps:

  1. Define the rules of your external engine in a Kiuwan format (ruledef) and import them in your model.
  2. Convert the output result report of the external engine to a Kiuwan results report format.
  3. Analyze the application and upload the results to Kiuwan.

As an example, we are going to use BRAKEMAN as an external engine, and integrate it with Kiuwan.

Rules definition

First, you need to import the Brakeman rules (checkpoints, in Brakeman jargon) in your Kiuwan library.

Brakeman’s definitions can be found on http://brakemanscanner.org/docs/warning_types/.

Kiuwan’s ruledefs are definition files in XML format. We can use the Kiuwan Rule Developer tool to create these documents. This tool is bundled with Kiuwan Local Analyzer.

Run the Rule Developer from %KiuwanLocalAnalyzer_install_dir%\development\rdev.cmd.

After logging in with your Kiuwan account, in the initial screen, click ‘New’ button to create a new rule:

 

blank_editor

 

The definition form appears:

definition

 

As an example to populate this form, Brakeman’s ‘Dangerous Send’ rule will be used.

The fields are:

  1. Each rule must be have a ‘unique’ code. Also, all user defined rules must begin with the prefix ‘CUS’.

As a recommendation, you should define a namespace for your rules as a common part of the unique identifier. In this example, as namespace we will use the language and the engine name: RUBY.BRAKEMAN. And then, a specific unique code for each rule, in lowercase and without blank spaces. In this case, the rule code is: dangerous_send.

  1. The rule name to be displayed.
  2. A simple description.
  3. An URL where to find more information for this rule.
  4. Benefits and drawbacks.
  5. Choose one of the software characteristics that will be mostly affected when the rule finds defects.
  6. The programming language, Ruby obviously.
  7. Choose the priority for this rule.
  8. Choose the repair difficulty of defects found by the rule.
  9. Class: This is an unused field when we are using 3rd party engines. Write a dummy value.
  10. Choose a target folder where the definition file will be saved.

As extra help documentation, you can include same code examples.

code_examples

Once we save the definition, the file CUS.RUBY.BRAKEMAN.dangerous_send.rule.xml appears in the target folder.

 

 

IMPORTANT: You need to manually edit this file and replace OPT.CRITERIUM_VALUE.ENGINE.QAKING by OPT.CRITERIUM_VALUE.ENGINE.OTHER.

When you have many rule definitions to create, doing them all manually, as described above, can be inefficient. In this case, you can develop a simple program to automate the task. That program should read the source where the 3rd party engine has the definitions and create an XML file for each rule with the above format (one file with all the ruledefs will work as well).

Import this definition to your Kiuwan rules library

To use these new rules in your models you have to import them to your library. To do this, open a new session in Kiuwan, go to ‘Settings – Models Management’ and create a new model.

 

new-model

 

In the menu option ‘Rules’, click on ‘Install rule definitions’:

install-rule-definitions

 

Upload your created definition file (or files if you have more than one and want to import them on bulk):

install-rule-definitions-2

 

Choose the model where you want to include this rule (you can do this in a later step as well). The rule is automatically added to the library and in the selected model (if any was selected).

model-with-ruby

From the library you can add it to any other existing model or the ones you create from now on. You don’t need to do the import again since the rule definition is already in your library.

Now you can publish the model. This is mandatory if you want to use this model, with the Brakeman rule in it, to use it in our analyses.

model-publish

To use it, from ‘Settings – Application management’, you can create a new application and assign this model to it:

 

setmodel

Format converter

Before the next steps, you need a converter program to transform the defects report generated by Brakeman to a format which Kiuwan understands. You can find detailed information about this format in https://www.kiuwan.com/docs/display/K5/Third+party+analyzers.

For Brakeman, the Kiuwan Team has published a sample transformer application in the Kiuwan Github public account.

You can get the application at: https://github.com/kiuwan/thirdparty-report-importer

You need the dist/kiuwan-thirdparty-report-importer-0.2.2.jar file.

Analysis of an application

Once you have your converter, you can analyze a Ruby application and see the results in Kiuwan.

This analysis has 3 steps:

  1. Analyze the application with Brakeman.
  2. Convert the defects report generated by Brakerman to Kiuwan format.
  3. Analyze with Kiuwan Local Analyzer to upload the report to Kiuwan.

Analysis with Brakeman

Assuming that the source code of your application is in c:\myapp\src, we should execute:

%RUBY_HOME%\bin\brakeman.bat –format json –out c:\brakeman_report.json c:\myapp\src

The output format of this report is a json file:

Conversion

In this step, you convert the json file generated by Brakerman to the XML Kiuwan format. The output file must have ‘kiuwan_’ as prefix.

 

This is the generated report in Kiuwan format:

Analysis with Kiuwan

In this last step, you will use the Kiuwan Local Analyzer to upload the report to our server. At the same time, the Kiuwan Local Analyzer will calculate volumetric metrics and will run a duplicated code analysis, which are mandatory in any Kiuwan analysis.

Ready to get the most out of Kiuwan

In a few minutes we can see the results on Kiuwan. Select your Ruby application in Kiuwan, and in the ‘Defects’ screen, you can find the defects detected by Brakeman, in what file and line of code they are and help information (this is the meta information you put in the rule definition) for each imported Brakeman rule.

defects

 

Additionally, all Kiuwan indicators are calculated taking the Brakeman defects into account, and now you can benefit from all Kiuwan features including the “what if” analysis to create an action plan that may include Brakeman defects, generate a PDF reports, share the results with your colleagues, etc… Interested, click below and see what Kiuwan Code Analysis can add to your development process.