Rules development (II): basis for implementation

In the previous post we introduced the process of rules development, creating custom rules from setting up your development environment to executing our rule in KIUWAN. Now, we begin to see how to implement the rules themselves.

We have already explained that, through Kiuwan Rule Developer, we have the option to create new rules, generating two files: the basic structure of the source code of the rule (a .java file with the implementation of the rule) and its definition (an .xml with the necessary metadata for execution). Now we will edit that .java template to add source code that detects and reports violations of the rule we want to apply.

First of all: basic knowledge

A KIUWAN rule is a program that runs source code static analysis, but how does it work?Rules development 01Source code goes through a process called parsing, to obtain an object called AST (Abstract Syntax Tree): a tree representation of the syntactic structure of some code written in a specific programming language. Each node of the tree represents an element that appears in the source code, so our rules could go through those nodes looking for the conditions denoting there is a violation of certain coding best practice.

A rule is just a Java class that must meet the following conditions:

  • To extend AbstractRule (com.als.core.AbstractRule). For some technologies, there are more concrete abstract rule classes to extend from: com.als.cobol.rules.AbstractCobolRule, com.optimyth.sql.rules.AbstractSqlRule… Each one of them extends from com.als.core.AbstractRule.
  • To implement an initialize method. This is where you can recover the values of the properties to customize your rule analysis. This method will be executed just once per launched analysis.
  • To implement a visit method. This is where the main functionality of the rule is placed. This method will be executed one time per analyzed file.
  • To implement a postprocess method. This is where your rule can perform actions on information retrieved during the analysis of each file. This method will be executed just once per launched analysis.
  • To report a RuleViolation (com.als.core.RuleViolation) in the RuleContext (com.als.core.RuleContext).

Example:

 

As we have already mentioned, the rule operation is to visit the AST object nodes to recover data confirming the existence of a violation. There are different APIs and tools provided by the product, useful to navigate through the AST in many different ways. Abstract Syntax Tree (low-level and high-level) API.

  • NavigableNode / TreeNode API.
  • XPath rules.
  • Query API.
  • Control-flow graph (CFG) and data-flow analysis.
  • Library metadata.
  • Tainting propagation.
  • Local / Global Symbol Table.

For more detailed information, you can check the documentation for rules development in developer directory of Kiuwan Local Analyzer distribution, specifically API alternatives and Additional Static Analysis facilities sections. Anyway, we will see these topics in more detail and giving concrete examples of their uses in subsequent posts.

 

Let’s get started!

The best way to get to know the API is by developing your first rule, so there you have it, we are going to implement a rule whose description says as follows:

When developing java source code, there sould not be defined methods with more than four parameters.

First of all, you will need an example of a violation of the convention set for the chosen programming language. This is usually a short example of how to code against the rule. You will need the same example with fixed violations as well. Once you have both code fragments, you can parse them using Kiuwan Rule Developer and then explore the AST corresponding to the code. For this example, we will condense a violation and a fix in the same Java class:

Java source code:

 

You can copy and paste this code into ‘Test Source Code’ tab in Kiuwan Rule Developer and click ‘Generate AST’ button. An Abstract Syntax Tree for the java class will be created:

002

 

When you have the AST, you can develop the best approach to traverse the nodes in order to find the way to determine whether there is a violation of the convention in the code or not. For that, there is a basic way, very useful, to travel each one of the nodes: the visitor strategy.

Visitor strategy:

 

So, applying this strategy to our rule implementation is as simple as:

My first rule:

 

But what happens if we want to change the maximum number of parameters allowed in a method? Would we have to recompile the rule? No! We only would have to add a parameter to the rule!

The parameter has to be defined in the rule definition (see Creating a rule in Kiuwan Rule Developer Quick start guide), so you can retrieve the value in your rule by using the initialize method.

003

My first rule with parameters:

 

You can define parameters of different types, as well as define parameters with a regular expression as value or even with a list of possible values.

Parameters definition:

 

And that’s it. We have implemented our first rule. We just need to follow the steps to compile, deploy and run as saw in previous post.

A words about performance

The rules of thumb to optimize rules:

  • Minimize the number of queries to the AST.
  • Get the nodes you need and only the ones you need whenever possible.
  • Avoid caching AST nodes. When you cache a node you are actually caching the whole tree.
  • DO NOT use global variables (fields)*. Use local variables instead. Rules have to be “thread safe”!
  • Take advantage of initialize() and postProcess() methods for unique operations like obtaining the rule’s properties. Both methods are executed just once per rule analysis execution, while visit() is executed once per analyzed file.
  • Avoid using TreeNode.findXXX and other methods that produce list of nodes. Instead of that use the visitor strategy.

(*) Except for representing the properties of the rule. In this case, the value is the same during all the rule execution, so you won’t have concurrency problems.


Further reading

Kiuwan Local Analyzer includes Rule Development Manual, under the /development folder: this is the complete reference you will need if you plan to develop rules for KIUWAN, as well as Rule implementation examples, under the /development/samples: we provide basic rule examples for different languages supported by KIUWAN (like Cobol, C++, Java, Javascript and PHP) that you can check and execute with Kiuwan Rule Developer.

From here, we will dedicate next posts to the study of APIs and facilities we have to make rules implementations, seeing specific application in different scenarios, so we encourage you to visit us regularly.