Authoring A Warning Processor

• Basics
• Considering Processor Application
• Display Scripts
• Other Warning Processor Sections

Basics

The essential requirements for a warning processor are as follows.

• It must accept the required commands.
• The hub must be able to execute it. If the warning processor is not itself an executable, a wrapper (.sh or .bat file) must be provided.

Within these constraints there is a great deal of flexibility. For example, a warning processor may be written in any language.

The procedure for creating a custom warning processor will generally look something like the following.

1. Decide on the appropriate mode for the processor.
2. Implement handling for the required commands.
   • Make sure that warning processor input and output are handled correctly.
3. Decide whether or not you want a custom display script.
   If so, create one and make sure that your processor's install command emits it to stdout.
4. If necessary, create a wrapper for executing the processor.
5. Install the warning processor.

Execution Environment

CodeSonar will execute the warning processor executable or wrapper in an environment with two available environment variables.

Python Warning Processor Utilities

We provide a package, csonar_utils, containing useful functionality for authoring Python warning processors. See Authoring Python Warning Processors: The csonar_utils Package for details.

Considering Processor Application

It is useful to consider how your processor will be applied as part of your design process, because it will affect the set of commands you will need to implement and the input and output you will need to work with.

Some warning processors are equally suited to interactive application and automatic application. In most cases, though, a warning processor will be suited to only one or the other.

• Design for interactive application if any of the following apply.
  • The processor needs to interactively obtain information from the user.
  • The processor makes use of user session data.
  • You don't want the processor to be applied to every warning submitted to the hub.
• Design for automatic application if any of the following apply.
  • You want to utilize the analysis_transition command (for example, to send summary email messages about all the activity carried out by the processor for a specific analysis).
  • You want the processor to be automatically applied to every warning submitted to the hub.

Display Scripts

A display script allows you to:

• request an extended version of the XML input to the warning processor, and
• customize the way the warning processor is presented in Warning Reports.

You do not have to define a display script if you do not want to do either of these.

• Define a display script if you want to do any of the following.
  • Access the id attributes of priority, state, finding, or user elements in the XML input to the warning processor. These attributes are only included if the display script specifies that they are required.
  • Hide the warning processor from the Change Warning form.
  • Add additional rows to the Warning Details table.
  • Provide additional text in the Change Warning form (beyond the processor label).
  • Specify conditions under which the option to apply the warning processor should not be offered (for example, you may wish to specify that the processor should only be offered if it has not already been applied to the warning).
• You don't need to define a display script if both of the following are true.
  • Your warning processor does not access the id attributes of priority, state, finding, or user elements in the XML input.
    and
  • You do not require any display customization. (The default presentation is a checkbox that is labeled with the processor label and is always available.)

Display Script Authoring Guidelines

A warning processor display script...

• ... must be emitted to stdout by the warning processor install command.
• ... must be a Python code snippet.
• ... must contain the following comment line if your warning processor accesses the id attributes of priority, state, finding, or user elements.
  

  # CSONAR_WP_CAPABILITY:PROPERTY_IDS
  

  (If you don't require other display script functionality, the display script may consist only of this comment.)
• ...will be executed in a scope containing several variables that may be useful: display, notes, is_change_multiple, CSHUB_PROCESSORS_HOME.

  display	An object with three methods that control the warning processor's presentation in the Warning Report. display.add_resource(title, content) adds a new row to the Warning Details table, with title as the row heading and content as the corresponding content. display.label_checkbox(label) changes the label of the warning processor's checkbox in the Change Warning form to label. display.hide_checkbox() removes the warning processor's checkbox from the Change Warning form (unless there is a subsequent call to display.label_checkbox()).
  notes	A list of strings, representing the warning Notes (one string per comment, in chronological order). Note that this is a read-only representation: the display script does not update the Notes.
  is_change_multiple	A Boolean that is True if and only if the display script is invoked via Change Multiple Warnings.
  CSHUB_PROCESSORS_HOME	The path to the hub's warning processor installation directory (hubdir/processors/, where hubdir is the hub directory). This path information is also available directly to the warning processor executable or wrapper as environment variable CSHUB_PROCESSORS_HOME (same name as this variable).

Example Display Script

The bugzilla warning processor shipped with CodeSonar includes a display script: see $CSONAR/py/processors/bugzilla/display.py.

Other Warning Processor Sections

The following sections contain further information about warning processors.