Svace is an automatic defect detection tool for source code written in C, C++, Java, Go, Kotlin and C# languages. The detection algorithms are based on static analysis. This software is copyrighted by Ivannikov Institute for System Programming of the Russian Academy of Sciences (ISP RAS).

Svace is a continuously evolving product based on long term research. It uses a number of unique state-of-the-art analysis technologies and adopts the front-end of several open compilers to support the latest language standards. Svace provides ease of integration with any build systems and allows to accurately capture the exact code being built and the details of its compilation. Svace analysis engine covers all program execution paths and considers function calls in particular. The analysis is fully parallel and scalable up to projects with tens of millions lines of code. Several third-party analyzers are integrated into Svace to widen the scope of detected issues. Analysis results are represented through detailed reports, where the traces provided for each reported issue support code navigation.

Outline

This User Guide includes the following main sections:

• Introduction
• Dependencies and installation
• Using Svace (description of the main use cases)
• Command line tools (Svace command line tools reference)
  • svace init
  • svace build
  • svace config
  • svace warning
  • svace analyze
  • svace history
  • svace server
• Analysis with cache (analysis which share data between runs)
• Remote analysis
• Tutorial (tutorial for analysis performed using command-line interface)
• Warning types (Svace warning type reference)
  • Kinds of warning types
  • Null pointer dereference
  • Tainted input
  • Buffer overflow
  • Memory management
  • Infinite loop
  • Integer overflow
  • Security errors
  • Concurrency
  • Signal handlers
  • Library specific
  • C++ warning types
  • C# warning types
  • Go warning types
  • Other warning types
• Java analysis

Introduction

Typically, analyzing source code with Svace involves four stages:

• Compiling source code into intermediate representation files.
• Performing analysis of the code.
• Exporting the analysis results to a remote analysis history server or importing them to the local analysis history storage.
• Managing the history of previous analysis runs and evaluation status of previously detected issues (history storage).

Svace includes internal compilers to generate intermediate representation for analysis. For C/C++ Svace uses a modified version of Clang to produce the LLVM intermediate representation (bitcode) files. For Java, javac compiler from OpenJDK is used to produce bytecode. For C#, Roslyn is used.

The analysis tool uses the intermediate files and other data (including source code) produced and stored at the build phase to generate analysis result files (in various formats including plain text, XML and JSON).

History of previous analysis runs allows one to indicate (for a new run) which issues were new to this run and which issues detected on this run were previously marked as incorrectly detected (false positives).

Dependencies and installation

Svace is released in 3 separate distributions:

• Linux (x86_64, tested on Ubuntu from Trusty to Bionic).
• Windows (x86_64, the minimum supported version is Windows 7 SP1 with update KB2533623).
• macOS (x86_64, tested on Mojave and newer; svace build requires disabling System Integrity Protection).

The analyzer has no external dependencies and may be used right after unpacking.

Using Svace

This section describes how to perform analysis through command line interface, explaining the process of analysis in detail.

Initializing project folder

Svace stores all the data related to a project being analyzed in a special project folder. This folder can be created using a svace init tool.

Building source code

Svace provides the svace build tool to wrap a normal building command. This tool intercepts invocations of compilers supported by Svace (C/C++: GCC, ARMCC, Clang, icc, MSVC and multiple others; Java: OpenJDK, Oracle JDK and ECJ (including their usage via API)) and transparently runs Svace internal compilers along with the original compiler command.

Building in Tizen and Samsung Build System

Running the build command

For SBS make sure that sbs is in PATH. The following command should now work from a source package directory:

svace build sbs -b

Similar procedure is for building a Tizen package using GBS. For example, to build a libxml2 package:

svace build gbs build -A armv7l --binary-list libxml2

Performing analysis

Use svace analyze command line tool.

Secondary analysis engines

A Svace distribution can additionally include Clang Static Analyzer and SpotBugs. Also, several lightweight defect detectors are implemented in Svace javac compiler. By default, all those tools are run before the main analysis, using intermediate data produced during the build phase as input. Defect reports produced by those tools are included into the final analysis results.

Performance tuning

Svace supports configuration options that may affect the analysis behaviour. Default option values are suitable for most scenarios, but it is possible to tune specific parameters. Changing their values is done by the svace config tool:

svace config THREAD_NUMBER 4

In the example above the THREAD_NUMBER configuration option, that controls the number of parallel threads used for analysis, is set to 4. By default, the THREAD_NUMBER option has value max that allows analyzer to use as many threads as the number of processor cores. Other possible values are positive numbers to set specific analysis threads number and auto to select threads number depending on current processor load.

In most cases analysis is the fastest when THREAD_NUMBER is max. At the same time each thread uses additional memory so more threads will use more memory and when the amount of RAM is limited it is better to decrease this option value.

Working with history storage

When the svace history tool is used after an analysis, analysis results are added to history storage. History storage for a project is located in its Svace directory. A history storage contains the list of known warnings found in the project, and snapshots of the relevant source code.

History storage allows to recognize some issues detected on a new analysis run as instances of previously detected issues (even if the source code and line numbers changed between the analyses). If an issue was marked as a ‘false positive’ after some analysis run, it will remain marked so in new analysis results.

Viewing the results

Analysis results may be viewed through a web-browser using a builtin server (see svace server) or a standalone Svacer history server, or opened with an editor.

Each issue detected by Svace is associated with the following information:

• Warning type
• Source location, warning message, warning trace
• Evaluation status (Not inspected, True, Technically true, False or Unknown)

The analysis results are presented as a tree. The top level lists warnings by type, the second level lists the warnings themselves.

Each warning record shows location in the source code and warning message that may include names of the relevant expressions. For each warning, subnodes in the tree may indicate multiple source locations playing different roles in the warning (for example, for DEREF_AFTER_NULL, one location shows where the pointer is dereferenced, and the other location shows where it was compared to NULL). Together they form a warning trace that usually helps to understand the program flow from the defect occurrence to its manifestation point, or other useful information related to the warning.

When using a web-server warning status can be set by selecting appropriate value from the drop-down list, and is indicated by the color of the issue. There are the following options:

• Not inspected — a default state for issues that weren’t inspected yet.
• True — a correctly detected issue, that offers useful guidance about what should be changed in the source code.
• Technically true — a correctly detected issue, that should probably be left unchanged in the source code for some reason (e.g. given the assumptions specific to the analyzed source code, the detected issue isn’t expected to cause problems).
• False — an incorrectly detected issue.
• Unknown — an issue that was inspected, but it was too difficult to understand whether it’s a correctly detected issue.

Command line tools

The command line tools can be accessed through a wrapper tool svace located in svace/bin/ (it’s recommended to add this directory to PATH, so that svace becomes accessible as a command). Command line options for svace are as follows:

usage: svace <command> [args]
       svace --version [--quiet | --verbose]
       svace [--help]

This is the command-line interface for Svace static analysis tool.
Type 'svace help <command>' to get help on a specific command.

optional arguments:
  --help                Show this help message and exit.
  -V, --version         Show version information and exit. If used together
                        with '--quiet', only version number in X.Y.Z format is
                        printed. If used together with '--verbose', source
                        code revision is printed too.
  -v, --verbose         Increase output verbosity.
  -q, --quiet           Reduce output verbosity.

commands:
  main:
    analyze             Run Svace static analyzer to search for defects in
                        source code, given the data gathered during 'svace
                        build'.
    build               Capture invocations of supported compilers performed
                        by a given command and generate intermediate data for
                        a subsequent analysis.
    config              Manage general configuration settings.
    init                Create a Svace project directory.
    warning             Control which warning types are enabled during
                        analysis.
  
  experimental:
    admin               Manage object pool in a project directory.
    clean               Remove old annotations.
    context-spec        Manage context in which particular function will be
                        analyzed.
    export-build        Export a build object into an external directory.
    history             Interact with a warning database.
    merge-build         Merge multiple build objects into a single build
                        object.
    nhistory            Interact with a new warning database.
    server              Configure or run Svace server.
    show                Show results in a Svace server (localhost:8060).
    spec                Manage user-provided specifications for third-party
                        library functions.
  
  miscellaneous:
    compare-details     Compare details for 2 svres files.
    compare-svres       Compare warnings from two .svres files ignoring
                        checker names and generate comparison stats.
    convert-svres       Convert analysis results files into newer or older
                        format versions.
    csa-stat            Display Clang Static Analyzer checker statistics
                        summary.
    diff-svres          Show diff for 2 svres files.
    filter-svres        Extract the issues enabled in given warning settings
                        file from a given .svres.
    ignore-test         Check svace.ignore filter.
    import-sqlite       Convert svace sqlite format db to svres.
    match-svres         Match two svres files and show identifiers of the
                        matched warnings from the first svres file.
    merge-svres         Merge multiple .svres files with analysis results for
                        different projects into a single file.
    mti                 Calculate message template id from warning messages
                        taken from svres files.
    mti-csharp          Calculate message template id from warning messages
                        taken from svres files.
    quality-report      Print report about warnings quality for reviewed svres
                        files(s).
    review-rebase       Rebase warning review from one svres file to other.
    split-svres         Split a multi-project .svres file into separate files
                        with analysis results for individual projects.
    suppress            Run stand-alone suppression tool.
    svres2json          Converter from Svace results format to JSON format and
                        vice versa.
    svres2sarif         Converter from Svace results format to Sarif 2.1
                        format.
    warning-selector    Pick particular warnings and write them to an svres
                        file.
  
  for debug and development:
    cgoc                Tool to compare call graph logs.
    cgop                Tool to calculate sub-call graph order.

svace init

usage: svace init [options] [DIR]

Create an empty Svace project directory or reinitialize an existing one. By
default, this command creates a '.svace-dir' subdirectory in DIR (but see
--bare). If DIR is not specified, the value of SVACE_DIR environment variable
(or, if unset, the current directory) is used instead. If the project
directory already exists, this command can reinitialize its permissions
according to the options without changing the stored data. Note that only
permissions of the directory itself can be changed. Permissions of
subdirectories should be changed manually if desired.

optional arguments:
  --bare       Initialize the specified directory as a Svace project directory
               instead of creating '.svace-dir' subdirectory in it.
  --shared     Make the project directory group-writable and set the set-
               group-id bit on it if needed. This allows users belonging to
               the current user's primary group to share this project
               directory.
  -q, --quiet  Print only error messages (to stderr).
  --help       Show this help message and exit.

svace build

This tool launches a specified custom build command, intercepts invocations of supported compilers and uses Svace internal compilers to produce intermediate representation of the same source code that is being built by the given command.

Command line options are as follows:

usage: svace build [options] <build-command>

Run <build-command> and capture all invocations of supported compilers during
its execution. Create intermediate representation files using information from
the intercepted compiler invocations.

<build-command> can include options and arguments. To capture multiple
commands, wrap the commands in a single script.

Typical usage:
 svace build make -j4 all

 svace build gradle --no-daemon build

positional arguments:
  build-command

optional arguments:
  -h, --help            show this help message and exit
  --svace-dir SVACE_DIR
                        Specify a Svace directory, overriding current
                        directory and SVACE_DIR environment variable.
  --init                Initialize the selected Svace project directory before
                        doing anything else. This is a shortcut for avoiding
                        manual 'svace init' if all you need is its default
                        behavior.
  --clear-build-dir     Remove redundant contents of the build directory after
                        build.
  --enable-language LANG, --disable-language LANG
                        Enable or disable compilation interception for the
                        specified programming language. Supported languages
                        are: all, cxx, go, kotlin. By default, all supported
                        languages are enabled.
  -L LANGS, --languages LANGS
                        Enable compilation interception for languages in the
                        specified comma-separated list and disable it for
                        other languages. The special value 'all' enables all
                        supported languages (which is the default).
  --debug               Enable verbose logging useful for debugging and making
                        bug reports.
  --enable-spotbugs, --disable-spotbugs
                        Run SpotBugs checkers for intercepted Java
                        compilations during the build phase. By default, this
                        feature is disabled.
  --disable-java-agent  Don't inject Java agent into intercepted JVM
                        processes. If this option is used, compilations
                        performed via compiler APIs (e.g., javac API) are not
                        intercepted. Since Svace Java agent requires Java 7 or
                        newer and causes build failure if it's injected into
                        an older JVM, this option can be useful if build
                        process involves older Java and compiler API
                        interception is not needed.
  --spotbugs-memory SPOTBUGS_MEMORY
                        Specify maximum size of Java heap (in MB) that
                        SpotBugs may use (default: 2048).
  --kotlinc-memory KOTLINC_MEMORY
                        Specify maximum size of Java heap (in MB) that Kotlin
                        compiler may use (default: 2048).
  --captured-nothing-status STATUS
                        If the build command completed successfully and no
                        serious Svace failures were detected, but no
                        compilations were successfully captured, exit with the
                        specified status (255 by default).
  --low-ready-units-ratio PERCENTAGE
                        If the ratio of ready units to all units (as shown
                        with --verbose) is less than the specified integer
                        percentage for any programming language with at least
                        one intercepted compilation, print a warning and exit
                        with the status specified with --low-ready-units-
                        status option (but still generate all data necessary
                        for analysis). This option doesn't apply if no units
                        were captured at all (see --captured-nothing-status).
                        The default value is 0 (i.e. no capture ratio is
                        considered low).
  --low-ready-units-status STATUS
                        Set the exit status for --low-ready-units-ratio option
                        (254 by default).
  -v, --verbose         Report more detailed statistics after build.

