Rules development (III): debugging custom rules

In previous posts in this series, we introduced the process of creating, executing and implementing custom rules in KIUWAN. Within Rules development series, this post will specifically focus on how a custom rule can be remotely debugged from our favorite IDE.

One of the many powerful features in Kiuwan is its ability to execute custom rules. If your Kiuwan account has the appropriate edition, you will be able to develop your own static analysis rules and evaluate your software quality and security following your own standards.

 

The rule development workflow

When creating a rule for KIUWAN, we will be working with two tools: our favorite IDE and Kiuwan Rule Developer. In previous posts we have seen how to synchronize Kiuwan Rule Developer with our IDE, so changes in our rule’s code are automatically propagated to Kiuwan Rule Developer. This way we can change our rule source code and see the results of applying these changes to our test code immediately:

 

0001

 

Why do I need to debug my rules?

Sometimes we need to perform complex checks and take into account multiple cases of how our code should be constructed or which best practices it should follow.

Although KIUWAN offers a complete API reference (bundled with Kiuwan Rule Developer), we often hit a wall when we try to foresee how our rule will behave when executed in non trivial scenarios. But we at KIUWAN know about these walls and we want you to easily jump over them.

By debugging a complex rule we will be able to tune fine its behavior, making the rise of spurious defects less likely to happen.

Spurious defects
We say that a false positive is introduced in an analysis result when a defect arises, but it should not.We say that a false negative is introduced in an analysis result when a defect that should arise does not.

 

Debugger to the rescue

Kiuwan Rule Developer allows you to remotely debug the rule you are editing in your IDE while it is being executed. If you want to debug your rules, you should launch Kiuwan Rule Developer in debug mode. To do so, open a console and type:

Windows:

> AGENT_HOME/bin/agent –development debugPort=xxxx

Unix:

> AGENT_HOME/bin/agent.sh –development debugPort=xxxx

Where xxxx is the port number where Kiuwan Rule Developer will wait for a remote debug tool to be attached to. Note that the application will not be launched until the remote debug tool is detected by the process.

0002

Once Kiuwan Rule Developer is waiting for the debugger to be attached, create a remote debug configuration in your IDE. We will see how to do this with Eclipse:

  • Right click your Kiuwan custom rules project in the Explorer view.
  • Select the “Debug As” option and then select “Debug Configurations…”.
  • Double click the “Remote Java Application” option on the left side of the dialog shown.
  • Fill the “Connection Properties” form with these values:
    • Host: localhost
    • Port: xxxx (the port number you specified when launching Kiuwan Rule Developer).
  • Click the “Debug” button.

0003
Make sure the specified debug port matches
the one configured in your remote debug tool. If the attachment is successful, Kiuwan Rule Developer will start and you will see a red label indicating the current debugging port in the bottom left of the Rule Developer window:

0004

 

Once Kiuwan Rule Developer is started in debug mode:

  • Set a breakpoint in your rule’s source code.
  • Execute the rule in Kiuwan Rule Developer.
  • Eclipse should stop in the breakpoint.
  • You are ready to debug your custom rule!

 

0005


Further reading:

Kiuwan Rule Developer Quick Start Guide.