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.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc
General

codesonar dump_warnings.py: Download Specified Warnings

The codesonar dump_warnings.py command downloads warning information directly from the hub in CSV, JSON, or text format, without the need to interact with the CodeSonar Web GUI or write a custom script. The set of downloaded warnings and the warning information downloaded are fully customizable.

Overview

The codesonar dump_warnings.py command downloads warning information directly from the hub in CSV, JSON, or text format, without the need to interact with the CodeSonar Web GUI or write a custom script. The set of downloaded warnings and the warning information downloaded are fully customizable.

This page provides a full description of the codesonar dump_warnings.py command and all its options, with some examples for illustration.

dump_warnings.py is a codesonar Python subcommand.

Note: If you want to download all warnings from a specific analysis, you may prefer to retrieve the /analysis/analysis_id-allwarnings.xml URL. For example, to download all warnings from the analysis with ID 5 from the hub at http://myhub:7340, use http://myhub:7340/analysis/5-allwarnings.xml.

Command Line

The general form of the command line for downloading warning information is:

codesonar dump_warnings.py [-h]
[--project-file path/to/prjfile] [--project-name prjname] [--analysis-id aid] [--analysis-url aurl] [--search search_term]
[--hub [protocol://]host:port]
[--show-column "colname"] [--sort "ascending:colname"] [--sort "descending:colname"]
[--format "fmtstr"] [--csv] [--json] [--sarif]
[--fail-if-more-warnings-than max_warnings] [--gained-since-previous-analysis] [--lost-since-previous-analysis]
[--visible-warnings warning_filter] [-t max_seconds] [--src-root /path/to/repo] [--sarif-detail detail_level]
[--metrics-csv path/to/csv_outfile] [--metrics-xml path/to/xml_outfile]
[-auth authtype] [-hubuser username] [-hubpwfile pwfile] [-hubbearerfile bearerfile] [-hubcert certfile] [-hubkey privatekeyfile]
[-o outfname]

The following constraints apply:

[-h]
[--help] 		Show a help message and exit.
[--project-file path/to/prjfile] Get warnings from the most recent analysis of the project whose project file is path/to/prjfile.
  • The project file has file extension .prj and is a sibling of the analysis directory.
  • The set of retrieved warnings will be those from the analysis saved to the specified project file.

    This is not necessarily the last analysis of the project, because the project may have subsequently been analyzed in a different location. For example, it may have been analyzed by a different user on a different machine.

  • If specified multiple times, only the last path/to/prjfile is used.
  • The set of retrieved warnings can be further refined with other options: --gained-since-previous-analysis, --lost-since-previous-analysis, --search, --visible-warnings.
[--project-name prjname] Get warnings from the last analysis of the project whose name is prjname.
[--analysis-id aid] Get warnings from the analysis whose ID is aid.
[--analysis-url aurl] Get warnings from the analysis whose Analysis:Warnings page URL is aurl.
[--search search_term] Get only warnings that satisfy the constraints in search_term.
[--hub [protocol://]host:port] The hub location. If you don't specify a location, CodeSonar will determine one as follows.
  • If --analysis-url aurl is specified, the hub location is derived from aurl.
  • Otherwise, location [::1]:7340 is used.
[--show-column "colname"] Add colname to the list of retrieved columns.
  • colname must be one of the available column names listed below.
  • If colname is already present in the list of retrieved columns, --show-column "colname" will have no effect.
  • If --show-column is specified in combination with --format, the command will fail with an error.
  • If --show-column is specified in combination with --sarif, the command will fail with an error.
[--sort "ascending:colname"]
[--sort "descending:colname"] 		Sort the retrieved warnings in ascending (descending) order by the colname column.
  • colname must be one of the available column names listed below.
  • If --sort is specified in combination with --sarif, the command will fail with an error.

If --sort is specified multiple times, sort conditions specified later on the command line are used to sort within the ordering constraints imposed by conditions specified earlier on the command line.
[--format "fmtstring"] Specify the format for plain text output, where fmtstring is a Python printf-style format string.
  • The default format string is:
    %(file)s:%(lineNumber)s:%(class)s
  • Keyword arguments in fmtstring must correspond to column names.
  • The set of retrieved columns will be exactly the set of keyword arguments specified in fmtstring.
  • If --format is specified in combination with --show-column, the command will fail with an error.
  • If --format is specified in combination with --csv, --json , or --sarif, the command will fail with an error.
[--csv]
[--json] 		Retrieve the warning information in the specified format: CSV or JSON.
  • All retrieved columns will be included in the output.
  • If --csv or --json is specified in combination with --format, the command will fail with an error.
  • At most one of {--csv, --json, --sarif} can be specified. If more than one is specified, the command will fail with an error.
[--sarif] Retrieve the warning information in SARIF format.

The --sarif option is not compatible with any of the following. Specifying these combinations will cause the command to fail with an error.

The --src-root and --sarif-detail options control aspects of the SARIF output.
[--fail-if-more-warnings-than max_warnings] If this is specified and more than max_warnings warnings satisfy the constraints imposed by the remainder of the command, the command will run as usual (including producing output) but then exit with a non-zero return code. This option is provided for use with continuous integration pipelines that should fail if there are too many CodeSonar warnings.
If not specified, there is no such bound on the number of warnings.
[--gained-since-previous-analysis]
[--lost-since-previous-analysis] 		This functionality corresponds to GUI-based analysis comparison, where the 'previous' analysis is determined with respect to the 'current' analysis determined by the other arguments.
  • If --analysis-id aid is specified, the current analysis is the analysis whose ID is aid.
  • Otherwise, if --analysis-url aurl is specified, the current analysis is the analysis whose ID is encoded in aurl.
  • Otherwise, if --project-file path/to/prjfile is specified, the current analysis is the analysis saved to the specified project file.
  • Otherwise, if --project-name prjname is specified, the current analysis is the last analysis of the indicated project.
  • Otherwise, there is no notion of a current analysis and no warnings will be retrieved when --gained-since-previous-analysis or --lost-since-previous-analysis is specified.
--gained-since-previous-analysis Include only warnings that are in the current analysis but not the previous analysis.
--lost-since-previous-analysis Include only warnings that are in the previous analysis but not the current analysis.
  • Cannot be specified in combination with --search query. If one of these is specified, any specified --search option will be ignored.
  • At most one of {--gained-since-previous-analysis, --lost-since-previous-analysis} can be specified. If both are specified, --gained-since-previous-analysis will be applied.
[--visible-warnings warning_filter] The specified Visible Warnings filter is applied to the set of retrieved warnings. If not specified, the all filter is used.
  • The available Visible Warnings filters can be viewed on the Warnings tab of the Saved Searches page.
  • If warning_filter contains spaces or other special characters, it must be double-quoted.
[--src-root /path/to/repo] When --sarif is specified, instructs the CodeSonar SARIF generator to express file paths with respect to /path/to/repo. This is primarily useful for integration with GitHub. This takes precedence over analysis option -srcroot and configuration parameter SRCROOT_PATHS.
When --sarif is not specified, specifying this flag will cause the command to fail with an error.
[--sarif-detail detail_level] When --sarif is specified, specified the level of detail to include in the SARIF output : one of {brief, default}.
  • --sarif-detail brief : produce SARIF output that omits the relatedLocations and codeFlows fields. This will generally be faster than the default setting.
  • --sarif-detail default: produce SARIF output that includes these fields.
  • Not specified: same behavior as --sarif-detail default.
When --sarif is not specified, specifying this flag will cause the command to fail with an error.
[-t max_seconds] Specifies the maximum time (in seconds) the request is allowed to take.
[--metrics-csv path/to/csv_outfile]
[--metrics-xml xml_outfile] 		In addition to retrieving warning information, write a file containing metric values for the 'current' analysis determined by the other arguments.
  • See --gained-since-previous-analysis for details of how the current analysis is determined.
  • If there is no current analysis, the command will fail with an error.
Behavior is as follows.
  • When --metrics-csv path/to/csv_outfile is specified, metric values are written in CSV format to file path/to/csv_outfile.
  • When --metrics-xml path/to/xml_outfile is specified, metric values are written in XML format to file path/to/xml_outfile.
    The XML schema for this file is metrics.xsd.
  • Both --metrics-csv and --metrics-xml can be specified.
    If you specify both, ensure that they each have a different output file path. If the output file paths are the same, the resulting file will contain XML output only.
  • All metric values computed for the analysis will be included in the output.
    In particular, the --search and --visible-warnings options have no effect on the set of metric values.
[-auth authtype],
[-hubuser username],
[-hubpwfile pwfile],
[-hubbearerfile bearerfile],
[-hubcert certfile],
[-hubkey privatekeyfile] 		Specify how CodeSonar should attempt to authenticate this command. For details, see Hub Authentication: Authenticated codesonar Subcommands.
If you are using codesonar dump_warnings.py in a script or a similar unattended context, it will probably be most convenient to use bearer authentication: specify -auth bearer -hubbearerfile bearerfile, where bearerfile contains a valid session bearer token.
[-o outfname] If specified, CodeSonar will write the retrieved warning information to outfname. Otherwise, the information is written to stdout.

Retrieved Columns

The retrieved columns are as follows.

Column Names

The available column names for --show-column and --sort are as follows.
These correspond to the available table columns for the Warning Search Results page.

When restricted to a single analysis Otherwise
  • categories
  • class
  • cluster
  • detected
  • directory
  • file
  • filePath
  • finding
  • fingerprint
  • firstDetected
  • id
  • language
  • lineContent
  • lineNumber
  • modified
  • notes
  • owner
  • priority
  • procedure
  • rank
  • score
  • significance
  • sourceFileName
  • sourceFilePath
  • sourceLineNumber
  • state
  • url
  • analysisDescription
  • analysisId
  • analysisName
  • categories
  • class
  • cluster
  • detected
  • directory
  • file
  • filePath
  • finding
  • fingerprint
  • firstDetected
  • id
  • language
  • lineContent
  • lineNumber
  • modified
  • notes
  • owner
  • priority
  • procedure
  • project
  • projectDescription
  • rank
  • score
  • significance
  • sourceFileName
  • sourceFilePath
  • sourceLineNumber
  • state
  • url

Note: the command is restricted to a single analysis if one of the following is specified: --analysis-id, --analysis-url, --project-file, --project-name.

Examples

Example 1

From the hub at [::1]:7340 (the default, since neither --hub nor --analysis-url is specified):

codesonar dump_warnings.py --analysis-id 46 \
--sort "descending:class" --sort "ascending:score" \
 --csv -o warnings-46.csv

For example, if the analysis with ID 46 is from the Basic Tutorial, warnings-46.csv will look something like the following.

score,id,project,class,significance,file,line number,procedure,priority,state,finding,owner,url
74,252.944,cs-BasicProj,Use After Free,Security,BasicProj.c,55,main,None,None,None,"",/warninginstance/944.txt
77,257.949,cs-BasicProj,Type Mismatch,Security,BasicProj.c,44,main,None,None,None,"",/warninginstance/949.txt
48,254.946,cs-BasicProj,Null Pointer Dereference,Reliability,BasicProj.c,25,main,None,None,None,"",/warninginstance/946.txt
49,255.947,cs-BasicProj,Null Pointer Dereference,Reliability,BasicProj.c,17,main,None,None,None,"",/warninginstance/947.txt
79,256.948,cs-BasicProj,Leak,Reliability,BasicProj.c,24,main,None,None,None,"",/warninginstance/948.txt
54,253.945,cs-BasicProj,Buffer Overrun,Security,BasicProj.c,38,main,None,None,None,"",/warninginstance/945.txt

Example 2

From the hub at localhost:7340:

codesonar dump_warnings.py --hub localhost:7340 \
--project-file /usr/alex/projects/basic/cs-BasicProj.prj \
--json -o warnings-basic.json

For example, if this is the project from the Basic Tutorial, warnings-basic.json will look something like the following.

{"rows":[
{"id":{"instanceId":10040,"groupId":2},"class":"Leak","file":"BasicProj.c","lineNumber":24},
{"id":{"instanceId":10036,"groupId":7},"class":"Use After Free","file":"BasicProj.c","lineNumber":55},
{"id":{"instanceId":10035,"groupId":5},"class":"Type Mismatch","file":"BasicProj.c","lineNumber":44},
{"id":{"instanceId":10037,"groupId":3},"class":"Buffer Overrun","file":"BasicProj.c","lineNumber":38},
{"id":{"instanceId":10039,"groupId":4},"class":"Null Pointer Dereference","file":"BasicProj.c","lineNumber":17},
{"id":{"instanceId":10038,"groupId":6},"class":"Null Pointer Dereference","file":"BasicProj.c","lineNumber":25}
]}

Example 3

From the hub at localhost:7340:

codesonar dump_warnings.py --analysis-url http://localhost:7340/analysis/46.html \
--search "class:null or class:free" --visible-warnings active \
--format "Warning %(id)s has class %(class)s and was issued at %(detected)s"

For example, if the specified URL corresponds to an analysis from the Basic Tutorial, the output will look something like the following.

Warning 7.10036 has class Use After Free and was issued at 2023-02-19T23:29:54.600469Z
Warning 4.10039 has class Null Pointer Dereference and was issued at 2023-02-19T23:29:54.600469Z
Warning 6.10038 has class Null Pointer Dereference and was issued at 2023-02-19T23:29:54.600469Z

Note. This page contains references to HTTP API documentation, which is served directly by the hub and cannot be accessed via a file:// URL. For active HTTP API documentation links, start a hub (if one is not already running), then open the manual from the hub.

 

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