experimental options:
  -t TARGET, --target TARGET
                        Specify the target platform that Clang should use for
                        bitcode generation. Valid values are: auto, aarch64,
                        arm, hexagon, mips, mips64, powerpc, powerpc64,
                        riscv32, riscv64, sparc, sparc64, x64, x86. Values
                        other than 'auto' override automatic target detection.
                        This option is intended for debugging only.
  --enable-ptrace       Use ptrace-based interception for statically-linked
                        executables. By default, Svace uses LD_PRELOAD-based
                        interception, which works only for dynamically linked
                        executables. But sometimes compiler toolchains are
                        statically linked, or there are other statically
                        linked processes that break LD_PRELOAD-based
                        interception (for example, by removing LD_PRELOAD
                        environment variable). This option enables a hybrid
                        mode: Svace will start in LD_PRELOAD mode, but will
                        switch to ptrace-based mode each time it detects a
                        launch of a statically linked executable, and will
                        switch back if that executable runs a dynamically
                        linked executable.
  --enable-ptrace-all   Use ptrace-based interception for all executables and
                        disable LD_PRELOAD-based interception. See --enable-
                        ptrace for more details.
  --prepend-preload-lib
                        By default, the Svace library for function call
                        interception is appended to LD_PRELOAD environment
                        variable, ensuring that necessary environment
                        variables are propagated across the process tree even
                        if other LD_PRELOAD-libraries are used in the course
                        of the build process. However, if such libraries
                        modify arguments of created processes in a way that
                        makes them unrecognizable to the Svace code that
                        detects "interesting" processes, the Svace library
                        should be prepended instead, ensuring that it sees the
                        same arguments that were passed by the application. In
                        particular, this is needed for Scratchbox environment.
  --disable-comp        Disable all compiler addons
  --disable-misc        Disable all non-compiler addons
  --clang-opts CLANG_OPTS
                        Add specified options to the Clang and Clang Static
                        Analyzer run by Svace. The options should be separated
                        by ';'.
  --spotbugs-opts SPOTBUGS_OPTS
                        Add specified options to the SpotBugs run by Svace.
                        The options should be separated by ';'.
  --hash-ar-content     Calculate archive hash based only on names of files in
                        the archive, excluding timestamp, UID, GID and
                        content. Use in case of undeterministic mode of ar or
                        ranlib and in case of prebuilt archives with prebuilt
                        object files (that may differ because of another
                        platform etc.). DO NOT USE in case of rebuilding the
                        same archive more than once in the same build (e.g.
                        debug and release mode).
  --enable-huge-source-workaround
                        Clang can't handle translation units larger than 2 GB
                        after preprocessing because it uses signed 32-bit
                        integer type internally for identifying source
                        locations. Sometimes such huge TUs occur in practice
                        because the same autogenerated header file is included
                        multiple times without guards. In this case source
                        locations are allocated for each inclusion, which may
                        cause an overflow resulting in a hang or crash. This
                        option makes it so source locations are allocated only
                        once per header file, which may help avoid the
                        overflow in this case. This option is incompatible
                        with '--enable-csa-deps'.
  --chroot-interception-failure-mode {fail,warn,ignore}
                        Specify how to react if Svace fails to set up
                        interception upon encountering a transition into a
                        chroot jail. If set to 'fail', terminate the affected
                        process immediately and report a fatal error.
                        Otherwise, disable interception for the affected
                        process and its descendants and, if set to 'warn',
                        also report a warning when 'svace build' completes.
                        This may be useful in cases when chroot() is used for
                        purposes other than running compilations in a chroot
                        jail, making interception failure irrelevant. The
                        default value is 'fail'.

deprecated options (may be removed in a future release):
  --clear-bitcode-dir   An alias for --clear-build-dir.

Environment variables:
  SVACE_DIR             Overrides the default value for --svace-dir
  SVACE_ENABLE_CSA_STAT
                        Overrides the default value for --enable-csa-stat.
                        Must be set to 'yes' or 'no'.

svace config

Usage: svace config [OPTIONS] [<key> [<value>]]
       svace config [OPTIONS] --unset <key>

Manage configuration settings. In the first variant (without --unset), if 
only <key> is specified, get current value assigned to that key (--parents 
must be specified to take system-wide and user-specific configuration into 
account). If both <key> and <value> are specified, set <key> to <value>. For 
boolean keys, possible values are 'true' and 'false'. Some keys that control 
internal (development) settings are 'hidden' and don't show by default, but 
can be listed with --show-hidden.

Common config options (shared by 'warning' and 'config' tools):
  --global           : Work with user-specific configuration
                       ~/.svace/<config-file>, rather than the local
                       configuration $SVACE_DIR/<config-file>
  --system           : Work with system-wide configuration
                       /path/to/distro/config/<config-file>, rather than the
                       local configuration $SVACE_DIR/<config-file>
  -f, --file FILE    : Use specified config file instead of the one implied by
                       options --global, --system, or current svace dir.
                       If FILE is '-', read from stdin and write to stdout
                       (implies --quiet).
  --unset            : Remove the entry for specified key from config file (so
                       that the default value or value specified in parent
                       config files will be used instead).
  --unset-all        : Clear the config file.
  -l, --list         : List the entries specified in config file(s).
  -a, --all          : List entries for all keys, including those not specified
                       in config files. Don't list hidden keys, unless 
                       --show-hidden is specified. Implies --parents.
  --show-hidden      : When listing keys with --all or --list, show hidden keys
                       as well.
  -i, --info         : For each listed key, print a short description.
  -p, --parents      : When reading from config file, take into account the
                       settings specified in parent files. By default, apply
                       system-wide, user-specific and then Svace directory
                       or explicitly specified settings to form the list of
                       modified settings and their values.
                       If --global is specified, apply only system-wide and
                       user-specific settings; if --system is specified,
                       apply only system-wide settings.
  --svace-dir PATH   : Specify a Svace directory, overriding current directory
                       and $SVACE_DIR environment variable.
  -q, --quiet        : Only print error messages (to stderr) and specifically
                       requested output (to stdout).
  --get-val          : Only print the value of specified key (without 'key = ').

svace warning

Usage: svace warning [OPTIONS] [<warn-type> [<state>]]
       svace warning [OPTIONS] --unset <warn-type>

Manage warning settings (which warning types are enabled/disabled). In the
first variant (without --unset), if only <warn-type> (key) is specified, get
current state (value) of that warning type (--parents must be specified to
take system-wide and user-specific configuration into account). If both
<warn-type> and <state> are specified, set <warn-type> to <state>. Possible
values for <state> are 'true', 'false' and 'hidden' (disables a warning type
and hides it from output of '--all').

Special warning name 'all' can be used to enable/disable all warning types
at once, except for warning types hidden by default.
Use special warning name 'hidden' to enable/disable warning types hidden by
default.

Common config options (shared by 'warning' and 'config' tools):
  --global           : Work with user-specific configuration
                       ~/.svace/<config-file>, rather than the local
                       configuration $SVACE_DIR/<config-file>
  --system           : Work with system-wide configuration
                       /path/to/distro/config/<config-file>, rather than the
                       local configuration $SVACE_DIR/<config-file>
  -f, --file FILE    : Use specified config file instead of the one implied by
                       options --global, --system, or current svace dir.
                       If FILE is '-', read from stdin and write to stdout
                       (implies --quiet).
  --unset            : Remove the entry for specified key from config file (so
                       that the default value or value specified in parent
                       config files will be used instead).
  --unset-all        : Clear the config file.
  -l, --list         : List the entries specified in config file(s).
  -a, --all          : List entries for all keys, including those not specified
                       in config files. Don't list hidden keys, unless 
                       --show-hidden is specified. Implies --parents.
  --show-hidden      : When listing keys with --all or --list, show hidden keys
                       as well.
  -i, --info         : For each listed key, print a short description.
  -p, --parents      : When reading from config file, take into account the
                       settings specified in parent files. By default, apply
                       system-wide, user-specific and then Svace directory
                       or explicitly specified settings to form the list of
                       modified settings and their values.
                       If --global is specified, apply only system-wide and
                       user-specific settings; if --system is specified,
                       apply only system-wide settings.
  --svace-dir PATH   : Specify a Svace directory, overriding current directory
                       and $SVACE_DIR environment variable.
  -q, --quiet        : Only print error messages (to stderr) and specifically
                       requested output (to stdout).
  --get-val          : Only print the value of specified key (without 'key = ').

Warning tool specific options:
  --preset NAME      : Work with specific preset of options

Warning type properties (displayed when option --info is given;
see User Guide for more details):
  Situation  : What kind of situation is indicated by the issue.
               Possible values:
                 Quality
                 Security
                 CodingStyle
                 Suppressed
                 Duplicate
                 Performance
                 Portability
  Severity   : Potential danger represented by the issue, if it's correctly
               detected. Possible values:
                 Critical
                 Major
                 Normal
                 Minor
                 Undefined
  Reliability: How often the issues of this type are detected correctly
               (in different projects). Possible values:
                 VeryHigh
                 High
                 Average
                 Low
                 VeryLow
                 Unknown
  Language   : For which languages warnings of this type are detected.
               Possible values:
                 CXX
                 JAVA
                 KOTLIN
                 CSHARP
                 GO
                 NONE
  Detection tools: Where the checker for the issue is implemented.
               Possible values:
                 SvEng
                 SvaceCppSpecific
                 CSA
                 SpotBugs
                 Goa
                 TagsJavac
                 Roslyn
                 Kotlinc
  Group      : A group which this warning type belongs to.

Examples:
# Get the state of warning type DEREF_AFTER_NULL, taking parent configuration
# into account:
    svace warning -p DEREF_AFTER_NULL

# Disable DEREF_AFTER_NULL for all analysis invocations by current user:
    svace warning --global DEREF_AFTER_NULL false

# Disable DEREF_AFTER_NULL for java language:
    svace warning JAVA.DEREF_AFTER_NULL false

# Disable all warning for language CSHARP:
    svace warning CSHARP false

# Disable autofixes for all warnings (but do not change warnings themselfs):
    svace warning AUTOFIX false

# List all critical warnings:
    svace warning CRITICAL

# List all warnings with autofixes:
    svace warning AUTOFIX

# List all warnings of buffer overflow group:
    svace warning TAINTED_SECTION
 or 
    svace warning TAINTED

# List all warnings by wildcard (only * is allowed):
    svace warning DEREF_*_NULL*

# List several categories:
    svace warning DEREF_OF_NULL,DEREF_AFTER_NULL

# Intersect several categories:
    svace warning --and CRITICAL,JAVA

# List all warning settings specified for current user, including a short
# description for each warning type:
    svace warning -lpi --global

# Dump all information about the configuration that would be used during
# analysis:
    svace warning -lap --show-hidden

svace analyze

This is the main analysis tool. It takes as input the data produced by svace build and generates analysis result files. Command line options are as follows:

usage: svace analyze [options]

Analyze the selected project directory with Svace.
By default, a project directory based on the current working directory 
is selected, and analysis is performed for the last build object produced by
'svace build', which is specified in file <project-dir>/bitcode/build-object.
Use '--svace-dir' to specify a different project directory and '--build'
to specify a different build object.

