GUI: Searching

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

General

GUI Reference: Searching

Users of the CodeSonar Web GUI can search for warnings and metrics, as well as for various software artifacts. Several searching mechanisms are provided, along with functionality for creating and then applying saved searches.

This section provides an overview of search functionality in CodeSonar, and provides links to reference sections that contain further detail.

Search Overview
Executing a Search
Saved Searches
Search Languages
Permissions

Search Overview

Every CodeSonar search involves a (possibly empty) set of constraints to be imposed within a specified domain and scope. When a search is executed in the GUI, CodeSonar presents the recovered information in a search results page, which provides browsing, modification, and save functionality.

Domain

The search domain specifies what kind of item you are searching for. CodeSonar support searching in eight different domains, described in the following table.

Searches in the various domains work by matching against elements of the project internal representations (IR) stored by CodeSonar. For domains whose corresponding IR requires full CodeSonar analysis of the project — Code and Procedures — search results will only include elements from project code that has undergone such analysis. This means that results from these domains will only cover C/C++, C#, and Java code. For other domains, the required IR is available for all analyses, independent of the language or languages involved, so results can cover elements from any analysis. This includes, for example, analyses created by importing SARIF results.

domain	search results are...	...each linked to	analyzed languages
Warnings	Warnings	a Warning Report.	Any
Files	Source file instances	a Source Listing.	Any
Code	Occurrences of non-keyword tokens	the corresponding line in a Source Listing.	C/C++, C#[], Java[]
Procedures	Procedures	the procedure definition in a Source Listing.	C/C++, C#, Java
Metrics	Code components for which metric values will be reported, plus the corresponding metric values.	the relevant code component. For file-granularity metrics, this is the file's Source Listing. For procedure-granularity metrics, it is the procedure definition (within a Source Listing).	Any
Analyses	Analyses	the corresponding Analysis page.	Any
Projects	Projects	the Analysis page for the most recent analysis of the project.	Any
Warning Categories	Warning Categories	nothing: searches in this domain are used for warning category filtering.	Any
Users	Hub User Accounts	the corresponding Account Editor page.	Any

[*] For Java and C#, code search will only find occurrences of tokens that are defined in user code. Tokens defined in the respective language runtimes are not searchable.

Scope

The search scope specifies where, and how broadly, the search will be conducted. There are four possible scopes in the CodeSonar GUI; in most situations only some of them are available.

scope	search coverage
last analyses	The most recent analysis of each project on the hub.
all projects	All analyses on the hub. (For searches in the Projects domain: all projects on the hub. For searches in the Warning Categories domain: all categories. For searches in the Users domain: all hub user accounts.)
this analysis	The current analysis. (Only available from GUI pages related to a specific analysis, such as Analysis, Analysis Files, all types of Log.)
these results	The current search results. (Only available from Search Results pages.)

In general:

searches in the Code, Procedures, and Metrics domains can only be carried out within the scope of a single "focal" analysis (or narrower),
Warnings and Files searches can also be carried out both within the scope of a single analysis and in broader scopes,
Analyses, Projects, Warning Categories, and Users searches are necessarily broadly scoped.

Saved Search Execution Scope, below, discusses domain-specific scope issues for saved searches.

Executing a Search

For any search domain, there are several kinds of search that can be executed:

new searches based on user-provided constraints,
modifications of existing searches,
saved searches.

In all cases, search results are presented in the GUI.

CodeSonar's charting capabilities also interact with searching:

Constraints on charted data are specified using CodeSonar search functionality.
Clicking a chart component is equivalent to executing a search for the elements (warnings, files, or metrics) summarized by that component.

Specifying a New Search

CodeSonar provides two mechanisms for specifying new searches in all domains.

GUI Feature	Search Application
Simple Search tool	Provides full-text and search language searching directly from all GUI pages. (For Metrics searches, the simple search tool governs the component search only).
Advanced Search page	Allows users to specify the desired values of one or more properties in a selected search domain.

Metrics domain only: the Create New Report section of a Metric Report Creation page allows users to execute a new search by specifying the metrics included and table limit for the resulting report.

The following Tasks demonstrate various new searches in the Warnings domain.

Modifying an Existing Search

The general method for modifying an existing search is as follows.

