Emenda and Klocwork’s Approach to Industry Compliance
Both here at Emenda and at Roguewave, we understand the importance of proving compliance and know that such a task can be a pain for managers and developers alike. For over 10 years, Emenda have provided the expertise required to audit critical applications, be it automotive, aeronautic, industrial, medical, railway or nuclear. Likewise, Klocwork has been built from the ground up to make such a task as easy and pain-free as possible. As such, reporting compliance with Klocwork has never been easier. This article is designed to highlight reporting efforts made by both Emenda and Klocwork to help with this task, with the end goal of making Klocwork users’ lives easier when battling the notorious task of industry compliance.
Reporting Compliance with Klocwork’s REST API
- cURL (or similar)
- Depending on access control method in place, either a Klocwork username or Klocwork username plus valid authentication token.
- Performed authentication (kwauth) with the Klocwork server you wish to report against.
Viewing the API
Klocwork’s feature-rich REST API can be utilised to pull any information visible on the Klocwork Web Portal locally. Using this extensibility, it is possible to generate your own customised reports to meet certain compliances. If you already have Klocwork and would would like to test it, you can view the possible API calls by navigating to: http://<klocwork_server>:<klocwork_port>/review/api/
Figure 1 above shows that there is no limit to what report can be generated, providing a proper understanding of the requirements of such a report. Below, we discuss what is required to get started using this API and to generate your first report.
Formatting API requests
As with any API, requests must be authenticated. The usage of the API varies depending on the level of security (access control) present within the Klocwork server. Below covers the steps necessary to use the API in both scenarios.
Without Access Control Method
Only a username needs to be provided within the request, and this username can be anything. A minimal example request we can make is as follows:
With Access Control Method
When using access control, both a valid Klocwork username and an authentication token (termed ltoken) must be provided within API requests. Each Klocwork user has a unique ltoken, stored by the Klocwork tool kwauth in one of several user directories:
- Windows Vista and Windows 7: C:\Users\<user_name>\.klocwork\ltoken
- Windows XP: C:\Documents and Settings\<user_name>\.klocwork\ltoken
- Unix: ~/.klocwork/ltoken
- Mac: ~/.klocwork/ltoken
If there is no ltoken file in your .klocwork directory, run kwauth to generate the file.
The ltoken file contains one or more text lines, each of which contains four pieces of information, separated by semi-colons:
Use the fourth piece of information (the <token>), which is usually a long string of numbers and letters, as the authentication token in an API request. A minimal example request we can make is as follows:
For more information on API request authentication, please see the Klocwork documentation or get in touch with us at email@example.com.
Interpreting API responses
Using the example API request above, it is possible to retrieve the full list of issues for the CVS project, equal to viewing the “issues” panel of the Klocwork Web Portal with a blank search field. You can use the cURL’s -o argument to output this list (of JSON objects) to a file. Extracting a specific JSON object, we can see the following issue information:
For reference, the image below shows same issue information as above, but from within the Klocwork Web Portal:
Going further, it is possible to use the search action’s ‘query’ parameter to narrow down issues retrieved by our curl request. For example, from the isolated issue above (figure 4) it is known that the inflate.c file within the CVS project contains at least one MISRA.GOTO issue. Using the following command, we can pull all issues present within this file:
For absolute clarity, note that this is equivalent to making the following search within the Klocwork Web Portal:
Reporting Compliance with Klocwork using custom scripts
As demonstrated above, using JSON as output format of the API responses, Klocwork has made it extremely transparent and easy to collate and re-format Klocwork database information as desired. This leaves the option completely open for easy scripting of API responses, as resources for the manipulation of JSON data are readily available all over the web.
For example, the utilisation of python scripts to handle these responses is common. While this exceeds the scope of this post, you can find a comprehensive collection of examples from Klocwork’s Documentation here.
Reporting Compliance with Klocwork using Emenda’s Compliance Reporting Tool
Evidently, the API grants clear and unlimited access to raw Klocwork data, at the cost of some level of self-scripting. After retrieval, this data then also requires formatting into into the desired format for your organisation. As a “best of both worlds” solution, Emenda have developed a tool (python script) capable of interacting with this very same API and generating clear, concise compliance reports that can be tweaked for your specific needs. The tool can be downloaded directly from here.
- Python 2.7.6+
- Performed authentication (kwauth) with the Klocwork server you wish to report against.
- reportLab python module, or the provided reportLab module to be present in the same directory as the script.
The tool comes with a useful readme outlining its capabilities. To get started, extract the .zip file and open a command terminal in the directory extracted into. To verify successful use of the script, run the following command:
This will generate a .pdf compliance report for the supplied project across all possible taxonomies present on the server. In addition to this command, we can provide several additional arguments to fine-tune the generated report:
- -o / –output [Document Output Location]
- Output the report to a specific location
- -b / –build [Klocwork Build Name]
- Filter the report to show only data from a specific Klocwork project build
- -v / –view [Klocwork View Name]
- Filter the report to show only data from a specific Klocwork project view
- -t / –taxonomy [Klocwork Taxonomy Name]
- Filter the report to show only checkers present within a specific Klocwork taxonomy
- -n / –name [Document Name]
- Output the report with a specific name
- -c / –compliance
- Report full issue breakdown information
- -r / –reference [Klocwork Reference]
- Replace checker codes with references by providing a path to the taxonomy .tconf file
Example Reporting Scenario: Meeting MISRA C 2012 (C90) Compliance
In the following example, the reporting tool is utilised to generate a comprehensive report which provides information on which Klocwork issues are the source of a lack of compliance for the example CVS project. Using the newly introduced argument –taxonomy (or -t) we can easily filter to get the desired result:
Note: the tool recognised taxonomy names matching those seen within the configuration tab of the Klocwork Web Portal:
With this request, the tool uses the API to request from the server several pieces of information:
- Of the checkers that exist within the “MISRA C 2012 C(90)” taxonomy, which (if any) have been disabled for the CVS project.
- All issues present within the CVS project with checker codes matching those within the “MISRA C 2012 (C90)” taxonomy (recall that a taxonomy is just a collection of checkers/rules).
- Other general project metrics like project LOC and complexity rating.
Once gathered, the report generated consists of two main sections:
- Summary page — outlines the project’s overall compliance performance.
- Violations table — illustrates each checker’s performance, such as whether active, how many issues exist within the project that correspond to this checker and whether any of these issues have been ignored.
Automating the task of reporting compliance with Klocwork
Because of the lightweight nature of the tool, it is very easy to include in various continuous integration (CI) pipelines. For example, the following process can be easily performed:
- Run a nightly Klocwork analysis over a codebase
- Use our compliance tool to generate a report outlining the current status of the codebase’s compliance
- Email this report to concerned parties, such as project managers or developers, ready for the morning when they come in to work
To summarise, one of Emenda’s main focuses is, and will always be, compliance (after all, it’s in our motto!) To ensure this focus is always met, we only choose to support products equally as dedicated, and have found Klocwork to be the perfect fit. As part of this ongoing relationship, Emenda are happy to announce our compliance reporting tool, useful for generating customisable Klocwork reports for a myriad of industry compliances. The tool blends Klocwork’s powerful API with a friendly command-line interface to make compliance reporting as easy as possible and can be seamlessly integrated with CI tools such as Jenkins for fast compliance feedback.
If you are interested in finding out more about Klocwork and want to see how your codebases fare with this new tool, we invite you to get in touch with us here on our website, or email us at firstname.lastname@example.org.