Writing Python Plug-Ins For CodeSonar

JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

If you access the manual through the hub's Web GUI, the functionality will not be suppressed because the hub is a web server.
Alternatively, your browser may allow you to explicitly disable the security setting that suppresses functionality. See the CodeSonar FAQ for more information.

CodeSonar^® 9.2p0

CONFIDENTIAL

CodeSecure Inc

C and C++

Binaries

Writing Python Plug-Ins For CodeSonar

Python plug-ins are self-contained scripts that are executed automatically when CodeSonar starts up. This section describes how to write and install Python plug-ins.

For general information about CodeSonar plug-ins, see section CodeSonar Plug-In API.
For an annotated example plug-in, see the Plug-In API Tutorial.
You may find the Python Console helpful for developing and debugging Python plug-ins.

CodeSonar SaaS Note: If you want to use your own custom plug-ins with CodeSonar SaaS, contact CodeSecure support for assistance. The installation instructions provided in this page are not sufficient to make plug-ins available to SaaS analyses.

Overview
Create Source File(s)
Install
Implementation Notes
More on Plug-Ins

Overview

To create and use a CodeSonar Python plug-in, do the following:

Create Python source file(s) for the plug-in.
Save the plug-in in directory $CSONAR/codesonar/plugins, where $CSONAR is the CodeSonar installation directory.

Note that the top-level plug-in file must be a Python source (.py) file. It can import compiled Python (.pyc), but cannot itself be compiled.

Create Source File(s)

Suppose you want to define a plug-in called pname.

The following table describes plug-in file content and naming requirements, and summarizes some key implementation guidelines. Full details are provided in the remainder of this page.

File content requirements	Import the cs module. import cs (The plug-in code does not need to perform any registration.)
File name requirements	Depend on plug-in's installation location. in $CSONAR/codesonar/plugins: name must be of the form pname_plugin.py or pname.plugin.py. in another location, specified with PLUGINS: no restrictions.
Add visitors	In top-level scope.
Define new warning classes; define new metric classes	In top-level scope.
Key API Elements	Visitor decorators, Metric decorators; classes analysis, warningclass, project_metricclass, compunit_metricclass, sfile_metricclass, procedure_metricclass.
Annotated Examples	Plug-in Tutorial: Python, AST Tutorial: Python

(Further implementation notes are provided below.)

Install

Save the plug-in as $CSONAR/codesonar/plugins/pname_plugin.py or $CSONAR/codesonar/plugins/pname.plugin.py, where $CSONAR is the CodeSonar installation directory. It will be automatically loaded and run when CodeSonar runs.

If you want to save the plug-in in a different location, use the PLUGINS configuration file option to specify its file path so that CodeSonar can load and run it.

Adding Visitors

Add visitors	in the top-level scope of the plug-in.
Adding: all visitors except step visitors	Define a visitor function in the top-level scope of your plug-in. Declare the function to be a visitor by applying the appropriate visitor decorator.
Adding: step visitors	Subclass step_state to characterize your step visitor. Create an object of the subclass. Pass the object to analysis.add_step_bottom_up_visitor().

The following table lists the available methods and decorators for adding visitors.

Build/Analysis Phase	Add visitors with
drop traversal	@project_drop_visitor @compunit_drop_visitor @procedure_drop_visitor @global_symbol_drop_visitor @project_drop_finish_visitor
after drop traversal, before anything else	(do setup work in top level scope of plug-in)
after setup visitors, before serial depth-first analysis phase	@project_visitor
serial depth-first analysis phase	@compunit_visitor @sfile_visitor @sfileinst_visitor @sfileinst_finish_visitor @sfile_finish_visitor @procedure_visitor @point_visitor @symbol_visitor @procedure_finish_visitor @compunit_finish_visitor
after serial depth-first analysis phase, before any program parallel visitors	@project_finish_visitor
after program finish visitors, before parallel depth-first analysis phase	@project_parallel_visitor
parallel depth-first analysis phase	@compunit_parallel_visitor @sfile_parallel_visitor @sfileinst_parallel_visitor @sfileinst_parallel_finish_visitor @sfile_parallel_finish_visitor @procedure_parallel_visitor @point_parallel_visitor @symbol_parallel_visitor @procedure_parallel_finish_visitor @compunit_parallel_finish_visitor
after parallel depth-first analysis phase, before any program bottom-up visitors	@project_parallel_finish_visitor
after pointer analysis phase, before bottom up analysis phase	@project_bottom_up_visitor
bottom-up analysis phase	@procedure_bottom_up_visitor @point_bottom_up_visitor analysis.add_step_bottom_up_visitor() @procedure_bottom_up_finish_visitor
after bottom-up phase (all traversal is finished)	@project_bottom_up_finish_visitor
(periodically, as analysis progresses)	@cache_cleanup_visitor