Execute the original search (using any of the mechanisms described in this section).
From the search result page, specify your modifications.
- To refine the current set of results, use the simple search tool. Select D in these results from the domain/scope menu (where D will depend on the search domain), then enter your additional constraints in the text field and click Search.
- To change one or more of the constraints specified for the original search, use the simple search tool. Examine the search language expression currently displayed in the text field: this expression describes the executed search. Edit the expression in the text field according to the changes you want to make, then click Search.
- [Metrics domain only] to modify the metrics included or table limit, use the Edit Report tool on the Metric Report page.

Task: Refine a search demonstrates a search modification in the Warnings domain.

Search Results

Search results are presented in the CodeSonar Web GUI in page types that depend on the search domain, as shown in the following table.

Search Domain	Result Page Type
Warnings	Warning Search Results
Files	File Search Results
Code	Code Search Results
Procedures	Procedure Search Results
Metrics	Metric Report
Analyses	Analysis Search Results
Projects	Project Search Results
Warning Categories	Warning Category Search Results
Users	User Search Results

Saved Searches

All search result pages include functionality for saving the search constraints and giving this "saved search" a name so that it can be applied later. Saved searches are securable resources.

The following information is saved, and can subsequently be viewed on the appropriate tab of the Saved Searches page.

Name	so that the search can be identified later.
ID	a unique numerical identifier for the saved search.
Search	a search language expression that describes the user-specified search constraints along with any constraints imposed by the visibility filter setting.
Scope	the scope in which the search was carried out.
Domain	is implicit.
Created	the timestamp for the first saved search of this name.
Modified	the timestamp for the most recent saved search of this name.
Metrics	[Metric searches only] the metrics included in the search.

Saving A Search

Domain-specific Save documentation is provided in the GUI Reference for the search result pages: Warnings, Files, Code, Procedures, Metrics, Analyses, Projects, Warning Categories, Users.

Using a Saved Search

There are four mechanisms for applying saved searches. Execution scope and permission issues are discussed elsewhere in this page.

GUI Feature	Saved Search Application	For more information
Advanced Search page	Each domain tab includes a menu of the saved searches in that domain. A search selected from one of these menus is executed immediately.	Advanced Search: Search Controls
Saved Searches page	Each domain tab contains a table of the saved searches in that domain. Users can click a table entry to execute the corresponding search (if execution is still possible). There is also functionality for deleting saved searches.	Saved Searches: Table of Saved Seaches
Visibility Filter	When a page contains a visibility filter selector for a particular domain, the filter candidates offered are the saved searches in that domain. If a filter is selected, the corresponding search constraints are applied to the current page contents. The saved scope is not applied. When you save a search, the visibility filter setting is recorded as part of the search definition.	Visibility Filter
Warning Category Filtering	[Warning Category domain only] Saved Warning Category searches can be applied to filter the set of warning categories displayed on GUI pages that contain warning information.	Warning Category Filtering

Metrics domain only: the Open Saved Report section of a Metric Report Creation page is another way to execute a saved search.

Saved Search Execution Scope

When you save a named search, the originally specified scope is recorded. The scope used when you execute the search from the Saved Searches page depends on several factors:

The original scope.
The search domain.
Whether the domain is an analysis that has subsequently been deleted, or an analysis of a project that has subsequently been deleted.
[For some domains] Whether there have been subsequent analyses of the same project, or other activity that affects the content of the project analysis directory (pfilesname.prj_files/).

Scope behavior depends on the search domain:

Warnings
Files
Code
Procedures
Metrics
Analyses
Projects
Warning Categories
Users

Warnings and Files

Warnings and Files searches are based on properties that are recorded on the hub for each analysis and project.

A saved search in either of these domains will execute in the scope originally specified for the search, unless that scope no longer exists.

If the original scope was restricted to an analysis that has since been deleted, CodeSonar will execute the search with scope set to the most recent analysis of the same project.
If the original scope was restricted to a project that has since been deleted, clicking the line will have no effect.
If the original scope was restricted to an analysis of a project that has since been deleted, or that has no remaining (undeleted) analyses, clicking the line will have no effect.

Code and Procedures

Code and Procedures searches are based on properties that are recorded in the project analysis directory. In consequence, only the information from the most recent analysis of each project is generally available for searching (see Procedures: Availability for full details).

Metrics

Saved searches in the Metrics domain have a hybrid approach: the saved component search essentially describes both a Files search and a Procedures search, and the saved metrics included set can contain file-granularity metrics, procedure-granularity metrics, or both.

