Emenda’s Approach to Third-Party Code in Klocwork
The integration of third-party libraries into your software projects has been well documented as bringing accompanying risk¹. You are putting yourself at the mercy of another organisation’s development practices and standards. The well-known proverb, « a chain is only as strong as its weakest link » warns us to take care when integrating external libraries into in-house systems. This holds true even more so in safety-, and security-based systems than any other. Above all, it teaches us that we cannot assume everyone holds their code to the same standard.
Our point is this: always analyze third-party code because you cannot be sure the owner(s) have taken the same care you have by using Klocwork. Klocwork’s power also comes from its ability to accurately understand the interactions of your code, which you compromise if anything is left unanalyzed. Therefore, our recommendation here at Emenda is to analyse everything, then filter what issues you care about seeing from there. Luckily for you, handling third-party code in Klocwork has never been easier, with several methods available to fit any organisation’s software cleanup strategy.
1. Handling third-party code in Klocwork: Issue Citing with « Ignore » status
First on our list is the method of citing detected defects in third-party code with the « Ignore » status. The workflow for this method is as follows:
- Perform a full Klocwork analysis over your entire codebase.
- Access the project from Klocwork Review.
- Filter third-party issues by directory using the search bar.
- Bulk-cite these issues with status « Ignore » along with an explanatory comment.
Example using the CVS project
Let’s take a look at an example project we have set up: the source code for CVS.
CVS uses third-party code located within the « cvs/lib » directory, which we can see by navigating to the « Xref » tab of the CVS project:
Knowing the file path, we can view all Klocwork issues identified for files under « cvs/lib » by entering it into the search bar, found under the « Issues » tab.
We find that Klocwork has identified 287 issues within the third-party code of the CVS project, confirming the number seen in figure 2. To hide these issues from developers, we can bulk-edit all issues with the status « Ignore » by selecting the « Edit All » button shown below.
Then select « Ignore » from the drop-down menu, leave a comment justifying the change if you wish and select « Submit ».
Viewing the same search as in figure 3, we now see that all issues have status « Ignore »:
A few points on ignored issues
- Issues marked as ignore will not appear in searches and reports unless explicitly requested. An important note, however, is that the issue information itself is not removed from Klocwork when an issue is marked as ignored. If at any time you wish to review/restore ignored issues, you can search « status:Ignore » within the search bar and they will be visible.
- If you activate new checkers or deploy new custom checkers into the project, or if the third-party vendor releases a new version/patch that you then integrate into your project, there is a chance that new issues within the third-party code will be detected. Therefore, we advise repeating the above steps on any change to the checker configuration of your project to ensure you have an up-to-date filter on third-party issues.
- If your organisation monitors the changing of issues more comprehensively (usually due to the need to meet certain strict compliance standards), then when ignoring issues we recommend leaving a comment explaining its link to third-party code. By doing this, the reason for the exclusion is clear to auditors.
2. Handling third-party code in Klocwork: Organising into Modules/Views and Filtering
Analyze everything, including third-party code, then filter out issues present within this code using Klocwork Modules and Views. This is Emenda’s preferred method.
Let’s start by creating a module. For those unfamiliar, a module is a subset of your project’s codebase mainly used to filter search queries more easily. First, select the « Modules » tab within your Klocwork project. In this case, we want to create a module that contains all third-party code. For our CVS project, that is all code within the « cvs\lib\ » directory, so we specify « cvs\lib\ » as a path pattern (of which you can have several) and save the module with an appropriate name (and tag if desired). Alternatively, you can also select the paths from a tree view by selecting the « Use tree » button.
A quick note on tags in Klocwork
Tags are terms used to filter and sort your projects, views and methods. For example, say you have several third-party libraries and you want to maintain separate modules for each. You might give all these modules the tag « third-party », allowing you to quickly filter out other modules when maintenance of your third-party code is needed. Tags are also used for cross-project reporting. We won’t go into that in this article, but if you want to find out more you can visit Roguewave’s documentation on the matter here.
Using the search within the « Issues » tab we can now view this module in action:
Of course, this is exactly the same as what we saw in figure 3 when searching based on file path! To streamline things further, we need to integrate this module into a view, which can be seen as a global filter for which issues are seen when viewing your project in Klocwork Review. Select the « View » tab and create a view that, as its search, excludes the « third-party » module:
By doing this, we have created a view that filters out any issues present within the « third-party » module. More specifically, any issues present within the paths defined within the « third-party » module.
The only thing remaining is to enable this view. The toggle for such is located in the top right corner of Klocwork Review, as shown below:
If all has been configured correctly, enabling the view should reduce the number of issues you see.
Advantages of this method
Ease of maintainability: There is a nuanced but useful difference between this method and bulk-marking issues as ignored. With this method, new third-party issues introduced in later builds (perhaps due to a change to your project’s checker configuration or an update/patch to the third-party library) will be automatically excluded, as these issues will still be caught within the directory paths defined by the module.
Ease of reporting: Another advantage of using modules and views to handle third-party code in Klocwork is that the reports visible within Klocwork review update dynamically depending on the view being used, but without actual modification of the issues themselves. As a result, we can easily visualise the effect removing third-party issues has on our project, and return to view the original graphs easily by turning off the view. For example, the « Top Open Issues » before and after applying the « exclude-third-party » View for the CVS project can be seen below:
This feature is really helpful when justification of resource allocation to various issues is required, as it provides a more accurate picture of the real problems within your code without flooding your issue lists with ignored issues.
A note on Modules and Views
A more comprehensive tutorial covering modules and views will follow shortly on our website. In the meantime, you may find useful to know that Roguewave have a video available outlining their use, which you can watch here.
3. Handling third-party code in Klocwork: kwinject’s « –ignore-files » command
Another (more complex) option to handle third-party code in Klocwork is to ignore it from the beginning, before even running a Klocwork analysis over your codebase. While generating the build specification file of your codebase using ‘kwinject’, we can use the ‘–ignore-files’ option to filter out any files we do not want to analyse.
If this method sounds more appropriate for your organisation, please note that these build specification files are essential to Klocwork’s understanding of your code, as Klocwork uses these files as input to its own internal compiler when running its analysis. Hopefully, therefore, you can see problems that may arise as a result of this exclusion. For example, if files containing memory allocation functions are excluded from the analysis (in this case, if these functions are part of a third-party library!), then the analysis may fail to report a memory leak in your code.
Overall, this method of handling third-party code in Klocwork should be used with extreme caution and with the comprehensive know-how of the code being ignored. Given the advantages and ease of implementation of methods 1 and 2 discussed above, this method is not recommended by the Emenda team.
4.Handling third-party code in Klocwork: Knowledge base file manipulation
The fourth and final method for handling third-party code in Klocwork requires some slightly deeper understanding of Klocwork.
This method involves something called the Knowledge Base file (.kb extension in C/C++, .kjb in Java), a Klocwork-generated file which contains a record for each function that operates within your code, as well as how these functions interact with one another. They are really quite incredible files, and to the trained eye (hint hint, Emenda!) can be manipulated extensively to tune Klocwork’s issue detection to reduce false positives or false negatives in your C/C++ and Java results. If you are interested in learning more about these files, Roguewave has detailed reference documentation to help understand the syntax and to tune the .kb files to your needs. Alternatively, we here at Emenda offer training and fine-tuning of these files to make your Klocwork results are as accurate as possible. Just get in touch!
Above, we mentioned that a big problem using method 3 to handle third-party code in Klocwork is that it leaves a ‘hole’ in Klocwork’s understanding of your codebase. This ‘hole’, in fact, is a gap in the knowledge base file Klocwork has generated for your code because of the exclusion of these files during the build specification generation. The solution, then, is to fill this gap in Klocwork’s knowledge base without introducing the third-party code into your project at any point. To do this, we:
- Create a separate project for the third-party code in complete isolation from your application code.
- Use Klocwork to generate a knowledge base file of this third-party code.
- Import the generated knowledge base file into your Klocwork project that contains your application code.
- To generate a knowledge base file, you need to run a Klocwork analysis over the code. The resultant .kb file will be located in <klocwork tables directory>/clef/generated.kb.
- To import this knowledge base file into your Klocwork project, run the command:
kwadmin import-config <Klocwork project name> <knowledge base file>
Following the import of this new knowledge base file, Klocwork should now have a complete understanding of the third-party code, just as if the code itself was not excluded from the project.
Precautions when choosing this method
- Klocwork cannot update results of past analyses upon a retrospective change to its understanding of the codebase. Because of this, a new full build analysis needs to be performed after importing the knowledge base file, so that Klocwork can re-analyse the code with its more complete understanding.
- Just as with method 1, this method is more time-consuming the more the third-party codebase is updated. In this case, it is because it requires the maintainer to update the knowledge base file of the third-party code each time, import this file into the main project and run another full build analysis. Therefore, only choose this method if the third-party code is updated infrequently.
In this article, we’ve covered the various ways of managing third-party code in Klocwork. Our goal has been to demonstrate that there really is an option for everyone, and we hope we have done just that. If you would like further information on the methods available, help to select the most appropriate method for your organisation or help with the integration of these methods, we here at Emenda would be happy to help. You are welcome to contact the Emenda team at firstname.lastname@example.org with any queries.
About the Author
Working as a security consultant for Emenda for the past 4 years, Ben’s work has taken him all over Europe securing the systems of organisations big and small. Currently working for the Emenda Nordic family, he is just one of our many experts in software safety and security ready to support your organisation. You are welcome to reach out to him directly at email@example.com, or to the Emenda team at firstname.lastname@example.org.