New Warning Classes

Warning Class type	warningclass
Warning Class flag type	warningclass_flags
Must be defined	in the top-level scope of the plug-in.
Defined with	analysis.create_warningclass()

Issuing Warnings

Issue warnings with one of the following.

warningclass.report() - returns a result indicating whether or not the warning was successfully reported.
warningclass.report_return warning() - returns the reported warning object (or throws a result).

Both methods are overloaded to account for all warning-issuing cases. See the warningclass class description for details.

Retracting Warnings

Retraction info parameter type (when warning reported)	warning_retraction_info
Manually retract with	warning.retract()

Warning Class Information

Warning Class Information	Method
ID (a numeric identifier)	warningclass.get_id()
Name	warningclass.name()
Are WARNING_FILTER settings such that instances of this warning class will always be ignored?	warningclass.always_discarded()
Retrieve class by ID or name	analysis.lookup_warningclass() (overloaded)

New Metric Classes

Metric class type	project_metricclass compunit_metricclass sfile_metricclass procedure_metricclass
Metric class flag type	metricclass_flags
Must be defined	in the top-level scope of the plug-in.
Defined with	Definition mechanism depends on whether the metric is to be reported automatically or manually. For automatically-reported metrics, apply a suitable metric decorator to the computation function: @project_metricclass_function @compunit_metricclass_function @sfile_metricclass_function @procedure_metricclass_function For metrics that will be reported by the plug-in, use the create() method of the metric class manager with the corresponding granularity: project_metricclass_manager.create() compunit_metricclass_manager.create() sfile_metricclass_manager.create() procedure_metricclass_manager.create()

Reporting and Retracting Metric Values

Automatically-reported metrics are computed and reported automatically by the CodeSonar analysis. Manually-reported metrics must be reported explicitly by the plug-in.

Both automatic and manual retraction can take place.

Manually report with	The metric class report() method. project_metricclass.report() compunit_metricclass::report() sfile_metricclass::report() procedure_metricclass::report()
Manually retract with	The metric class retract() method. compunit_metricclass.retract() sfile_metricclass.retract() procedure_metricclass.retract() (All analysis-granularity metrics are automatically retracted.)

Other Metric Functionality

Functionality	Metric Class Method	Links
Get the granularity of a metric class.	none: granularity is implicit in type of metric class object.	-
Get the tag (short identifier) of a metric class.	tag()	project_metricclass.tag() compunit_metricclass.tag() sfile_metricclass.tag() procedure_metricclass.tag()
Get the description (longer, human readable description) of a metric class.	description()	project_metricclass.description() compunit_metricclass.description() sfile_metricclass.description() procedure_metricclass.description()
Get the flags associated with a metric class.	flags()	project_metricclass.flags() compunit_metricclass.flags() sfile_metricclass.flags() procedure_metricclass.flags()
Look up a metric class.	lookup()	project_metricclass_manager.lookup() compunit_metricclass_manager.lookup() sfile_metricclass_manager.lookup() procedure_metricclass_manager.lookup()
Get the value of a specified metric for a specified program element.	value()	project_metricclass.value() compunit_metricclass.value() sfile_metricclass.value() procedure_metricclass.value()
Iterate over all metric classes with a specified granularity.	metricclasses()	project_metricclass_manager.metricclasses() compunit_metricclass_manager.metricclasses() sfile_metricclass_manager.metricclasses() procedure_metricclass_manager.metricclasses()

More on Plug-Ins

General Information:

Visitors	Plug-ins are based on visitors, which specify actions to be carried out on elements of the CodeSonar internal representation (IR) at various stages of the analysis.
Writing Plug-Ins	General information about creating plug-ins to attach custom functionality to the CodeSonar analysis.
Custom Checks: Accounting for Incrementality	Ensuring that custom checks implemented in plug-ins generate appropriate results in incremental analyses.
Plug-In Tutorial	Two annotated example plug-ins (each provided in all API languages), with building and installation instructions.
AST API Tutorial	The AST API tutorial (provided in all API languages) also uses plug-ins.

Additional sample plugins can be found at $CSONAR/codesonar/plugins/*.py where $CSONAR is your CodeSonar installation directory.

Specific API Language:

	Plug-In Guidelines	Key API References
C++	Writing C++ Plug-Ins	classes analysis, visitor, warningclass, project_metricclass, compunit_metricclass, sfile_metricclass, procedure_metricclass.
Python	Writing Python Plug-Ins (this page)	Visitor decorators, Metric decorators; classes analysis, warningclass, project_metricclass, compunit_metricclass, sfile_metricclass, procedure_metricclass.
C	Writing C Plug-Ins	CodeSonar Plug-In API: C Functions and Types for Visitors, Warnings, and Metrics

To report problems with this documentation, please visit https://support.codesecure.com/.