optional arguments:
  -h, --help            show this help message and exit
  --svace-dir DIR       Specify a Svace directory, overriding current
                        directory and SVACE_DIR environment variable.
  -b HASH, --build HASH
                        A build object to be analyzed. By default, the last
                        build object produced by 'svace build' is used.
  -n NAME, --name NAME  Associate given name with the analyzed project (used
                        for naming files with results and some other files).
                        By default, the name of the project directory is used.
  --memory NUM_MB       Specify maximum amount of RAM (in MB) that Svace may
                        use for analysis. More precisely, this option controls
                        the maximum size of JVM heap. If set to 'auto' (the
                        default), Svace attempts to detect the maximum usable
                        JVM heap size at the time of analysis start and uses
                        the value close to the detected maximum.
  --enable-language LANG, --disable-language LANG
                        Enable or disable analysis for the specified
                        programming language. Supported languages are: all,
                        cxx, go, kotlin. Enabling a language also enables
                        working with the relevant tools (e.g., enabling C/C++
                        turns on analysis with Clang Static Analyzer). Default
                        values set by this option are overridden by
                        --import-<tool>, --skip-import-<tool> and
                        --skip-<lang_or_tool>-analysis options. By default,
                        analysis of all supported languages is enabled.
  -L LANGS, --languages LANGS
                        Enable analysis for languages in the specified comma-
                        separated list and disable it for other languages. The
                        special value 'all' enables all supported languages
                        (which is the default).
  --target TARGET       Select the target architecture of C/C++ code to
                        analyze. If it's set to 'all' (the default), each
                        target is analyzed in turn independently of other
                        targets. Valid values are: all, aarch64, arm, hexagon,
                        mips, mips64, powerpc, powerpc64, riscv32, riscv64,
                        sparc, sparc64, x64, x86.
  --preset NAME         Use the requested warnings preset during the analysis.
  --import-csa, --skip-import-csa
                        Import Clang Static Analyzer results generated at the
                        build phase. Has no effect if CSA is run at the
                        analysis phase (see --skip-csa-analysis).
  --import-spotbugs, --skip-import-spotbugs
                        Import analysis results of SpotBugs generated at the
                        build phase. Has no effect if SpotBugs is run at the
                        analysis phase (see --skip-spotbugs-analysis).
  --import-kotlinc, --skip-import-kotlinc
                        Import analysis results of Kotlin compiler generated
                        at the build phase. Has no effect if kotlinc is run at
                        the analysis phase (see --skip-kotlinc-analysis (not
                        implemented yet)).
  --import-goa, --skip-import-goa
                        Import analysis results of Goa generated at the build
                        phase. Has no effect if Goa is run at the analysis
                        phase (see --run-goa-analysis).
  --skip-c-analysis     Don't analyze C/C++ code with Svace engine. Note that
                        Clang Static Analyzer is not affected by this option.
  --skip-sveng-analysis
                        Don't run Svace engine analysis.
  --skip-csa-analysis   Don't analyze C/C++ code with Clang Static Analyzer.
                        You may still see CSA results if it was enabled at the
                        build phase and its results were imported.
  --skip-spotbugs-analysis
                        Don't analyze Java code with SpotBugs. You may still
                        see SpotBugs results if it was enabled at the build
                        phase and its results were imported.
  --run-goa-analysis    Analyze Golang code with Goa.
  --csa-opts OPTS       Add specified options to the Clang Static Analyzer run
                        by Svace. The options should be separated by
                        semicolons (';'). To specify a literal semicolon,
                        prepend a backslash ('\') to it. To specify a sequence
                        of literal backslashes before a literal semicolon,
                        repeat each of the literal backslashes twice.
  --set-config KEY=VALUE
                        Set the value of config option KEY to VALUE for this
                        analysis run only. Takes precedence over config files.
  --set-warn WARN=(true|false)
                        Enable or disable warning type WARN for this analysis
                        run only. Takes precedence over config files.
  -w FILE, --warnings FILE
                        Load warning settings (information about
                        enabled/disabled warning types) from FILE instead of
                        warn-settings.txt from Svace project directory. Note
                        that defaults from system and global settings are
                        still applied as usual.
  -q, --quiet           Show error messages only.
  -v, --verbose         Show detailed information about analysis and its
                        status.
  --log-level LOG_LEVEL
                        Log level. May have values: quiet, brief, default and
                        verbose.
  --version             Show Svace engine version information and exit. If
                        used together with '--quiet', only version number in
                        X.Y.Z format is printed. The Svace engine version is
                        normally the same as the version of the Svace
                        distribution as shown by 'svace --version'.

experimental options:
  -t HASH, --task HASH  A task object to be analyzed.
  --raw-files           Analyze files with intermediate representation in the
                        build directory ($SVACE_DIR/bitcode by default)
                        instead of analyzing a build object. This option may
                        be useful for debugging, but normally shouldn't be
                        used.
  --with-cache          Use cache for analysis intermediate results. Enabling
                        cache may increased analysis speed of modified
                        project. Require additional disk space.
  --analyze-storage-dir SVACE_ANALYZE_STORAGE_DIR
                        Specify a folder for storing analysis data that are
                        shared between analysis. Analysis with cache, fast
                        analysis and incremental analyses use this folder. By
                        default analysis uses folder $SVACE_DIR/analyze-
                        storage.
  --build-dir DIR       Specify a build directory produced by 'svace build' to
                        use for analysis. The default is $SVACE_DIR/bitcode.
                        Valid only together with --raw-files.
  -s DIR, --source DIR  Search for source code in DIR. Project directory is
                        used by default (as specified, even if the actual
                        Svace directory is its subdirectory .svace-dir). Valid
                        only together with --raw-files.
  -o DIR, --output DIR  Save analysis results in DIR. By default, the results
                        are saved in $SVACE_DIR/analyze-res. The analysis
                        result files are $PRJ_NAME.svres and $PRJ_NAME.txt,
                        where $PRJ_NAME is the name of the analyzed project.
                        Valid only together with --raw-files.
  --fix                 Run autofix during analysis.
  --autofix-backend {svace}
                        Autofix backend to use. The default is 'svace'.
  --emit-autofix-input  Emit autofix input as a separate file (for debug
                        purposes).

svace history

svace history list   [--svace-dir <project-dir>] [--branch <branch>]
                     [--class <warning type>] [--status <warning status>]
svace history update [--svace-dir <project-dir>] [--branch <branch>]
                      --warning <warning ID> [--user <user name>]
                     [-status <warning status>] [--comment <comment>]
svace history import [--svace-dir <project-dir>] [--branch <branch>]
                     (--task <task ID> | --build <build ID>)
                      --results <results ID> [--name <snapshot name>]
                     [--user <user name>]
svace history branch (list |
                      clone --target <branch name> [--source <branch name>] |
                      delete --branch <branch name> [--force] |
                      sync <branch name> <branch name>)
                     [--svace-dir <project-dir>] [--branch <branch>]
svace history merge-svres svres-id...
svace history split-build build-id

Interact with a warning database. Allows to import new analysis results,
list analysis results and modify warning states from the command line.

Common options:
  --svace-dir PATH  : Svace project directory to work with.
                      If not set, current working directory will be used.
  --branch NAME     : History branch to work with.
                      If not set, default ('master') branch will be used.

Operations and their options:
  list          : Show list of actual warnings in a history branch.
                  These warnings can be filtered.
    --class NAME    : Display only warnings of selected class.
                      Can be used several times, showing multiple warning
                      classes. If not set, all warnings are shown.
    --status STATUS : Display only warnings having selected status.
                      Can be used several times, showing warnings of
                      multiple statuses. If not set, all warnings are shown.
    --format FORMAT : Format output for each warning according to
                      a format string. Supported format specifiers:
                      %h: Warning ID (hash)
                      %c: Warning class
                      %s: Warning status
                      %m: Warning message
                      %l: Warning location
                      %u: User comment
                      %A: User-defined attributes
    --current-snapshot VAL  : If VAL is false, display only warnings that
                      didn't appear on the current (last) snapshot
                      (but were detected on one of the old snapshots).
                      If it's true, display only warnings detected on the
                      current snapshot (this is the default).
    --previous-snapshot VAL : If VAL is false, display only warnings that
                      didn't appear on the previous snapshot
                      (but were detected either on one of the old snapshots,
                      or on the current snapshot).
                      If it's true, display only warnings detected on the
                      previous snapshot.

  update        : Modify a warning in the history storage.
    --user NAME     : Username related to this warning modification.
                      If not set, current user name will be used.
    --warning ID    : The 32-symbol ID for warning which must be updated.
    --status STATUS : New status for the selected warning.
                      May be one of 'bug', 'scope', 'goal', 'unclear' or
                      'default' (case-insensitive).
                      Other statuses are interpreted as 'default'.
    --comment STRING    : New comment string for the selected warning.

  import        : Import analysis results into history storage.
                  When neither build/task nor results object are specified,
                  import the last analysis results.
    --user NAME     : Username related to this warning modification.
                      If not set, current user name will be used.
    --results ID    : The 32-symbol ID for the imported analysis results.
    --build ID      : The 32-symbol ID for the build which was analyzed
                      to produce imported analysis results.
    --task ID       : The 32-symbol ID for the task which was analyzed
                      to produce imported analysis results.
    --name NAME     : Snapshot name related to these analysis results.

  import-data       : Internal tool mostly for debugging.
                      Allows to import analysis results and source code snapshots,
                      into svace storage system.
    --type      : 'svres', 'build', 'source-build' or 'empty-build'.
                  'svres' allows you to import analysis results in svres format,
                  'empty-build' produces build-object with no data in it,
                  'build' imports build object previously exported using
                  Svace 'export-build' command, 'source-build' allows you to import
                  some directory as a source code snapshot. The resulting build-object
                  will obviously contain no bitcode, so it won't be analyzable;
                  however it can be useful for importing data into history system.
    --path      : path to file (if importing 'svres') or directory (if importing
                  a source code snapshot or build object) you want to import.
    --orig-path     : used for 'source-build' only, and is optional. Indicates
                      the path where the imported source tree should be available at.
                      E.g.: you have file /home/user/project/file.c, you use:
                      --path /home/user/project/, --orig-path /var/build
                      the file will be imported and used by history system
                      like it was located at /var/build/file.c
                      If you are under *nix OS and you want to emulate build-object
                      generated by windows system, change orig-path this way:
                      'C:\Some\Dir\' => '/c_/Some/Dir/', and also check next flag.
    --with-dxr      : used for 'source-build' only, and is optional. Allows to provide
                      a directory with source code markup in csv format. Svace requires
                      file names in the same format svace generates dxr files itself. Also
                      Svace requires empty .csv.stamp files along with .csv data files.
    --merge-metrics : used for 'build' only, and is optional. If set to 'true' merges
                          imported build object metrics with the current ones.
    --move      : used for 'build' only, and is optional. If set to 'true' moves
                  imported files instead of copying them. This allows to speed up
                  the import but the export folder will be cleared after this.

  branch        : Manage branches. Must be followed by one of
                  the following sub-commands:
    list        : List all branches in the project directory
                  (including remote branches).
    clone       : Create a new branch and optionally makes its state
                  equal to another branch.
      --target NAME : Branch name to be created.
      --source NAME : Branch to be cloned.
                      If not set, created branch will have no content.
    delete      : Delete specified branch.
      --branch NAME : Name of the branch to be deleted.
      force     : Allows to delete 'master' branch.
                      (svace history branch delete force --branch master)
    sync NAME NAME  : Sync warning states from two given branches.

  merge-svres       : Takes multiple analysis results and merges them all
                  in one large analysis results.
  split-build       : Takes build object and splits it into multiple build objects
                  where each resulting build object has only some target-related data.

Examples:
# List warnings of class MEMORY_LEAK with Goal and Default statuses:
    svace history list --class MEMORY_LEAK --status Default --status Goal

# List warnings of class MEMORY_LEAK that disappeared on the last snapshot:
    svace history list --class MEMORY_LEAK --current-snapshot false \
                       --previous-snapshot true

# Change status of a selected warning:
    svace history update --user developer1 --warning 123..132 --status Bug \
                         --comment 'Array index isn't checked before access'

# Import existing analysis results into history database:
    svace history import --user developer1 --build 123..231 --results 323..321'

# Clone existing branch into a new one:
    svace history branch clone --source master --target backports_2.0

svace server

usage: svace server [--server-dir DIR] <subcommand> [args]

optional arguments:
  --server-dir DIR  Specify a Svace server directory. By default, the current
                    directory is used.
  --help            Show this help message and exit.

subcommands:
  subcommand
    init            Create a Svace server directory.
    start           Start the history access server.
    single-start    Start the history access server in single-project mode.
    admin           Manage a Svace server.
    show-api-docs   Display documentation for Svace history API.

Analysis with cache

Svace analysis has special mode which allow to reuse analysis results from previous run. It is intended for cases where project is regular analyzed by Svace.

How to use

Build program

svace init
svace build make

Analyze program with special parameter --use-cache. Svace will store results of intermediate operation to analysis cache.

svace analyze --use-cache

Then program may be changed. Program should be rebuilt and analyzed:

make clean
svace build make
svace analyze --use-cache

Svace will used stored results from previous analysis run. If Svace already has results for intermediate operations than it will be used them. Analysis time should be increased.

Notes

Parameter --use-cache must be used every time. If it will be omitted than results from cache won’t be used.

Svace stores results to folder .svace-dir/analyze-storage. Analysis stores all results not only results from previous run. Such mode may be efficiently used for different projects branches. All result will be in cache.

For using analysis cache project must be build in the same folder.

Time increasing depends on project and changes. We expect that second analysis is in average 10 times faster. Storing results to cache may slightly decrease analysis time compared with regular analysis.

Cache may require sufficient disk space. In average, it is comparable with the size of svace folder after build. After every analysis the cache size grows.

Changing default folder

Folder .svace-dir/analyze-storage where cache is placed may be changed by analysis parameter --analyze-storage-dir. For example:

svace analyze --with-cache --analyze-storage-dir CACHE_DIR

The parameter change storage directory not only for analysis with cache but also for fast analysis.

How it is implemented

We have operations which takes some times. It has input data and output data. Output data are fully defined by input data. Operation is fully independent of other parts of analyzer.

For input data we may quickly calculate hash. Output data are relatively small and may be serialized to disk.

Analysis “does not know” that it is run in special mode. All functions are performed the same way as with regular analysis except of dedicated operations. For such operation Svace creates hash for input data. Then Svace checks cache with for hash. If cache is not empty, then operation is skipped and output data are loaded from cache. If cache is empty then operations is performed and output data are stored to cache.

Described scheme is very simple and reliable.

What cases are supported

CSA analysis. It does not have inter module analysis and that’s why every module are analyzed independently. We recommend to use cache for this analysis.

Tags-javac analysis. It is also does not have inter module analysis. It is based on compilation unit (run of javac). We recommend to use it if build script run many compilation units. If only one compilation unit is used then cache will be obsolete after each source file modification.

Spotbugs analysis. It has similar limitation as Tags-javac analysis. We recommend to use it if build script run many compilation units.

Module parsing. Here input is a module (llvm bitcode file, Java/Kotlin bytecode file). Output is a set of loaded functions. The mode allows to skip module parsing. Moreover, Svace uses module parsing twice inside every analysis: for preliminary phase and for main phase. In some cases uses of such parsing may increase even first analysis because modules will be parsed only on preliminary phase. It has drawback — required disk size. Output data here is all procedures of projects. In some cases it may be bigger than whole svace directory. We recommend to use it if large disk are used.

Function analysis in main phase. It is more complicated analysis which depends on many data: function code, call graph, summaries of called functions, results of preliminary phase. If some function is changed then all functions that are above at call graph must be reanalyzed. Svace analysis spends most time for function analysis. Enabling cache for function analysis may significantly increase analysis time. This analysis depends on preliminary phase. But now we do not have way to define that preliminary phase may change function analysis. We recommend to use it if some changes with regular analysis are acceptable.

Customization

There are two ways to enable analysis with cache. First way is to use option PERSISTENT_MODE:

svace config PERSISTENT_MODE true

After setting this option all further analysis will be done with cache until this option will be disabled.

Second way is to use parameter –use-cache:

svace analyze --use-cache

This parameter temporary enable option PERSISTENT_MODE inside svace analyzer. Never configurations file will be changed. This option should be used every time when analysis is run. It is possible to enable/disable particular analysis by follow options:

• PERSISTENT_MODE.CSA — for CSA analysis
• PERSISTENT_MODE.TAGS_JAVAC — for tags-javac analysis
• PERSISTENT_MODE.SPOTBUGS — for spotbugs analysis
• PERSISTENT_MODE.MODULE_PARSING — for parsing module.
• PERSISTENT_MODE.FUNC_ANALYSIS — for function analysis.

Above options are enabled by default.

Also, it is possible to disable logging by using option PERSISTENT_MODE.LOGGING.

Details

Cache is stored at .svace-dir/analyze-storage. Currect implementations are based on file system. No databases are used. Every operation stores data to its own directory:

• .svace-dir/analyze-storage/csa — CSA analysis
• .svace-dir/analyze-storage/tags-javac — tags-javac analysis
• .svace-dir/analyze-storage/spotbugs — Spotbugs analysis
• .svace-dir/analyze-storage/procedures — results of procedure parsing
• .svace-dir/analyze-storage/structures — part of procedure parsing that store information about structures and classes for C/C++ analysis
• .svace-dir/analyze-storage/classes — part of procedure parsing that store information about classes for C/C++ analysis
• .svace-dir/analyze-storage/proc-analysis — result of procedure analysis

Logs are put to .svace-dir/analyze-res/logs/<proj>-persistent.log

If cache is enabled then Svace print to console:

Persistent mode is enabled. Some results may be got from cache.

Cache is “flat”. It stores all information from different analysis to the same place. It may be used for analysing different branches of some project. Formally it may be used for analysing different projects, but it is very unlikely that cache will be useful in this case.

Known limitations

The mode is based on file hashes. Even minor changes of 1 bit will lead to hash changes. Any changes lead to cache missing.

Project must be build in the same folder. Changing build folder lead to changing hashes.

Modification of C/C header files lead to changes all modules which are using those headers.

Compiler options also changes hashes.

Svace never clean folder .svace-dir/analyze-res. For now, we do not know what clear mode is needed for users.

Svace settings are not taken into account. If you change option which changes analysis then cache will be incorrect. It is responsibility of user to clean the cache. It is implemented so because many settings are not changes results. For some options it will be desirable to use cache with slightly other results instead of spending more time for analysis.

Svace version are not checked. We do not recommend to use different Svace version with the same cache.

Cache may be ineffective for spotbugs and tags-javac analysis. The reason — compilation unit is used for hash creating. Many Java projects have only one compilation unit.

Analysis with cache may produce different results for main function analysis if they depend on preliminary phase. Preliminary phase collects data about global arrays and constants, performs pointer analysis. Now we can`t define what changes may affect analysis of separate function. If preliminary phase is disabled (USE_PRELIMINARY_PHASE is false) then results should be the same.

Cache does not check it integrity.

Remote analysis

It allows to analyze project on remote server.

How to use

We have two machines remove-server and local-machine. On remove server we have to create svace directory in some folder:

mkdir server
cd server
svace init

Then run svace remote server:

svace server single-start

This command print to console:

Remote analysis server started at port 55135

Now we build project on local machine:

svace init
svace build make

If we would like to analyze project on local machine we run command

svace analyze

but now we want to analyze on server. For doing it we have to run follow command:

svace remote --host remove-server analyze

After running this command, Svace passes all needed data to remote server and performs analysis there. Command remote returns control back when analysis on server is finished. Then it puts results into a .svres file on local machine to regular place: .svace-dir/analyze-res/<proj>.svres.

It is possible to review analysis progress via web browser by reference: http://remote-server:8060/status.

Why remote analysis may be needed

Remote analysis may be useful in follow cases:

• To save resource of local machine. Analysis require many memory and processor times. Remote analysis allows to use it on other machine.
• Using powerful server for analysis. User machine may not have enough resources for analysis.
• Build machine must have all dependencies for building. In many cases it is hard to install all those environment on many machines. Analysis machine has to have powerful processor, many memory and in some cases big disk. Such command allows to use different machines for those tasks.

Data transferring

Data are passed to server by network using port 55135. It may be changed by modifying option SERVER_PORT in file .svace-dir/conf/svace.conf on remote machine. For changing port on local machine parameter port should be used:

svace remote --host remove-server --port 10000 analyze

Data are send efficiently. Sending data takes a little time compared with analysis time. Sending is limited by network throughput.

Transferring is based on file hashes. Only those files that are needed are passed. If remote server already has such file it won`t be sending again. That is why transferring is especially efficient if project regular is built and analyzed on remote server.

Remote analysis server

It may perform several analysis. By default, limit is 3. It is possible to change such behavior by option SIMULTANEOUS_ANALYSIS_LIMIT in file .svace-dir/conf/svace.conf.

If limit is reached client will wait when some analysis will finish.

All analysis data except results (svres-file) are stored on server. Server put data to different folders inside svace-directory and never clear it.

If analysis option ZIP_ANALYZE_RES is enable Svace will compress folder analyze-res to zip file. This option affects remote analysis too and may be used to transferring analysis results to client machine.

Option REJECT_CLIENT_CONFIGS set up a special server config which ignore user setting and warning configs. This option is disabled by default. In this case user can set up configs for settings and warnings on client machine which will be used on server.

Tutorial

This section demonstrates the process of using the tool with an example (analysis of proftpd-1.3.3).

Building source code

Let’s assume that Svace is located in ~/svace/, on an Ubuntu system.

A copy of the proftpd-1.3.3 distributive can be downloaded from the Internet at ftp://ftp.proftpd.org/distrib/source/proftpd-1.3.3.tar.bz2. Extract the archive in ~/projects/proftpd-1.3.3/.

The package can be built using configure/make. To obtain LLVM bitcode files for analysis by svace, svace project folder must be initialized first and then building commands need to be wrapped in svace build command as follows:

cd ~/projects/proftpd-1.3.3
./configure
~/svace/bin/svace init
~/svace/bin/svace build make

If the operation completes successfully, a text like the following will be displayed by build:

Now Svace will preprocess captured data.
Processing source code markup data...
[**********************************************************************] 100%
Assembled build object: [BUILD]6715d4e4c908f8e62a54f174796282c48ce2d3a5
  83 C/C++ units are ready.

As a result, the folder ~/projects/proftpd-1.3.3/.svace-dir/bitcode/ should now contain files with intermediate representation, for example the file

~/projects/proftpd-1.3.3/.svace-dir/bitcode/auth.e7d9dbb866bdbd6c2456bf8f3212d727.bc

Further analysis will only require files within Svace project folder (~/projects/proftpd-1.3.3/.svace-dir), so the other byproducts of the building process can be safely removed.

Performing analysis

Assuming that folder ~/projects/proftpd-1.3.3 contains the svace project folder with intermediate representation files obtained on the previous step, analysis can be launched with the following command:

~/svace/bin/svace analyze --svace-dir ~/projects/proftpd-1.3.3

As a result (it should take a couple of minutes), two files will be created:

~/projects/proftpd-1.3.3/.svace-dir/analyze-res/proftpd-1.3.3.txt
~/projects/proftpd-1.3.3/.svace-dir/analyze-res/proftpd-1.3.3.svres

First file should contain (for example) the following warning of type DEREF_OF_NULL:

* DEREF_OF_NULL: Pointer 'symhold' that can have only NULL value (checked at line 152), is dereferenced at line 153.
    dereference at mod_ls.c:153
    null at mod_ls.c:152
    source line: "*symhold = show_symlinks_hold;"

Corresponding source file fragment (from ~/projects/proftpd-1.3.3/modules/mod_ls.c:152):

if (!symhold)
    *symhold = show_symlinks_hold;

Viewing the results

For example, consider the warning NULL_AFTER_DEREF/proftpd-1.3.3/auth.c:1227. Below is the corresponding excerpt from the plain text file ~/projects/proftpd-1.3.3/.svace-dir/analyze-res/proftpd-1.3.3.txt:

* NULL_AFTER_DEREF: Pointer 'login_name' which was dereferenced at line 1222 is compared to NULL value at line 1227.
    null check at auth.c:1227
    dereference at auth.c:1222
    source line: "if ((!login_name || !anon_c) &&"

The relevant part of the source code is as follows:

1222: if (*login_name &&
          auth_alias_only &&
          *auth_alias_only == TRUE)
        *login_name = NULL;

1227: if ((!login_name || !anon_c) &&
          anon_name) {
        *anon_name = NULL;
      }

On line 1222, variable login_name is dereferenced. If login_name is NULL, this will be a null pointer dereference. On line 1227, this pointer is compared to NULL, which suggests that it indeed can be NULL on line 1222. If it can’t, then the check on line 1227 is redundant.

Warning types

Warning types classify individual warnings (issues) emitted by Svace. Each warning type specifies the kind of defect being sought, typical situations in which such issues are found, and possible sources of false positives. Some warning types have subtypes, allowing more fine-grained classification of the detected issues.

Kinds of warning types

Each warning type is characterized by several properties, which can be inspected by running the warning tool with option --info. These properties can be helpful when deciding which warning types to inspect and when interpreting the results classified under various warning types.

Severity

Severity is an estimate for the potential danger represented by issues of the warning type that are detected correctly. Possible values of this property are Critical, Major, Normal, Minor and Undefined.

Reliability

Reliability is an estimate for how often the issues of a given type are detected correctly. The estimate is based on results obtained on many projects, and actual reliability of results on a given project may significantly deviate from the average. Possible values are VeryHigh, High, Average, Low, VeryLow and Unknown. When there are only a few issues detected for a warning type, it may be worthwhile inspecting even warning types rated Low or VeryLow, but for warning types that are frequently detected, focusing on results of VeryHigh, High and Average reliability is more important.

Type of detected situations

In addition to normal warnings that indicate a defect, there are warnings with different aims, which are described with this property. Suppressed and Duplicate warning types normally shouldn’t be used, but are included for completeness.

• Quality: Warnings of this type indicate defects that can lead to errors and should be fixed. An ideal checker for such warning types should in principle be able to avoid false positives (compare with Suppressed).
• Security: Warnings of this type focus on potential vulnerabilities that may be exploited by a malicious attacker.
• CodingConvention: Coding convention warnings indicate situations where a certain coding convention is violated. Violation of a coding convention doesn’t necessarily lead to an error, and so should only be fixed if the coding convention is encouraged or enforced for the code being analyzed. An ideal checker for such warning types should in principle be able to avoid false positives, but the issues are likely to be of no interest to the projects that don’t follow the coding convention.
• Suppressed: Issues emitted with suppressed warning types are those that could’ve been emitted with a normal (non-suppressed) warning type, but were found to have some flaw that made it probable that they would be false positives. Rather than hiding such issues entirely, we instead change their warning type to a related suppressed warning type. Note that different suppressed warning types may have different reliability, but unlike normal warning types, their reliability often can’t be improved even in principle, and is often low or very low “by design”. In rare cases, reliability of suppressed warnings may be acceptable, in which case it may be worthwhile to inspect their results.
• Duplicate: Warnings of this type are duplicates of other warnings, and so shouldn’t normally be inspected, even if they have high reliability.

Detection tool

Most Svace checkers are implemented in the main analysis framework, which is indicated by SvaceMain detection tool property of the warning type. A few of the checkers that detect simpler situations are implemented in Clang, and have SvaceClang as their detection tool. Issues imported from SpotBugs are marked as having SpotBugs as the detection tool (and have warning type prefix FB.).

Warning subtype specifiers

Some warnings have common subtypes, that are indicated by adding a suffix after a dot to the warning type. For example, the TAINTED_INT warning type has a suppressed subtype TAINTED_INT.MIGHT.

.MIGHT

This subtype indicates that the checker knows of ways in which the warning might be false, and of ways in which the warning might be true, but can’t prove it either way. This is a “weaker” warning subtype, and sometimes the results falling under it should be skipped, but sometimes the detected issues turn out to be correct. Since the checker can’t prove that the issues are correct, even under the heuristic assumptions used to find them, reliability of these warning types is generally lower and can’t be significantly improved.

.PROC (except C#)

This subtype specifies that the runtime error or memory corruption happens inside a user-written procedure called from the code that causes the problem. In other words, the problem is caused by incorrect (unsafe) invocation of a procedure.

.GLOBAL

This subtype indicates that memory locations involved in these warning reports have global scope.

.MINOR

This subtype indicates that severity of warning may be less than for major type.

.STRICT

This subtype indicates that a warning is reported may require very strict error policy to analyzed source code.

.EX

This subtype indicates that a warning is reported by an extended version of the checker.

.EXCEPTION

This subtype indicates that a warning is reported for an exception path.

.RET

This subtype indicates that a warning is related to a value returned from a function.

.LIB

This subtype indicates that a warning is related with a library function.

.LOOP

This subtype indicates that the issue is reported for a specific loop iteration.

.COND

This subtype indicates that the issue is reported for a specific condition branch.

.TEST (C#)

This subtype indicates that a warning is reported in test code.

.ARGUMENT (C#)

This subtype has the meaning of .PROC in C# null dereference checkers.

Null pointer dereference

DEREF_OF_NULL

This checker finds situations where a pointer is dereferenced, but can only have NULL value, and so the operation of dereference can never be run without causing a runtime error. A special case where the NULL value is explicitly assigned is categorized as DEREF_OF_NULL.CONST.

More generally, checkers in the DEREF_OF_NULL group find situations where a dereferenced pointer can be assigned NULL value on one of the possible execution paths.

Subtype .PROC (except C#) or .ARGUMENT (only C#) may be applied to the warnings of this group.

Example (C/C++)

struct process {
    char* user;
};

void test(struct process* ps, FILE* log) {
    if (!ps)
        fprintf(log, "No information for user: %s", ps->user);
}

Dereference of structure pointer ps, if reachable, can only lead to a null pointer dereference.

Example (Kotlin)

fun example(s: String?) {
    if (s == null) {
        derefAnyway(s)
    }
}

fun derefAnyway(s: String?) {
    print(s!!.length)
}

fun possibleFix(s: String?) {
    print(s?.length)
}

Function example illustrates the defect: variable s of nullable type is compared with null directly and is dereferenced by derefAnyway function call.

Function possibleFix illustrates a possible fix: use null safe operator ?. and remove redundant derefAnyway call.

The example given is too synthetic, because it’s quite difficult to create Kotlin code where Svace will report a DEREF_OF_NULL warning, Kotlin compiler will try to prevent you from writing such code by reporting warnings and errors. For example, Kotlin compiler will report a compilation error for exampleOfCompilationError function below.

Example (Kotlin)

fun exampleOfCompilationError(s: String?) {
    if (s == null) {
        s!!.length // kotlin compiler report a compilation error here
    }
}

See also

• DEREF_OF_NULL.CONST
• DEREF_OF_NULL.COND
• DEREF_OF_NULL.RET
• FREE_OF_NULL

DEREF_OF_NULL.EX

This checker is similar to DEREF_OF_NULL checker, but can find situations where a pointer is assigned to NULL under some condition and then dereferenced under another condition which is not incompatible with the first one.

Example (Kotlin)

import java.io.File

fun handleCollection(collection: Collection<Any>?) {
    for (elem in collection!!) {
        // ...
    }
}

fun handleCollectionCorrect(collection: Collection<Any>?) {
    collection?.forEach { elem ->
        // ...
    }
}

fun example(f: File) {
    val files = f.listFiles()?.asList()
    handleCollection(files)
}

fun possibleFix(f: File) {
    val files = f.listFiles()?.asList()
    handleCollectionCorrect(files)
}

Function example illustrates the defect: files may be null, but it will be dereferenced inside handleCollection function call.

Function possibleFix illustrates a possible fix: use safe implementation handleCollectionCorrect to iterate over collection. Safe call of forEach is used inside handleCollectionCorrect function.

DEREF_OF_NULL.CONST

This checker finds situations where a pointer is dereferenced, but can only have NULL value, because it was explicitly assigned a NULL value.

Example

void test() {
    int* ptr = NULL;
    int x;

    // ...

    x = *ptr;
}

Example (Kotlin)

class Holder(str: String) {
    var nullable: Int? = null
}

fun example() {
    val h = Holder("Create and forget to init 'nullable'")
    h.nullable!!.dec()
}

fun possibleFix() {
    val h = Holder("Create and forget to init 'nullable'")
    h.nullable?.dec()
}

Function example illustrates the defect: dec is called for value which may be null.

Function possibleFix illustrates a possible fix: use safe call.

False positives

Sometimes, the pointer is assigned a non-null value as a side effect of a function call. If the analysis is unable to see such a side effect (normally, side effects are analyzed), this warning may be emitted incorrectly.

DEREF_OF_NULL.ASSIGN

This checker finds situations where a pointer is assigned NULL value, and is subsequently dereferenced. In these situations, the dereferenced pointer is not necessarily NULL, but a pointer that was assigned NULL value is necessarily dereferenced.

Example (C/C++)

void proc(int* p, int flag) {
    if (flag == 7)
        p = 0; // NULL value assigned to `p`.

    *p = 7; // If NULL value is assigned to `p`, it's necessarily dereferenced here.
}

Example (Kotlin)

data class Wrapper(val value: Int)

fun example(w: Wrapper?): Int {
    val mayBeNull = w?.value
    return mayBeNull!!
}

fun possibleFix(w: Wrapper?): Int? {
    val mayBeNull = w?.value
    return mayBeNull
}

Function example illustrates the defect: mayBeNull may have null value and is cast to non-nullable type by !! operator.

Function possibleFix illustrates a possible fix: return nullable type.

See also

• DEREF_AFTER_NULL

DEREF_OF_NULL.COND

This checker detects issues where a NULL pointer value is passed to a function, which dereferences it under some uncontrolled conditions.

Example (C/C++)

#include <stddef.h>

extern int get_data();
extern void consume(int);

void deref_maybe(int *p) {
    int data = get_data();
    consume(data);
    if (data > 1) {
        *p += data;
    }
}

void example() {
    deref_maybe(NULL);
}

void deref_fixed(int *p) {
    int data = get_data();
    consume(data);
    if (p && data > 1) {
        *p += data;
    }
}

void example_fixed() {
    deref_fixed(NULL);
}

Function example illustrates the defect: NULL pointer value is passed to deref_maybe function, which dereferences it, if the value of data returned by get_data function is greater than 1.

Functions deref_fixed and example_fixed illustrate a possible fix.

Example (Kotlin)

data class SimpleData(val value: Int)

fun example(): Int {
    return helper(null, null)
}

fun helper(a: SimpleData?, b: SimpleData?): Int {
    if (a != null) {
        return a.value + 2
    } else {
        return b!!.value + 2
    }
}

fun exampleFix(): Int {
    return helperFix(null, null)
}

fun helperFix(a: SimpleData?, b: SimpleData?): Int {
    a?.let { return a.value + 2 }
    b?.let { return b.value + 2 }
    throw IllegalStateException()
}

Function example illustrates the defect: helper function is called with both null arguments and its second argument is cast to non-nullable type by !! operator inside helper function.

Function helperFix illustrates a possible fix: use null safe operator ?..

False positives

Sometimes, the condition under which the function dereferences the pointer is not satisfiable at the call site where NULL value is assigned to that pointer. The checker emits the warning even if this possibility wasn’t ruled out, which leads to false positives in such cases.

DEREF_OF_NULL.EX.COND

This checker detects issues where a NULL pointer value is passed to a function, which dereferences it under certain conditions.

Example (C/C++)

#include <stddef.h>

extern void use(int);

void deref_if(int *p, int x) {
    if (x > 1) {
        x -= *p;
    }
    use(x);
}

void example(int x) {
    deref_if(NULL, x);
}

void example_fixed(int x) {
    deref_if(NULL, x > 1 ? 1 : x);
}

Function example illustrates the defect: NULL pointer value is passed to deref_if function, which dereferences it, if the passed value of x is greater than 1.

Function example_fixed illustrates a possible fix.

DEREF_OF_NULL.STRICT

This checker finds null pointer dereferences that are less reliable than those found by the DEREF_OF_NULL checker. Additionally, for Kotlin it reports situations where a value with a nullable annotation is dereferenced. Note that a nullable annotation is supported as a language feature (a nullable type) in case of Kotlin.

Example (Kotlin)

fun getLen(s: String?) = s!!.length

fun getLenCorrect(s: String?) = s?.length ?: throw IllegalStateException()

fun getLenOf(s: Any?) = (s as String).length

fun getLenOfCorrect(s: Any?) = (s as? String)?.length ?: throw IllegalStateException()

Functions getLen and getLenOf illustrate the defect: s may have null value and is cast to non-nullable type by !! and as operators respectively.

Functions getLenCorrect and getLenOfCorrect illustrate possible fixes: use null safe ?. and as? operators.

DEREF_OF_NULL.RET.ALLOC

This warning finds situations where a pointer returned by a memory allocation function, such as malloc(), is dereferenced without being checked for NULL value.

Example

void test() {
    char* buf = (char*) malloc(10);
    buf[0] = '\0';
}

See also

• DEREF_OF_NULL.RET

DEREF_OF_NULL.RET.LIB

This detector finds situations where a pointer returned by a library function is dereferenced without being checked for NULL value.

Following is the partial list of library functions that are recognized by this detector as being able to return NULL value for reasons not under user’s control:

Examples from C standard library:

• localtime,
• fdopen,
• fopen,
• popen,
• getenv,
• opendir,
• dlopen,
• dlsym,
• freopen,
• tempnam,
• tmpfile,
• tmpnam,
• ptsname,
• getutent,
• getutid,
• getutline,
• pututline,
• getcwd,
• getwd.

Examples from Java libraries:

• java.io.File.listRoots()
• java.io.File.getParent()
• java.io.File.getParentFile()
• java.io.File.listFiles().tryLock()
• java.net.DatagramSocket.getLocalAddress()
• java.nio.channels.FileChannel
• javax.crypto.Cipher.update(byte[])
• javax.crypto.Cipher.update(byte[], int, int)
• android.os.Bundle.getBundle(String)

Example (C/C++)

void example() {
    char *s = getenv("RANDFILE");
    if (s[0] == '\0') {
        // ...
    }
}

void possible_fix() {
    char *s = getenv("RANDFILE");
    if (s != NULL && s[0] == '\0') {
        // ...
    }
}

Function example illustrates the defect: function getenv may return NULL, which will be dereferenced by array access at index 0.

Function possible_fix illustrates a possible fix: check the result of getenv call.

Example (Kotlin)

import java.io.File

fun example(f: File) = f.parentFile.listFiles()

fun possibleFix(f: File) = f.parentFile?.listFiles()

Function example illustrates the defect: property parentFile may return null, which will be dereferenced by listFiles call.

Function possibleFix illustrates a possible fix: use safe call of listFiles function.

DEREF_OF_NULL.RET.LIB.PROC

This detector is a subtype of DEREF_OF_NULL.RET.LIB detector. DEREF_OF_NULL.RET.LIB.PROC finds situations where a pointer returned by a library function may have NULL value and is dereferenced within a function call.

Example (C/C++)

void example() {
    FILE *f;
    f = fopen("test.txt", "r");
    fclose(f);
}

void possible_fix() {
    FILE *f;
    f = fopen("test.txt", "r");
    if (f != NULL) {
        fclose(f);
    }
}

Function example illustrates the defect: function fopen may return NULL, which will be dereferenced within fclose call.

Function possible_fix illustrates a possible fix: check the result of fopen call.

Example (Kotlin)

import java.io.File
fun handleFiles(arr: Array<File>?) = arr!!.count { f -> f.isFile && !f.isDirectory }

fun exampleProc(f: File) = handleFiles(f.listFiles())

fun handleFilesCorrect(arr: Array<File>?) = arr?.count { f -> f.isFile && !f.isDirectory } ?: 0

fun possibleFixProc(f: File) = handleFilesCorrect(f.listFiles())

Function exampleProc illustrates the defect: call of listFiles function may return null, which will be dereferenced within the call of user defined function handleFiles.

Function possibleFixProc illustrates a possible fix: use safe implementation handleFilesCorrect to iterate over files. Safe call of count is used inside handleFilesCorrect function, also it returns zero if arr is null.

See also

• DEREF_OF_NULL.RET

DEREF_OF_NULL.RET.USER

This is an obsolete detector. Both DEREF_OF_NULL.RET.USER and DEREF_OF_NULL.RET.USER.PROC have been replaced with DEREF_OF_NULL.RET detector.

DEREF_OF_NULL.RET.USER.PROC

This is an obsolete detector. Both DEREF_OF_NULL.RET.USER and DEREF_OF_NULL.RET.USER.PROC have been replaced with DEREF_OF_NULL.RET detector.

DEREF_OF_NULL.RET

This detector finds situations where a pointer returned by a user-written procedure that returns NULL on some execution paths, is dereferenced without being checked for NULL value.

Example (C/C++)

#define USE_PREFIX 1
#define MAX_SIZE 1024

char* buf[MAX_SIZE];

char* get_login(const char* url, int flag) {
    if (flag == USE_PREFIX && url[0] != '%' && url[1] != '%')
        return NULL;

    return fill_from_bd(buf, MAX_SIZE);
}

void use(const char* url) {
    char* login = get_login(url, USE_PREFIX);
    int len = strlen(login);
    // ...
}

Example (Kotlin)

data class Wrapper(val value: Int)

class Helper(val wr: Wrapper?) {
    fun getMaybeNull() = wr?.value
}

fun deref(n: Int?) = n!!.times(3)

fun example(h: Helper): Int {
    val num = h.getMaybeNull()
    return deref(num)
}

fun derefCorrect(n: Int?) = n?.times(3)

fun possibleFix(h: Helper): Int? {
    val num = h.getMaybeNull()
    return derefCorrect(num)
}

Function example illustrates the defect: num may be null after getMaybeNull call and it is dereferenced by call of user defined function deref. Function possibleFix illustrates a possible fix: use safe implementation derefCorrect. Safe call of times is used inside derefCorrect function.

DEREF_OF_NULL.RET.STAT

This detector is a statistical version of DEREF_OF_NULL.RET.

It detects issues when a pointer returned by call to a function is dereferenced without a check to NULL, while for a number of other calls to the same function it is dereferenced only after a proper NULL check.

Example (C/C++)

#include <stddef.h>

extern int *get_ptr(int);

void example() {
    int *p1 = get_ptr(1);
    if (p1)
        *p1 = 3;
    int *p2 = get_ptr(2);
    if (p2)
        *p2 = 1;
    int *p3 = get_ptr(3);
    if (p3)
        *p3 = 4;
    int *p4 = get_ptr(4);
    if (p4)
        *p4 = 1;
    int *p5 = get_ptr(5);
    //if (p5)
        *p5 = 5;
    int *p6 = get_ptr(6);
    if (p6)
        *p6 = 9;
    int *p7 = get_ptr(7);
    if (p7)
        *p7 = 2;
    int *p8 = get_ptr(8);
    if (p8)
        *p8 = 6;
}

Function example illustrates the defect: each time the function get_ptr is called, the returned value is checked to NULL before its dereference, except for variable p5.

Possible fix is to uncomment the commented if, which checks pointer p5 before its dereference.

Settings

• STAT.EXAMPLES_NUMBER
• GROUP_RESULTS_OF_STAT_CHECKERS
• GROUP_RESULTS_OF_DEREF_OF_NULL.RET.STAT
• DEREF_OF_NULL.RET.STAT.THRESHOLD
• DEREF_OF_NULL.RET.STAT.MAX_FAILS_IN_FILE

See also

• UNCHECKED_FUNC_RES.STAT

DEREF_OF_NULL.DYN_CAST

This checker finds issues where pointer value is the result of dynamic_cast C++ operator, it might be NULL, and it is dereferenced without an appropriate check.

Example (C/C++)

class A {
public:
    virtual int a() { return 0; }
};

class B : public A { 
public:
    virtual int a() { return 1; }
    virtual int b() { return 0; }
};

int example(A *a) {
    B *b = dynamic_cast<B*>(a);
    return b->b();
}

int example_fixed(A *a) {
    B *b = dynamic_cast<B*>(a);
    if (!b)
        return -1;
    return b->b();
}

Function example illustrates the defect: pointer b is the result of dynamic_cast operator, and it is dereferenced without any check.

Function example_fixed illustrates a possible fix.

False positives

Sometimes, a complex program logic might guarantee that dynamic_cast can be used safely without any additional checks, while the analysis is not able to prove it.

DEREF_OF_NULL.DYN_CAST.PROC

This checker finds issues where a pointer value comes from a call to function, where the pointer is the result of dynamic_cast C++ operator and it might be NULL, and then it is dereferenced after the call without an appropriate check.

Example (C/C++)

class A;
class B;

class A {
public:
    virtual int a() { return 0; }
    B *asB();
};

class B : public A { 
public:
    virtual int a() { return 1; }
    virtual int b() { return 0; }
};

B *A::asB() {
    return dynamic_cast<B *>(this);
}

int example(A *a) {
    B *b = a->asB();
    return b->b();
}

int example_fixed(A *a) {
    B *b = a->asB();
    if (!b)
        return -1;
    return b->b();
}

Function example illustrates the defect: pointer b is the return value of call to A::asB, where it comes from dynamic_cast operator, and it is dereferenced without any check.

Function example_fixed illustrates a possible fix.

False positives

Sometimes, a complex program logic might guarantee that dynamic_cast can be used safely without any additional checks, while the analysis is not able to prove it.

DEREF_AFTER_NULL

This checker finds situations where first, a pointer is compared to NULL (which indicates that it could have a NULL value), and then it is dereferenced (unconditionally).

A subtype DEREF_AFTER_NULL.LOOP is emitted when the conditional expression comparing the pointer to NULL is part of a loop.

A (suppressed) .MACRO subtype of this warning is emitted if it is suspected that the warning is a false positive, caused by the conditional expressions being implemented within a macro. Such checks can be too general and not always reflect possible value range of index variables.

Example (C/C++)

int test(char* str1, char* str2, int len) {
    if (!str1) {
        len = 0;
    } else {
        len = strlen(str1);
    }
    return strcmp(str1, str2);
}

If str1 can be NULL, so that the conditional isn’t trivial, then call of strcmp will lead to a null pointer dereference.

Example (Kotlin)

data class Client(val name: String, val age: Int)

fun example(arg: Client?) {
    val age = arg?.age
    println("Client '${arg!!.name}' is $age years old")
}

fun possibleFix(arg: Client?) {
    val age = arg?.age
    age?.let{ println("Client '${arg.name}' is $age years old") }
}

Function example illustrates the defect: age is got from arg with null check, but name is got avoiding null check.

Function possibleFix illustrates a possible fix. Note that Kotlin compiler knows that arg is not null into let code block.

False positives

This warning can cause false positives if the conditional expression has a side effect of terminating the program, but that wasn’t noticed by the tool. For example:

if (!str1) {
    my_exit();
}
return strcmp(str1, str2);

If instead of my_exit(), a standard exit(int) is called, no false warnings will be emitted. The same holds if my_exit() transparently calls exit(int) or one of the other functions annotated as terminating.

See also

• DEREF_OF_NULL.ASSIGN

DEREF_AFTER_NULL.EX

This checker is a version of the DEREF_AFTER_NULL with path sensitivity. Unlike DEREF_AFTER_NULL, it gives warning when the variable after comparing with null can be dereferenced, and there is a combination of the input parameters, what may cause an error.

Example (Kotlin)

import java.text.DateFormat
import java.util.*

fun example(date: String?): Date {
    date?.let{ println("parsing: '$date'") }
    val df = DateFormat.getDateInstance(DateFormat.LONG, Locale.KOREA)
    return df.parse(date)
}

fun possibleFix(date: String): Date {
    println("parsing: '$date'")
    val df = DateFormat.getDateInstance(DateFormat.LONG, Locale.KOREA)
    return df.parse(date) // svace: not_emitted DEREF_AFTER_NULL*
}

Function example illustrates the defect: date may be null according to safe call of let block, but it has been dereferenced onwards by passing as first parameter into parse method.

Function possibleFix illustrates a possible fix: change function contract. First argument of possibleFix function is non-nullable.

DEREF_AFTER_NULL.COND

This checker detects issues where a pointer is compared to NULL (which indicates that it could be NULL) and then passed to a function, which dereferences it under some uncontrolled conditions.

Example (C/C++)

extern int get_some_data();

void deref_under_some_condition(int *p) {
    if (get_some_data() > 0) {
        *p = -1;
    }
}

void example(int *p) {
    if (p) {
        *p = 123;
    }   

    deref_under_some_condition(p);
}

void example_fixed(int *p) {
    if (p) {
        *p = 123;
    }   

    if (p) {
        deref_under_some_condition(p);
    }
}

Function example illustrates the defect: variable p is compared to NULL and then passed to function deref_under_some_condition which could dereference it under a condition, that depends on some uncontrolled integer value (returned by function get_some_data).

Function example_fixed illustrates a possible fix.

False positives

In some cases the checker might miss information that the condition of the dereference within the called function is not feasible with the precondition of the call itself.

DEREF_AFTER_NULL.EX.COND

This checker detects issues where a pointer is compared to NULL (which indicates that it could be NULL) and then passed to a function, which dereferences it under certain conditions.

Example (C/C++)

void deref_if_x_is_positive(int *p, int x) {
    if (x > 0) {
        *p = x;
    }
}

void example(int *p, int x) {
    if (p) {
        *p = 123;
    }   

    deref_if_x_is_positive(p, x);
}

void example_fixed(int *p, int x) {
    if (p) {
        *p = 123;
    }   

    if (p) {
        deref_if_x_is_positive(p, x);
    }
}

Function example illustrates the defect: pointer p is compared to NULL and then passed to function deref_if_x_is_positive which could dereference it, if condition x > 0 is true.

Function example_fixed illustrates a possible fix.

False positives

In some cases the checker might miss information that the condition of the dereference within the called function is not feasible with the precondition of the call itself.

DEREF_AFTER_NULL.LOOP

This checker detects issues where a pointer is compared to NULL (which indicates that it could be NULL) in a loop condition, and then the pointer is dereferenced.

Example (C/C++)

struct Item {
    int id;
    int value;
    struct Item *next;
};


int example(Item *start, int id) {
    Item *item = start;
    while (item && item->id != id) {
        item = item->next;
    }
    return item->value;
}

int example_fixed(Item *start, int id) {
    Item *item = start;
    while (item && item->id != id) {
        item = item->next;
    }

    if (!item)
        return 0;

    return item->value;
}

Function example illustrates the defect: variable item is compared to NULL in a while loop condition and then dereferenced after the loop.

Function example_fixed illustrates a possible fix.

False positives

Sometimes, when a loop uses several conditions which controls its execution, the assumption that the comparison implies NULL value might not be correct for the path, where the warning is reported, due to some additional unexplicit preconditions.

DEREF_AFTER_NULL.MIGHT

This checker detects issues where a pointer is compared to NULL (which indicates that it could be NULL), and then dereferenced on a path, where the program execution might be terminated, while the analysis is not able to ensure, whether it avoids NULL pointer dereference, or not.

Example (C/C++)

#include <stdlib.h>

extern int get_error_level(int error_id);

void handle_error(int error_id) {
    if (get_error_level(error_id) > 1) {
        exit(1);
    }
}

void example(int *p) {
    if (!p) {
        handle_error(313);
    }
    *p = -1;
}

void example_fixed(int *p) {
    if (!p) {
        handle_error(313);
    } else {
        *p = -1;
    }
}

Function example illustrates the defect: variable p is compared to NULL and then dereferenced, while on a path, where it is null function handle_error is called, which might terminate the program execution.

Function example_fixed illustrates a possible fix.

False positives

Sometimes, the program logic guarantees that the called function will always terminate the program execution, when the pointer is NULL, but the analysis is not able to prove it.

NULL_AFTER_DEREF

The checker NULL_AFTER_DEREF finds situations where first, a pointer is dereferenced, and then it is compared to null (which indicates that it could have a NULL value).

A (suppressed) .MACRO subtype of this warning is emitted if it is suspected that the warning is a false positive, caused by the conditional expressions being implemented within a macro. Such checks can be too general and not always reflect possible value range of index variables.

Example (C/C++)

struct bank {
    char* name;
    char* pool;
};

void test(struct bank* c, char* name) {
    strcpy(name, "<Global>");

    if (name)
        c->name = pstrdup(c->pool, name);
}

If name can be NULL, so that the conditional isn’t trivial, then call of strcpy will lead to a null pointer dereference.

Example (Kotlin)

import java.text.DateFormat
import java.util.Date
import java.util.Locale

fun example(date: String?): Boolean {
    val df = DateFormat.getDateInstance(DateFormat.LONG, Locale.KOREA)
    val ret = df.parse(date)
    date?.let{ println("'$date' has been parsed") } // svace: emitted NULL_AFTER_DEREF
    return ret.after(Date(2020, 12, 10))
}

fun possibleFix(date: String?): Boolean {
    val ret = date?.let {
        val df = DateFormat.getDateInstance(DateFormat.LONG, Locale.KOREA)
        df.parse(date).also { println("'$date' has been parsed") }
    }
    return ret?.after(Date(2020, 12, 10)) ?: false
}

Function example illustrates the defect: date may be null according to safe call of let block but it has been dereferenced earlier by passing as first parameter into parse method.

Function possibleFix illustrates a possible fix: wrap more code into let block.

Notes

In some cases, the dereference indicated in the warning points to a function that returns the pointer. Such warnings mean that the function that produced the pointer unconditionally dereferences it, and so the returned pointer can’t be NULL. In some cases, the code that checks the returned value for quality to NULL is protective or follows the specification that allows NULL value as possible behavior. In other cases, presence of the check indicates an incorrect assumption about the function.

See also

• NULL_AFTER_DEREF.RET
• COMPARE_LOCAL_ADDR

NULL_AFTER_DEREF.RET

The checker is like NULL_AFTER_DEREF, but it finds situations where pointer was dereferenced in a function and then returned. If the caller of that function still compares the returned value to NULL, they believe that it’s possible for the returned value to be NULL, while it’s actually not.

Example

char* get_buf(void) {
    char* buf = (char*) malloc(100);
    buf[0] = 'q';
    return buf;
}

void foo(void) {
    char* res = get_buf();
    if (res) // NULL_AFTER_DEREF.RET: `res` can't be NULL.
        res[1] = 'w';
}

COMPARE_LOCAL_ADDR

Since address of a local variable can’t be null comparing it with null value is redundant.

Example

int foo() {
    int x = 0;
    if (&x) // COMPARE_LOCAL_ADDR, maybe it should be `if (x)`.
        return 0;
    return 1;
}

Tainted input

Tainted input checkers find situations where a value obtained from external sources (network, files, environment variables) is used in an operation sensitive to incorrect or malicious parameters. The externally controlled value is called tainted, the location where tainted value is obtained is called source, and the location where tainted value is dangerously used is called sink. Checkers in this group consider tainted values of integer or C string types. TAINTED_INT.LOOP considers loop bounds as sinks.

Sources for TAINTED_INT:

int getch(void);
int _getch(void);
int getchar(void);

int atoi(const char* arg);
long atol(const char* arg);
long long atoll(const char* arg);
long strtol(const char *restrict nptr, char **restrict endptr, int base);
long long strtoll(const char *restrict nptr, char **restrict endptr, int base);
unsigned long strtoul(const char *restrict nptr, char **restrict endptr, int base);
unsigned long long strtoull(const char *restrict nptr, char **restrict endptr, int base);

elements of tainted integer arrays

Sinks for TAINTED_INT:

char *fgets(char *s, int num, FILE *stream);
void* memset(void * ptr, int value, size_t num);
ssize_t pwrite(int d, const void *buf, size_t nbytes, off_t offset);
ssize_t write(int d, const void *buf, size_t nbytes);

void *calloc(size_t num, size_t size);
void *malloc(size_t size);
void *xmalloc(unsigned long size);
void *realloc(void *ptr, size_t size);
void *xrealloc (void *ptr, size_t size);

Sources for TAINTED_PTR:

ssize_t recv(int s, void *buf, size_t len, int flags);
ssize_t recvfrom(int s, void *buf, size_t len, int flags, struct sockaddr *from, socklen_t *fromlen);
char *fgets(char *s, int num, FILE *stream);
size_t fread(void *ptr, size_t size, size_t nitems, FILE *stream);
char *gets(char *s);
ssize_t getline(char **lineptr, size_t *n, FILE *stream);
char *getenv(const char* key);
ssize_t read(int d, void *buf, size_t nbytes);

scanf(...)

Sinks for TAINTED_PTR:

FILE *fopen(const char *filename, const char *mode);
FILE *freopen(const char *filename, const char *mode, FILE *stream);
FILE *popen(const char *command, const char *mode);
char* strcat(char *s, const char * append);
char* strcpy(char *dst, const char *src);
char* stpcpy(char *dst, const char *src);

Format string sinks:

void err(int eval, const char *fmt, ...);
void verr(int eval, const char *fmt, va_list args);
void errx(int eval, const char *fmt, ...);
void verrx(int eval, const char *fmt, va_list args);
void warn(const char *fmt, ...) ;
void vwarn(const char *fmt, va_list args);
void warnx(const char *fmt, ...);
void vwarnx(const char *fmt, va_list args);
void error(int status, int errnum, const char *fmt, ...);
int fprintf(FILE *stream, const char *format, ...);
int fscanf(FILE *stream, const char *format, ...);
int printf(const char *format, ...);
int scanf(const char *format, ...);
int sprintf(char *s, const char *format, ...) ;
int snprintf(char *str, size_t size, const char *format, ...);
int asprintf(char **ret, const char *format, ...);
int sscanf(const char *s, const char *format, ...);
int vscanf(const char *format, va_list ap);
int vsscanf(const char *str, const char *format, va_list ap);
int vfscanf(FILE *stream, const char *format, va_list ap);
int vfprintf(FILE *stream, const char *format, va_list ap);
int vprintf(const char *format, va_list ap);
int vsprintf(char *s, const char *format, va_list ap);
int vsnprintf(char *str, size_t size, const char *format, va_list ap);
int vasprintf(char **ret, const char *format, va_list ap);
void setproctitle(const char *fmt, ...);
void syslog(int priority, const char *message, ...);
void Tcl_Panic(const char* format, ...);
void panic(const char* format, ...)

TAINTED_INT

The checker TAINTED_INT finds situations where an integer value received from external source (from a file or from the network; such value is called tainted value) is used in an operation where uncontrolled value may cause problems, such as allocation of memory of given size, or reading the given number of bytes from a file.

There is a .MIGHT variant of this warning (TAINTED_INT.MIGHT).

This warning has the following subtypes:

• TAINTED_ARRAY_INDEX — tainted value is used as an index to access an array.
• TAINTED_INT.CTYPE — tainted value is used in ctype functions (such as isdigit).
• TAINTED_INT.PTR — tainted value is used as an index to access an array through a pointer.
• TAINTED_INT.LOOP — tainted value is used as a loop bound.

Example

size_t size;
char* res;

void test() {
    char* env = getenv("QQQ");
    size = strtoul(env, NULL, 10);

    // Allocating a buffer of unbounded number of bytes.
    res = (char*) malloc(size);
}

TAINTED_INT.MIGHT

.MIGHT variant of TAINTED_INT, which finds situtations where tainted value is used in an unsafe operation, where value is tainted only on some execution paths.

Example

void test(char* str, int flag) {
    int count;
    if (flag) {
        count = atoi(str);
    } else {
        count = -1;
    }

    usleep(count);
}

TAINTED_INT.CTYPE

A subtype of TAINTED_INT, where a tainted value is used in character type functions from header <ctype.h> (isdigit, isspace, etc.). ISO C requires that ctype functions work for unsigned char values and for EOF. Other values may lead to undefined behavior, but many library implementations also support negative signed char and some other values. This warning is suppressed if tainted integer is known to have values only in interval [-128; 255].

Example

char ch = '0';
int val;

void int_type() {
    scanf("%d", &val);
    if (isdigit(val)) // Here the program may crash; TAINTED_INT.CTYPE is emitted.
        ch = (char) val;
}

TAINTED_INT.LOOP

A subtype of TAINTED_INT, where the tainted value is used as a bound in a loop, and thus may cause the program to hang.

There is a .MIGHT variant of this warning (TAINTED_INT.LOOP.MIGHT).

Example

size_t size;
char* res;

void test() {
    int i;
    char* env = getenv("QQQ");
    size = strtoul(env, NULL, 10);

    for (i = 0; i < size; i++) {
        // ...
    }
}

TAINTED_INT.LOOP.MIGHT

.MIGHT variant of TAINTED_INT.LOOP, which find situations where loop bound is tainted only on some execution paths.

Example

size_t size;
char* res;

void test(bool flag) {
    int i;

    if (flag) {
        char* env = getenv("QQQ");
        size = strtoul(env, NULL, 10);
    } else {
        size = 0;
    }

    for (i = 0; i < size; i++) {
        // ...
    }
}

TAINTED_INT.INFINITE_LOOP

A subtype of TAINTED_INT, where the tainted value is used as a loop step, and thus may cause the loop to be infinite.

There is a .MIGHT variant of this warning (TAINTED_INT.INFINITE_LOOP.MIGHT).

Example

void test() {
    int step = getchar();

    for (char i = 0; i < 100; i += step) {
        // ...
    }
}

TAINTED_INT.INFINITE_LOOP.MIGHT

.MIGHT variant of TAINTED_INT.INFINITE_LOOP, which find situations where loop step is tainted only on some execution paths.

Example

void test(bool flag) {
    int step;
    if (flag) {
        step = getchar();
    } else {
        step = 1;
    }

    for (char i = 0; i < 100; i += step) {
        // ...
    }
}

TAINTED_ARRAY_INDEX

The checker TAINTED_ARRAY_INDEX finds situations where an integer value received from external source (from a file or from the network) is used as an index in accessing an array, without ensuring that it’s within bounds. This warning is a subtype of TAINTED_INT.

There is a .MIGHT variant of this warning (TAINTED_ARRAY_INDEX.MIGHT).

Example (C/C++)

void array_index() {
    int buf[256];
    int index = getchar();

    if (index < 256) {
        // Index may still be negative!
        buf[index] = 7;
    }
}

Example (Kotlin)

fun example(number: String) {
    val num: Int = number.toInt()
    val x: IntArray = intArrayOf(1, 2, 3)
    if (num < 3) {
        print(x[num])
    }
}

fun possibleFix(number: String) {
    val num: Int = number.toInt()
    val x: IntArray = intArrayOf(1, 2, 3)
    if (num >=0 && num < 3) {
        print(x[num])
    }
}

Function example illustrates the defect: num is converted from string value. Only the right bound of num is checked and num may be still negative when it’s used as array index.

Function possibleFix illustrates a possible fix: check the left bound of num as well.

TAINTED_ARRAY_INDEX.MIGHT

.MIGHT version of TAINTED_ARRAY_INDEX, which checks if out-of-bounds array access could happen on some execution paths.

Example

void array_index(bool flag) {
    int buf[256];
    int index = getchar();

    if (flag && index < 256) {
        // Index may still be negative!
        buf[index] = 7;
    }
}

TAINTED_ARRAY_INDEX.EX

Extended version of TAINTED_ARRAY_INDEX, which checks if out-of-bounds array access could happen on some execution paths. Very similar to TAINTED_ARRAY_INDEX.MIGHT, but can find more diffucult cases.

Example

int bounded_getchar(int bound) {
    int res = getchar();
    return res > bound ? bound : res;
}

void array_index_error(int bound) {
    int buf[256];

    // If bound > 256, index may be equal to 256
    int index = bounded_getchar(bound > 256 ? 256 : bound);

    if (index >= 0) {
        // Index may still be equal to 256
        buf[index] = 7;
    }
}

void possible_fix(int bound) {
    int buf[256];

    // Index is not greater than 255
    int index = bounded_getchar(bound > 255 ? 255 : bound);

    if (index >= 0) {
        // No error here
        buf[index] = 7;
    }
}

TAINTED_INT.PTR

This checker is very similar to TAINTED_ARRAY_INDEX, except that it finds situations where array access with tainted index value happens through a pointer (TAINTED_ARRAY_INDEX is emitted only when the array is identified explicitly by name).

There is a .MIGHT variant of this warning (TAINTED_INT.PTR.MIGHT).

Example

void set_base(char* base) {  // Here 'base' an unknown pointer that probably points to an array.
    char* env = getenv("QQQ");
    size_t size = strtoul(env, NULL, 10);
    base[size] = '\0'; // Accessing an array through pointer `base` by tainted index `size`.
}

TAINTED_INT.PTR.MIGHT

.MIGHT variant of TAINTED_INT.PTR, which checks if out-of-bounds array access could happen on some execution paths.

Example

void set_base(char* base, bool flag) {  // Here 'base' an unknown pointer that probably points to an array.
    char* env = getenv("QQQ");
    size_t size = strtoul(env, NULL, 10);
    if (flag) {
        base[size] = '\0'; // Accessing an array through pointer `base` by tainted index `size`.
    }
}

TAINTED_PTR

The checker TAINTED_PTR finds situations where a string received from external source (from a file or from the network) is used in an operation where uncontrolled string (or unbounded size of the string) may cause problems, such as copying to a fixed-size array.

There is a .MIGHT variant of this warning TAINTED_PTR.MIGHT.

Example

char* env;
char buf[100];

void test() {
    env = getenv("VAR3");

    // Copying a string of unbounded size to a fixed-size buffer.
    strcpy(buf, env);
}

TAINTED_PTR.MIGHT

.MIGHT variant of TAINTED_PTR, which find situtations where string is tainted only on some execution paths.

Example

char* env;
char buf[100];

void test(bool flag) {
    if (flag) {
        env = getenv("VAR3");
    } else {
        env = "NONE";
    }

    // Copying a string of unbounded size to a fixed-size buffer.
    strcpy(buf, env);
}

TAINTED.SPRINTF

This checker finds uses of library function sprintf() that may overflow the destination buffer, because some values (integer values or strings) printed according to a constant format string are tainted and unchecked.

Example 1

char buf[100];
char dst[16];

void test() {
    fgets(buf, 50, stdin);
    sprintf(dst, "* %s\n", buf);
}

Example 2

size_t size;
char dst[5];

void test() {
    char* env = getenv("QQQ");
    size = strtoul(env, NULL, 10);

    sprintf(dst, "%d", size);
}

TAINTED_PTR.FORMAT_STRING

The checker TAINTED_PTR.FORMAT_STRING finds situations where a string received from external source (from a file or from the network) is used as a format string parameter in functions of printf() family. This vulnerability may be used in a format string attack.

Example

void fmt_str(int s, char* buf, int len, int flags) {
    recv(s, buf, len, flags);
    printf(buf);
}

Buffer overflow

STATIC_OVERFLOW

The checker STATIC_OVERFLOW finds situations where a fixed-size array is accessed at a constant index outside its range.

Example

void buf_overflow() {
    char buf[1024];
    buf[1024] = 0;
}

DYNAMIC_OVERFLOW

The checker DYNAMIC_OVERFLOW finds situations where a dynamic array is accessed at a constant index outside its range.

Example

void buf_overflow() {
    char *buf = (char *) malloc(1024);
    buf[1024] = 0;
    free(buf);
}

DYNAMIC_OVERFLOW.EX

Path sensitive version of the DYNAMIC_OVERFLOW. It checks if a path exists where dynamic array is accessed at a constant index outside its range.

Example

void buf_overflow() {
    char *buf = (char *) malloc(1024);
    buf[1024] = 0;
    free(buf);
}

STATIC_OVERFLOW.LOCAL

This checker finds buffer overflow situations where a buffer is accessed (with potential overflow) in the same procedure where it’s locally defined.

Example

void access_buf(int index) {
    int buf[10];
    buf[index] = 7;
}

void run() {
    int i;
    if (i >= 10)
        access_buf(i);
}

Here, the situation is detected interprocedurally (the condition that index is outside bounds is specified outside function access_buf). Warning of this type is emitted, because buffer access operation is in the same procedure as definition of the buffer.

See also

• STATIC_OVERFLOW.PROC

STATIC_OVERFLOW.PROC

This checker finds buffer overflow situations where a buffer is passed into another procedure before being accessed (with potential overflow).

Example

void access_buf(int* buf) {
    buf[10] = 0;
}

void run() {
    int buf[10];
    access_buf(buf);
}

Since buf is only 10 elements long, the access operation in procedure access_buf overflows the buffer. This situation is detected interprocedurally, since the size of the buffer is not available inside procedure access_buf.

See also

• STATIC_OVERFLOW.LOCAL

DYNAMIC_OVERFLOW.PROC

This checker finds overflows for heap buffers where a buffer is passed into another procedure before being accessed (with potential overflow).

Example

void access_buf(int* buf)
{
    buf[10]=0;
}

void test() {
    int* buff = new int[10];
    access_buf(buff); // Overflow.
}

STATIC_OVERFLOW.SPRINTF

This checker finds situation where a function from sprintf() family is used to write to a buffer of known size, but the constant format string and possible values of the arguments are such that the buffer could overflow as a result of the call.

Example

void static_overflow(char* val) {
    char buf[6];
    sprintf(buf,"%d!", val);
}

The checker will emit a warning for this example, unless val is known to be in the interval [-999, 9999] (up to 4 characters for the value, one for symbol ! and one for NULL terminator at the end of the string, total of up to 6 characters).

STATIC_OVERFLOW.SCANF

This checker finds situation where a function from scanf() family is used to read data into a buffer of known size, but the constant format string and possible values of the source of the data are such that the buffer could overflow as a result of the call.

Example

void static_overflow(FILE* f) {
    char buf[50];
    fscanf(f, "%s", buf); // `buf` can overflow.
}

Since the number of bytes read from the stream f is not restricted, the buffer can overflow. One way to fix this defect is to specify the maximum number of characters to be read explicitly:

void avoid_overflow(FILE* f) {
    char buf[50];
    fscanf(f, "%49s", buf); // `buf` can't overflow: bounds specified in format string.
}

BUFFER_OVERFLOW.EX

This checker detects potential overflows of fixed-size arrays on certain execution paths. It reports a warning when an array may be accessed beyond its right bound. Out-of-bounds array access leads to Undefined Behaviour (C/C++), Runtime Exception (Java), or run-time panic (Go).

enum Type {
  TYPE_ONE,
  TYPE_TWO,
  TYPE_THREE,
  TYPE_INVALID
};

enum Type get_type (int data) {
     if (data == 100)
         return TYPE_ONE;

     if (data == 200)
         return TYPE_TWO;

     return TYPE_INVALID;
}


const char* get_name (const char *n[], enum Type type) {
    return n[(int)type];
}

const char* example (int data, int flag) {
  const char* names[3] = {"First", "Second", "Third"};
  enum Type type = flag ? TYPE_THREE : get_type(data);

  // overflow in `get_name` occurs when type is TYPE_INVALID
  return get_name(names, type);
}

BUFFER_UNDERFLOW

This checker detects potential buffer underflows on certain execution paths. It reports a warning when an array may be accessed beyond its left bound (with negative index). Out-of-bounds array access leads to Undefined Behaviour (C/C++), Runtime Exception (Java), or run-time panic (Go).

unsigned a[1024];
void example(int x) {
    int len, i, j;
    for (i = 0; i < 1024; i += 4)
    {
        len = x++ / 2;
        for (j = 0; j < len; j++)
            a[i+j] &= 0xfffffffe;

        // buffer underflow happens on 1st iteration if (x == 0)
        a[i+(j-1)] |= 1;
    }
}

CHECK_AFTER_OVERFLOW

The checker CHECK_AFTER_OVERFLOW finds situations where first, a buffer is accessed with a certain index, and then this index is compared to some value that indicates that the index may lie outside the buffer’s range.

Example

char buf[256];

int test(int i) {
    buf[i] = 0;

    if (i != 256)
        return 1;
    return 0;
}

In this example, the check at the end shows that i is expected to sometimes have a value of 256, in which case the buffer access above will be out of bounds.

A (suppressed) .MACRO subtype of this warning is emitted if it is suspected that the warning is a false positive, caused by the conditional expressions being implemented within a macro. Such checks can be too general and not always reflect possible value range of index variables.

OVERFLOW_AFTER_CHECK

The checker OVERFLOW_AFTER_CHECK finds situations where first, a variable is compared to some value, indicating what the possible values of the variable are, and then it’s used to access a buffer in such a way that one of the possible values indicated by the check lies out of bounds.

Example

char buf[256];

void overflow(int i) {
    if (i > 255)
        printf("i > 255");

    buf[i] = 0;
}

OVERFLOW_AFTER_CHECK.EX

The checker is similar to OVERFLOW_AFTER_CHECK, but uses SMT solver and is capable of finding and filtering out more complex defects.

Example

struct A {
    int x[10];
    int y;
};

struct A array[10];

void func(struct A *q) {
    int i;
    for (i = 0; i <= 10; i++) {
        array[i] = q[i]; // `i` may be 10, but the last index is 9.
    }
}

OVERFLOW_UNDER_CHECK

Issues of this type are detected when the value of an index used to access a buffer is checked with a bound that is less strict than necessary. A bound on an index value can be used to ensure the absence of buffer overflows due to index value being too high or too low, but if the bound is itself too high or too low, a buffer overflow can still occur. For example, if a buffer has 10 elements, index values up to 9 are permitted, but checking that the index is less than 20 allows values between 10 and 19 that would lead to buffer overflow.

Example

int buf[10];

if (i < 20)
    buf[i] = 3; // Possible buffer overflow.

if (i >= -1)
    buf[i] = 5; // Possible buffer overflow.

for (i = 0; i < 100; ++i)
    buf[i] = 7; // Possible buffer overflow.

OVERFLOW_UNDER_CHECK.LIB