Scope for the Files-related part of the component search is determined in the same way as scope for a Files search. File-granularity metric values are reported with respect to this scope.
Scope for the Procedures-related part of the component search is determined in the same way as scope for a Procedures search. Procedure-granularity metric values are reported with respect to this scope.

Analyses

Searches in the Analyses domain are based on properties that are recorded on the hub for each analysis and project.

A saved search will execute in the scope originally specified for the search, unless the original scope was restricted to a project that has since been deleted (in which case clicking the line will have no effect).

Projects, Warning Categories, and Users

The Projects, Warning Categories, and Users domains have only one available scope: the whole hub. All saved searches, as well as all new searches, are therefore executed in this scope.

Search Languages

CodeSonar provides a family of powerful and flexible search languages: one search language for each domain. Each of these languages allows users to specify precise constraints on one or more properties in a specific search domain, and provides basic logical operators for combining multiple conditions. Searches can thus be as simple or as complex as required.

Search language expressions can be used in several contexts within the CodeSonar Web GUI.

on any page	Enter a search language expression in the simple search tool and click Search to execute a new search.
on any search result page	The search language expression describing the executed search is displayed in the simple search tool. You can modify the expression and then use it to execute a correspondingly modified search.
in the chart wizard	Use in the search tab to specify which warnings should be charted.

Note that the Metrics search language governs the component search only.

The search languages are documented individually: Warnings, Files, Code, Procedures, Metrics, Analyses, Projects, Warning Categories, Users.

Permissions

CodeSonar permissions apply to searching as follows.

Search Execution/Results

Search execution and results will always take into account the permissions held by the user performing the search.

Search Domain	Execution Requirements	Result Constraints (if executed)
Warnings	Depends on search scope: single analysis: ANALYSIS_READ for that analysis single project: PROJECT_READ for that project otherwise: search is executed.	Results only include warnings that belong to analyses for which the user has ANALYSIS_WARNING_EXISTS permission.
Files	Depends on search scope: single analysis: ANALYSIS_READ for that analysis single project: PROJECT_READ for that project otherwise: search is executed.	Results only include files that belong to analyses for which the user has ANALYSIS_READ permission.
Code	ANALYSIS_READ for the focal analysis	Results include all code that matches the search constraints.
Procedures	ANALYSIS_READ for the focal analysis	Results include all procedures that match the search constraints.
Metrics	ANALYSIS_READ for the focal analysis	Results include all metrics that match the search constraints.
Analyses	Depends on search scope: single project: PROJECT_READ for that project otherwise: search is executed.	Results only include analyses for which the user has ANALYSIS_EXISTS permission.
Projects	Always executed.	Results only include projects for which the user has PROJECT_EXISTS permission.
Warning Categories	Always executed.	Results include all matching categories that have appeared in analysis results submitted to the hub.
Users	G_ADMINISTER_USERS or G_LIST_USERS. Some field-condition terms in the user search language can only be used with G_ADMINISTER_USERS permission.	G_ADMINISTER_USERS: results include all users on the hub that match the search constraints. G_LIST_USERS only: results include all users on the hub that match the search constraints and have G_SIGN_IN permission (that is, enabled users). Some columns of the result table are only available to users with G_ADMINISTER_USERS permission.

Saved Searches

Saved searches are securable resources. As such, operations on saved ("named") seaches themselves are controlled by CodeSonar permissions.

Saving	If a user attempts to save a named search with name N, behavior depends on whether or not the user has NAMEDSEARCH_EXISTS permission for any existing saved search S in the same search domain with the same name N. If there are multiple such searches, CodeSonar considers only the most recently modified one. YES: If the user has NAMEDSEARCH_WRITE permission for S and specifies that they wish to overwrite, CodeSonar will overwrite the definition of S with the new search. If the user does not specify overwrite, they will not be able to save a search with name N. NO: CodeSonar creates a new saved search with name N. This can result in a situation where multiple searches in the same domain have the same name. When a user creates a new named search S, the user's default role is assigned all NAMEDSEARCH_* permissions for S.
Viewing and Using	NAMEDSEARCH_EXISTS permission for a given saved search is required in order to see that search in lists of searches (described below), and to apply it.
Deleting	Deleting a saved search requires NAMEDSEARCH_DELETE permission for that search.

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