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
• 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
  • 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 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 time. Default options should be suitable for most scenarios but it is possible to tune several parameters manually. By using the config tool it is possible to change them:

svace config THREAD_NUMBER 4

In the example above the THREAD_NUMBER configuration variable sets the number of parallel threads used for analysis as 4. By default the THREAD_NUMBER option has value 'auto' and the analyzer selects threads number depending of current processor loading. Value 'max' sets threads number equal to the processor kernels. And you may use any positive integer number. Usually analysis is faster if THREAD_NUMBER is 'max'. But every thread spend some amount of memory and more threads will spend more memory. So on machines with low memory it is better to reduce threads number.

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 of the 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 folder 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:
    add                 Add new sources to current build.
    admin               Manage object pool in a project directory.
    clean               Remove old annotations.
    context-spec        Manage context in which particular function will be
                        analyzed.
    del                 Delete given sources from project.
    export-build        Export a build object into an external directory.
    fa-diff             Compare warning results for fast analysis mode for
                        oldand new svace distributives.
    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:
    cgoc                Tool to compare call graph logs.
    cgop                Tool to calculate sub-call graph order.
    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.
    mark-multi-lang-warn
                        A tool marking multi-language warnings in 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.

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>
       svace build [options] --update [TARGET...]

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).
  --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, Java compilations
                        performed via compiler APIs (e.g., javac API) are not
                        intercepted. Since Svace Java agent requires Java 1.6,
                        this option must be used if build process involves
                        Java 1.5 or older.
  --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).
  --max-jobs MAX_JOBS   The maximum number of processes that Svace can use to
                        handle intercepted compilation commands. For full
                        builds, it is supported only on Windows. If combined
                        with --update, it is supported on all platforms. The
                        default value is the number of logical processors on
                        the system.
  --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).
  --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
  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 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.
  --server              Enable server analysis mode. In this mode computed
                        function annotations and possibly other information
                        will be saved to disk to be used by the annotation
                        server for supporting the client fast analysis mode.
  --client              Enable fast analysis mode on the client desktop. In
                        this mode, the data required for the unknown functions
                        analysis will be queried from the annotation server.
  --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.
  --incremental         Enable incremental analysis mode. It implents the same
                        behavior as a --client option. However, the results of
                        analysis is almost the same as for full analysis.
                        Demand a project to have been analyzed with server
                        option yet.
  --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.

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 of the 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 different 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 malicous 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 of the 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.

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 casted 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 finds situations where a function conditionally dereferences a pointer, and this function is called with NULL assigned to that pointer.

Example (C/C++)

 void foo(int x, int* p) {
   if(x>7)
     return;
   *p = 3;
 }
 
 void main() {
   foo(30, NULL);
 }

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 casted 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.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 casted 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 warning finds situations where a pointer returned by a library function, such as fopen(), is dereferenced (accessed by other library functions) without being checked for NULL value.

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

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

The 'DEREF_OF_NULL.RET.LIB.PROC' subtype specifies that DEREF_OF_NULL.RET.LIB 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.

Example (Kotlin)

import java.io.File

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

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

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 'example' illustrates the 'DEREF_OF_NULL.RET.LIB' 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.

Function 'exampleProc' illustrates the 'DEREF_OF_NULL.RET.LIB.PROC' defect: call of 'listFiles' function may return null, which will be dereferenced by 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

This checker finds situations where a pointer returned by a user-written procedure that returns NULL on some of the 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 example(h: Helper): Int {
    val num = h.getMaybeNull()
    return num!!.times(3)
}

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

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

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

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

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

Function 'example' illustrates the 'DEREF_OF_NULL.RET' defect: 'num' may be null after 'getMaybeNull' call and it is dereferenced by call of 'times' function. Function 'possibleFix' illustrates a possible fix: use safe call of 'times' function.

Function 'exampleProc' illustrates the 'DEREF_OF_NULL.RET' inter-procedural defect: 'num' may be null after 'getMaybeNull' call and it is dereferenced by call of user defined function 'deref'. Function 'possibleFixProc' illustrates a possible fix: use safe implementation 'derefCorrect'. Safe call of 'times' is used inside 'derefCorrect' function.

See also

• UNCHECKED_FUNC_RES.STAT

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 a 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.

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.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.

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_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

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

   if(index<256) {      
     // index may still be negative!
     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_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.SPRINTF

This checker finds uses of library function sprintf() that may overflow the destination buffer, because some of the 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);
 }

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
 }

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_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

BUFFER_SIZE_MISMATCH

The checker BUFFER_SIZE_MISMATCH finds situations where a size parameter passed to "safe" versions of standard functions (such as strncpy or memset) is unsafe (out of local buffer bounds).

Example

 char dst[10];
 char src[11];

 void test() { 
   strncpy(dst, src, sizeof(src));
 }

The last parameter for strncpy() should've been sizeof(dst)-1.

BUFFER_SIZE_MISMATCH.STRICT

The checker BUFFER_SIZE_MISMATCH.STRICT finds situations where a size parameter passed to "safe" versions of standard functions (such as memset_s, sprintf_s) is not constant and may be out of bounds.

Example

 char dst[10];

 void test_bad(int size, char* src) { 
   memcpy_s(dst, size, src, strlen(src));
 }

 void test_good(char* src) { 
   memcpy_s(dst, 10, src, strlen(src));
 }

DYNAMIC_SIZE_MISMATCH.STRICT

The checker DYNAMIC_SIZE_MISMATCH.STRICT finds situations where a size parameter passed to "safe" versions of standard functions (such as memset_s, sprintf_s) is not constant and may be out of bounds. Unlike BUFFER_SIZE_MISMATCH.STRICT it emits warnings for buffer from heap.

Example

 void test_bad(int size, char* src) {
   char* dst = malloc(100); 
   memcpy_s(dst, size, src, strlen(src));
 }

 void test_good(char* src) { 
   char* dst = malloc(10);
   memcpy_s(dst, 10, src, strlen(src));
 }

DYNAMIC_SIZE_MISMATCH

The checker DYNAMIC_SIZE_MISMATCH finds situations where a size parameter passed to "safe" versions of standard functions (such as strncpy or memcpy) is unsafe (out of dynamic buffer bounds).

Example

 char *dst;
 char src[11];

 void test() {
   dst = (char *)malloc(10); 
   strncpy(dst, src, sizeof(src));
 }

The last parameter for strncpy() should've been sizeof(dst)-1.

ALLOC_SIZE_MISMATCH

This checker reports warnings for instances of pointer assigned memory allocations where the pointer's target type is larger than the block allocated.

Example

 struct Person {
   int age;
   char name[20];
 };

 struct Person *foo(void) {
   struct Person *ptr;
   ptr = (Person *)malloc(sizeof(ptr));  // mismatched allocation size
   return ptr;
 }

In this example, the allocation is too small for the pointer's target type – sizeof(*ptr) was probably intended.

ALLOC_SIZE_MISMATCH.NEW

This checker reports warnings for C++ allocations using operator new when direct initialization is used incorrectly instead of the dynamic array size specification.

Example

int *a = new int(10); // should be new int[10]

This allocates memory for a single integer and initializes it with value 10 instead of allocating memory for 10 integer numbers.

MEMSET_SIZE_MISMATCH

This checker reports the same issue as ALLOC_SIZE_MISMATCH but for memset and similar functions instead of allocations.

READLINK_OVERFLOW

This checker finds situations where function 'readlink' (from libc) is used incorrectly. Function 'readlink' returns -1 on error, or the number of bytes written in the buffer, but doesn't write terminating NULL, so that it may return value equal to buffer size.

Example

 char buf[128];

 void overflow() {
   int len = readlink("/mnt/modules/pass1", buf, sizeof(buf));
   if(len != -1) {
     //len may be = sizeof(buf) = 128
     buf[len] = 0; // emitted READLINK_OVERFLOW
   }
 }

NONTERMINATED_STRING

The checker NONTERMINATED_STRING finds situations where "safe" versions of standard functions working with C strings enable creation of nonterminated strings as a result.

Example

 char dst[10];
 char src[15];
 
 void cp_str() {
   strncpy(dst, src, sizeof(dst));
 }

Even though buffer overflow won't occur directly in this call, it may create a non-terminated string, which may lead to buffer overflow later, when the string is accessed again. For example, if src is a 10-character string, the call will copy all 10 characters in dst, but there is no space left for a null terminator.

See also

• NONTERMINATED_STRING.STRICT
• TAINTED.NONTERMINATED_STRING

TAINTED.NONTERMINATED_STRING

This checker finds situations where "safe" versions of standard functions working with C strings enable creation of non-nullterminated strings as a result of using length parameter coming from untrusted source.

 char dst[10];
 
 void cp_str() {
   char* src = getenv("qqq");
   strncpy(dst, src, sizeof(dst));
 }

NONTERMINATED_STRING.STRICT

This checker is similar to NONTERMINATED_STRING, but doesn't assume that destination memory is zero-filled. It is reported when copying a smaller string into a bigger buffer without adding a null terminator. This can lead to unintended addition of a suffix to the copied string or nonterminated string if the destination buffer wasn't null-terminated.

STRING_OVERFLOW

This checker finds situations where a call to a string copying function can lead to a buffer overflow if the source string is larger than the destination buffer.

Example

 char buf[100];

 void test1(char* param) {
   strcpy(buf, param);
 }

OVERFLOW_UNDER_CHECK.LEN

The checker finds situations of potential overflow where string length is used to check possible size of buffer.

Example

void example(char* q) {
    int len = strlen(q);

    if(len>0) {
        struct S*s = (struct S*)q;
        s->x = 1;//potential overflow if len < sizeof(struct S).
    }
}

Memory management

FREE_NONHEAP_MEMORY

This checker finds situation where a pointer to non-heap memory could be passed to a memory deallocation function.

Example

 int buf[5];
 int* ptr;

 void test(int cond) { 
   if(cond)
     ptr = (int*) malloc(10);
   else
     ptr = buf;
   ...
   free(ptr); // 'ptr' could reference non-heap array 'buf'
 }

FREE_OF_ARITHM

This checker finds situation where a pointer passed to a memory deallocation function was obtained as a result of an arithmetic operation. Though sometimes the correct address of the beginning of a memory allocation block could be reconstructed using arithmetic operations, this is potentially a serious problem.

Example

 void foo(int* ptr) {
   int* start = ptr-30;
   free(start);
 }

BAD_ALLOC_ARITHMETIC

It emits warnings for arithmetic operation on the results of heap allocation functions. This might be a common typo when a closing brace is mistakenly placed before a part of the arithmetic expression for allocation size calculation.

Example

 char *mystrcpy(char *str) {
  char *ret = malloc(strlen(str)) + 1;  // Typo
  for (; *str;) *ret++ = *str++;
  char *copy = ret;
  *copy = 0;
  return ret;
 } 

Suggested code

char *mystrcpy(char *str) {
  char *ret = malloc(strlen(str) + 1);  // Correct size allocation for the whole string and zero terminator
  for (; *str;) *ret++ = *str++;
  char *copy = ret;
  *copy = 0;
  return ret;
} 

FREE_OF_NULL

This checker finds situations where a NULL pointer is passed to the library function free(). While it is totally okay, the code is useless as in this case no operation is performed and it might mean a problem with the program logic.

Example 1

 void test(int z, char* x) {
   if(z==7) {
     x = NULL;
 
     free(x);
   }
 }

Example 2

 void test(int x, char* z) {
   if(z==NULL) {
     x = 7;
 
     free(z);
   }
 }

See also

• DEREF_OF_NULL

DEREF_AFTER_FREE

This checker finds situations where a memory location is accessed through a pointer that has just been deallocated.

Example

 void test(char* pval, char x) {
   free(pval);
   x = *pval;
 }

See also

• USE_AFTER_FREE

USE_AFTER_FREE

This checker finds situations where the value of a pointer to a memory location that has been deallocated, is accessed.

Example

 void after_free(char* pval, char* pval2) {
   free(pval);
   pval2 = pval + 2;
 }

Example

 char* foo(char* x) {
   free(x);
   return x;
 }

See also

• DEREF_AFTER_FREE
• PASSED_TO_PROC_AFTER_FREE.EX

USE_AFTER_FREE.REALLOC

Subtype of USE_AFTER_FREE for situations where a pointer is passed to the realloc function that invalidates it but the original pointer value is used afterwards.

Example

  void boo() {
    int *newp = (int *) realloc (p, SIZE);//'p' is released
    p[0] = 1;//use of 'p'
    free(newp);
  }

PASSED_TO_PROC_AFTER_FREE.EX

This checker finds situations where a pointer referencing deallocated memory is passed to a function.

Example

 void foo(char* p);

 void run(char* p) {
   free(p);
   foo(p);
 }

Here, pointer p passed to a call of foo references memory deallocated by function free. One way to fix this defect is to set the deallocated pointer to NULL:

 free(p);
 p = NULL;
 foo(p); // no warning

Example

 struct proc {
   char* mem;
   int a;
 };

 void foo(struct proc* p);

 void run(struct proc* p) {
   free(p->mem);
   foo(p); // p->mem is referenced by p
 }

See also

• USE_AFTER_FREE

DOUBLE_FREE.EX

This checker finds situations where a pointer referencing deallocated memory is deallocated again.

Example

 char* foo(char* x) {
   free(x);
   free(x);
 }

DANGLING_POINTER.STRICT

This checker is designed to detect dangling pointers and resources, i.e. such pointers and resources that can be available from the caller context after they have been freed or released inside of the callee.

Example

int naive_pop(struct list *l)
{
  if (l == NULL) {
    return 0;
  }
  int *p = l->ptr;
  int ret = *p;
  free(p); // No removing of the freed pointer from the list, it remains there as a
           // dangling pointer that could crash the program on its dereference
  return ret;
}

Example

 typedef struct _St {
   char *p1;
   char *p2;
 } St;

 void ex(St *s) {
   if (cond1()) {
     free(s->p1);
     s->p1 = NULL; // Correct: the deallocated pointer is cleared
     return;
   }

   if (cond2()) {
     free(s->p1);  // Potential defect: the deallocated pointer may be used outside of the function
     return;
   }
 }

DANGLING_POINTER.STAT

Statistical version of DANGLING_POINTER. Svace emits this subtype when for some cases externally accessible memory pointing to it is reassigned and for others it isn't.

INCORRECT_STRLEN

This checker detects possible mismatch when using function 'strlen' to determine the size of a newly allocated buffer based on the length of an existing string.

Example

 char* alloc_same_plus_1(char* str) {
   char* res = (char*)malloc(strlen(str+1)); // svace emits INCORRECT_STRLEN
   res[0] = '\0';
   return res;
 }

strlen(str+1) return value that is less than strlen(str). Programmer probably wanted to write (strlen(str) + 1) to allocate 1 byte more than the length of 'str'; also, 'str+1' skips NULL terminator if 'str' was empty, leading to undefined behavior.

MEMORY_LEAK

This checker detects memory leak situations, where memory was allocated, and then all references to that memory were lost.

Example 1

 void mem_leak() {
   char* ptr1 = (char*)malloc(10);
   ptr1 = 0; // memory is leaked here
 }

Example 2

 void mem_leak() {
   char* str = strdup("hello");
   str = "qqq"; // memory allocated by function strdup is leaked here
 }

BUFFER_OVERLAP

This checker reports cases of using of the same source and destination buffers in function calls where it is prohibited such as memcpy.

HANDLE_LEAK

This checker finds situations where a file descriptor, file handle or a socket descriptor are lost, because local variables that held their value went out of scope or were re-assigned.

Example (C/C++)

 void func1() {
   FILE* f = fopen("qqq.c", "w");
 }

 void func2() {
   FILE* f = fopen("qqq.c", "w");
   f = 0;
 }

In some cases it might be possible for the programmer to predict the value of a descriptor returned by a function that allocates it. For example, after closing standard descriptor 1, the next allocated descriptor will have value 1. In such cases, even if the returned value is not recorded, the predicted value can still be used to deallocate resources. For these situations, Svace emits warnings of subtype HANDLE_LEAK.STRICT.

Example (Java)

import java.io.File;
import java.io.IOException;
import java.io.ObjectOutputStream;
import java.io.FileOutputStream;

public class HandleLeakTest {
    public static void example(File f) {
        try (ObjectOutputStream output = new ObjectOutputStream(new FileOutputStream(f))) {
            output.writeObject("test");
        } catch (IOException ignored) { }
    }

    public static void possibleFix(File f) {
        try (FileOutputStream fs = new FileOutputStream(f); ObjectOutputStream output = new ObjectOutputStream(fs)) {
            output.writeObject("test");
        } catch (IOException ignored) { }
    }
}

Function 'example' illustrates the defect. The underlying 'FileOutputStream' is not declared in a variable. It will never be closed directly in the generated finally block, it will be closed only through the 'close' method of the wrapping 'ObjectOutputStream'. The problem is, that if an exception is thrown from the 'ObjectOutputStream' constructor, its 'close' method will not be called and therefore the underlying 'FileOutputStream' will not be closed. Function 'possibleFix' illustrates a possible fix: assign the result of 'FileOutputStream' in variable and use it to construct 'ObjectOutputStream'. Note that the result of 'FileInputStream' constructor call will be lost if 'IOException' happens but this exception is handled inside 'example method'. If exception goes out of the method scope, HANDLE_LEAK.EXCEPTION will be emitted.

Example (Kotlin)

fun example(bytes: ByteArray) {
    val stream = File("data.txt").inputStream()
    stream.read(bytes)
}

fun possibleFix(bytes: ByteArray) {
    File("data.txt").inputStream().use { it.read(bytes) }
}

Function 'example' illustrates the defect: file input stream was created for 'data.txt' but it wasn't closed properly. Function 'possibleFix' illustrates a possible fix: call 'use' function which executes the given block function on this resource and then closes it down correctly whether an exception is thrown or not.

HANDLE_LEAK.EXCEPTION

This checker finds situations where a file descriptor, file handle or a socket descriptor are lost because of exception, which went out of the function scope.

Example (Java)

import java.io.File;
import java.io.IOException;
import java.io.ObjectOutputStream;
import java.io.FileOutputStream;

public class HandleLeakTest {
    public static void example(File f) throws IOException {
        try (ObjectOutputStream output = new ObjectOutputStream(new FileOutputStream(f))) {
            output.writeObject("test");
        }
    }

    public static void possibleFix(File f) throws IOException {
        try (FileOutputStream fs = new FileOutputStream(f); ObjectOutputStream output = new ObjectOutputStream(fs)) {
            output.writeObject("test");
        }
    }
}

Function 'example' illustrates the defect. The underlying 'FileOutputStream' is not declared in a variable. It will never be closed directly in the generated finally block, it will be closed only through the 'close' method of the wrapping 'ObjectOutputStream'. The problem is, that if an exception is thrown from the 'ObjectOutputStream' constructor, its 'close' method will not be called and therefore the underlying 'FileOutputStream' will not be closed. Function 'possibleFix' illustrates a possible fix: assign the result of 'FileOutputStream' in variable and use it to construct 'ObjectOutputStream'. Note that the result of 'FileInputStream' constructor call will be lost if 'IOException' happens and this exception goes out of the method scope. If exception is handled, HANDLE_LEAK will be emitted.

Example (Kotlin)

import java.io.*
import java.lang.IllegalStateException
import java.util.zip.*

fun example(f: File, com: String) {
    try {
        val zip = ZipOutputStream(FileOutputStream(f))
        zip.putNextEntry(ZipEntry("putNextEntry may throw exception"))
        zip.close()
    } catch (ex: Exception) {
        throw IllegalStateException(ex.message)
    }
}

fun possibleFix(f: File, com: String) {
    ZipOutputStream(FileOutputStream(f)).use { zip ->
        zip.putNextEntry(ZipEntry("putNextEntry may throw exception"))
    }
}

Function 'example' illustrates the defect: file output stream was created for 'f' but it will not be closed if 'putNextEntry' call raises an exception. Function 'possibleFix' illustrates a possible fix: call 'use' function which executes the given block function on this resource and then closes it down correctly whether an exception is thrown or not.

HANDLE_LEAK.FRUGAL

This checker is a subtype of HANDLE_LEAK and it finds situations where a database is opened and hasn't been properly closed.

Example (Kotlin)

fun example(helper: SQLiteOpenHelper) {
    var db = helper.readableDatabase
    // queries ...
}

fun possibleFix(helper: SQLiteOpenHelper) {
    helper.readableDatabase.use {
        // queries ...
    }
}

Function 'example' illustrates the defect: database was opened but it wasn't closed properly. Function 'possibleFix' illustrates a possible fix: call 'use' function which executes the given block function on this resource and then closes it down correctly whether an exception is thrown or not.

DOUBLE_CLOSE

This checker finds situations where a closed file descriptor is closed again.

Example

 void foo() {
   FILE *f = fopen("bar", "w");
   /* ... */
   fclose(f);
   /* ... */
   if (error()) {
     fclose(f);
   }
 }

Example

 void dup_to_2(int fd) {
   close(2);//now 2 is available
   dup(fd); //2 will be used
 }

USE_AFTER_RELEASE

This checker finds situations where a file descriptor, file handle or a socket descriptor are closed and there is an attempt to read from or write to it.

Example (Kotlin)

fun example(fileName: String) {
        val buf = ByteArray(1024)
        val stream = FileInputStream(fileName)
        stream.read(buf)
        // ...
        stream.skip(10)
        stream.close()
        stream.read(buf)
}

fun possibleFix(fileName: String) {
        val buf = ByteArray(1024)
        FileInputStream(fileName).use {
                it.read(buf)
                // ...
                it.skip(10)
                it.read(buf)
        }
}

Function 'example' illustrates the defect: 'stream' was closed and then there was an attempt to read from it. Function 'possibleFix' illustrates a possible fix: handle streams with 'use' function call.

BAD_FREE.MS_COM

This Microsoft Windows-specific checker finds situations where a Microsoft COM object is explicitly deallocated. Instead it should be automatically deallocated using a Release method.

Infinite loop

This checker find situations where number of loop iteration may be infinite because of integer overflow.

INFINITE_LOOP.INT_OVERFLOW

Example 1

void example1() {
    unsigned char i;

    for(i=0;i<=250;i+=10) {//possible integer overflow, after i = 250
        bar();
    }
}

Example 2

void example2(unsigned len) {
     int i = 0;

    while (len > 0) {
        len -= 8; //overflow if len % 9 != 0
    }

INFINITE_LOOP.STRING

This checker finds situations where number of loop iteration may be more than it was intended. The loop is depended from value of string.

Example

void func(char * pos) {
    while (*pos != ' ') {
        pos++;
    }
}

INFINITE_LOOP.INT_OVERFLOW.ARRAY

Сhecker INFINITE_LOOP.INT_OVERFLOW.ARRAY find situations with integer overflow that may lead to infinite loop execution and related to buffer access.

Example

void with_tainted() {
    unsigned char x = 0;
    char* buf = getenv("HOME");

    while(buf[x]==' ') {
        ++x; //svace: emitted INFINITE_LOOP.INT_OVERFLOW.ARRAY
    }
}

Here if first 256 bytes of buffer 'buf' do not contains space ' ' the variable 'x' will overflow which lead to infinite loop.

The checker emits warnings only for tainted buffers (from external sources). For other buffer subtype INFINITE_LOOP.INT_OVERFLOW.ARRAY.STRICT is emitted.

Example

char buf[1000];

void foo() {
    unsigned char x = 0;

    while(buf[x]==' ') {
        ++x; 
    }
}

BUFFER_OVERFLOW.LOOP

Checker finds suspicious situations where loop execution is bounded only by array data.

Example:

char buf[10];

void example() {
    char x = 0;

    while(buf[x]==' ') {
        ++x; //BUFFER_OVERFLOW.LOOP
    }
}

Integer overflow

INTEGER_OVERFLOW

This checker finds arithmetic operations with integer overflows when the result of that arithmetic operation is too big or too small to be represented as a value of the operation's result type.

Example

void print_integer_overflow(void) {
  /* Result of the expression is -1073741827 instead of the expected 3221225469 for 32-bit integer type */
  printf("%d\n", (INT_MAX / 2) * 3);
}

NO_CAST.INTEGER_OVERFLOW

This checker finds situations where the value of an arithmetic expression might overflow before the result is widened to a larger data type.

Example

long mult(int x, int y) {
  return (x * y);
}
...
  z = mult(0x7FFFFFFF, 2); /* Expected 0xFFFFFFFE but result is -2 */
...

The multiplication above should be performed after widening the arguments:

long mult(int x, int y) {
  return ((long)x * (long)y);
}

TAINTED.INT_OVERFLOW

The checker finds situations where value from external source is used in arithmetic operation without checking its range. It potentially may lead to integer overflow.

Example (C/C++)

int add_to_str(const char *str) {
    int index = atoi(str);
    int res = index + 500; //potential integer overflow
    return res;
}

Example (Kotlin)

fun example(number: String): Int {
        val num = number.toInt()
        return num - 1
}       

fun possibleFix(number: String): Int {
        number.toIntOrNull()?.let {
                try {
                        return Math.subtractExact(it, 1)
                } catch (e: ArithmeticException) {
                        throw e
                }
        }
        throw IllegalStateException()
}

Function 'example' illustrates the defect: string 'number' is casted to integer which is used in arithmetic subtraction without checking its range. Function 'possibleFix' illustrates a possible fix: use 'Math' library when working with values which are potentially from external source. Also it's recommended to use safe 'toIntOrNull' instead 'toInt' function.

TAINTED.INT_OVERFLOW.TRUNC

The checker finds situations where value from external source is passed to variable with smaller type size.

Example

    unsigned i;
    scanf("%3x", &i);
    unsigned short h = i; //potential loss of higher bits

INT_OVERFLOW.TRUNC.UNDER_BITMASK

The checker finds situations where potential integer overflow is possible for result of bit-manipulation operations.

Example

void foo(unsigned short a);

#define INVERT_BYTES_16(X)  (             ( ((X) & 0xFF00) >> 8 )         |   ( ((X) & 0x00FF) << 8 )     )

void bar(unsigned short b) {
    foo(INVERT_BYTES_16(b) + 1);
}

INT_OVERFLOW.LIB

The checker detects cases where the subtraction is performed on an unsigned value which can be 0 (or small enough), and, therefore the subtraction result may underflow, and it is passed to a function as its sensitive unsigned integer data argument.

Example

void example(char* dst, char* str) {
    size_t len = strlen(str);
    memcpy(dst, str, len - 1);
}

Security errors

SENSITIVE_LEAK

The checker finds situations where sensitive data may be occur to logs or be visible.

Example

char *password = getpass();
printf(password); 

For the example above specification for getpass must be added:

char *getpass() {
    char *ret;
    sf_overwrite(&ret);
    sf_password_set(ret);
    return ret;
}

The checker may detect sensitive data by name of used variables (passwd,pwd,privkey and etc.).

Example

char *pwd = "123";
log(pwd); //leak

Option SENSITIVE_NAME_REGEX allows changing regexp for name.

HARDCODED_PASSWORD

Checker finds situations where hardcoded password is passed to functions manipulating with passwords.

Example

var pass = []byte("0123456789abcdef0123456789abcdef")

func main() {
    block,_ := aes.NewCipher(pass) /using of hardcoded password
}

COMMAND_INJECTION

This checker reports various cases of insecure usages of shell commands execution or dynamic libraries loading when attacker is able to influence the environment of the running application.

Example

  const char *command = "some_command";
  system(command);

In the example above if the attacker is able to modify the PATH environment variable where some_command is searched he may set it in such way that allows to run his own malicious application instead of the intended one. The problem can be fixed as follows:

  const char *command = "/path/to/some_command"; // specify absolute path to command
  system(command);

Concurrency

DEADLOCK

This checker finds code that may result in two or more threads are waiting for each other, holding locks needed for the other to resume execution.

Example (C/C++)

 pthread_mutex_t *a, *b;

 void thread1() {
   pthread_mutex_lock(a);
   pthread_mutex_lock(b);
   ...
 }

 void thread2() {
   pthread_mutex_lock(b);
   pthread_mutex_lock(a);
   ...
 }

Example (Java)

class DeadlockTest {
    private Object lock;

    public synchronized void direct() {
        synchronized(lock) {
            // ...
        }
    }

    public void reverse() {
        synchronized(lock) {
            synchronized(this) {
                // ...
            }
        }
    }
}

Example (Kotlin)

class DeadlockExample() {
    lateinit var l: Any

    @Synchronized
    fun direct(): Unit {
        synchronized(l) {
            // ...
        }
    }

    fun reverse(): Unit {
        synchronized(l) {
            synchronized(this) {
                // ...
            }
        }
    }

    /*
    fun reverseCorrect(): Unit {
        synchronized(this) {
            synchronized(l) {
                // ...
            }
        }
    }
    */
}

Functions 'direct' and 'reverse' illustrate the defect: if there are two thread working with the same instance of 'DeadlockExample' class, and one thread executing 'direct' function acquires 'this' lock and tries to acquire 'l' lock, while another thread executing 'reverse' function acquires 'l' lock and tries to acquire 'this' lock, then both threads will wait indefinitely for one of them to release the lock. Possible fix: use 'reverseCorrect' function instead of 'reverse'.

DOUBLE_LOCK

The checker DOUBLE_LOCK finds situations where a lock is acquired twice in succession by the same thread (without getting released).

Example

 void proc(pthread_mutex_t* mut, int x) {
   pthread_mutex_lock(mut);
   if(x)
     pthread_mutex_unlock(mut);
 
   pthread_mutex_lock(mut);   // DOUBLE_LOCK: pthread_mutex_unlock() might not have been called
   ...
   pthread_mutex_unlock(mut);
 }

NO_UNLOCK

This checker finds situations where a thread acquires a lock during function execution and leaves it locked on some paths to the exit from the function, but the function also unlocks it on some of the other paths.

Example

 void test(pthread_mutex_t* mut, int flag) {
   pthread_mutex_lock(mut);
   if(flag) {
     return; //mut isn't unlocked on this path
   }
   pthread_mutex_unlock(mut);
 }

LOCK_ON_STACK

This checker finds situations where a local variable allocated on stack is used as a synchronization primitive. Since each thread has its own stack such locks can't be used for inter-thread synchronization.

Simple example

 void foo() {
  pthread_mutex_t m;

  pthread_mutex_lock(&m); //locking stack variable
 }

More complex example

class AutoLock {
public:
    AutoLock(pthread_mutex_t *_m) {
        m = _m;
    }

    AutoLock() {}

    ~AutoLock() {
        pthread_mutex_unlock(m);
    }

    void lock() {
        pthread_mutex_lock(m);
    }
private:
    pthread_mutex_t *m;
};

pthread_mutex_t m_glob;//it should be used.

void bar() {
    AutoLock l;
    l.lock(); //Variable l is on stack. l.m is also on stack. 
}

LONG_TIME_IN_LOCK

This checker finds situations where a blocking function is called inside a critical section. As a result, all threads have to wait for the blocking function to return, not just the thread that called it.

Example

 int proc(pthread_mutex_t* mut, pthread_mutex_t* socket) {
   pthread_mutex_lock(mut);  // lock
   int res = accept(socket); // this function might take a lot of time
   pthread_mutex_unlock(mut);
   return res;
 }

ATOMICITY

This checker finds cases of non-atomic usage of non-constant shared data where critical section is not sufficient to protect a variable.

NO_LOCK.STAT

This detector collects statistics in a single file of variables reads and writes inside and outside of critical sections. Based on this statistical data it detects possible usages of variables outside of critical sections that may lead to data races.

NO_LOCK.STAT.EX

This detector collects statistics for each access to the field. Statistics store whether access to the field was under lock and under what lock in particular. By handling the statistics the detector decides if some accesses to field may cause race condition. Constructors and 'equals', 'hashCode' and 'clone' methods are excluded from consideration.

The warning will be emitted by this detector if:

• 'NO_LOCK.STAT.EX.THRESHOLD' percentage of accesses to a field are under the same lock
• two of three accesses to a field are under the same lock and 'NO_LOCK.STAT.EX.TWO_OF_THREE' configuration variable is true

'NO_LOCK.STAT.EX.THRESHOLD' is equal to 80% by default. 'NO_LOCK.STAT.EX.TWO_OF_THREE' is false by default.

Note that 'NO_LOCK.STAT.EX.TWO_OF_THREE' is true for all examples below.

Example (Java)

public class NoLockStatExample {
    private int a;
    private Object l = new Object();

    public Example() {
        a = 0; // ignore this access to field 'a' in constructor
    }

    public synchronized void bar() {
        a++; // access to field 'a' under 'this' lock
    }

    public void foo(int b) {
        synchronized(l) {
            a += b; // first access to field 'a' under 'l' lock
            a += 2; // second access to field 'a' under 'l' lock
        }
    }

    /*
    public void barCorrect() {
        synchronized(l) {
            a++; // access to field 'a' under 'this' lock
        }
    }
    */
}

Function 'bar' illustrates the defect: field 'a' is accessed under 'this' lock, while in most cases (2 of 3) this field is accessed under 'l' lock in 'foo' function. This situation may cause race condition. Possible fix: use 'barCorrect' function instead of 'bar', field 'a' is accessed under 'l' lock in 'barCorrect' function.

Example (Kotlin)

class NoLockStatExample {
    private var a: Int = 0
    lateinit var l: Any

    @Synchronized
    fun bar() {
        a++ // access to 'a' under 'this' lock
    }
    
    fun foo(b: Int) {
        synchronized(l) {
            a += b // access to 'a' under 'l' lock
            a += 2 // access to 'a' under 'l' lock
        }
    }
    
    /*
    fun barCorrect() {
        synchronized(l) {
           a++
        }
    }
    */
}

Function 'bar' illustrates the defect: property 'a' is accessed under 'this' lock, while in most cases (2 of 3) this property is accessed under 'l' lock in 'foo' function. This situation may cause race condition. Possible fix: use 'barCorrect' function instead of 'bar', property 'a' is accessed under 'l' lock in 'barCorrect' function.

RACE.NO_UMASK

Warning of this type is emitted where a call to function 'mkstemp' is not preceded by a call to 'umask', which is necessary to restrict access rights to the newly created file to its creator.

For most libc implementation function 'mkstemp' creates file with correct permissions and this warning is not needed.

See also

• RACE.BAD_UMASK

RACE.BAD_UMASK

Even if function 'umask' was called before 'mkstemp', as checked by RACE.NO_UMASK, it's possible that access rights set by 'umask' are too permissive (for example, 777). This warning is emitted if that is the case.

For most libc implementation function 'mkstemp' creates file with correct permissions and this warning is not needed.

See also

• RACE.NO_UMASK

Signal handlers

SIGHANDLER.ASYNC_UNSAFE

This checker finds possible cases of using inconsistent data while executing asynchronous-unsafe functions from signal handlers. According to Section 7.14.1.1 of the C Rationale [ISO/IEC 2003]:

When a signal occurs, the normal flow of control of a program is interrupted. If a signal occurs that is being trapped by a signal handler, that handler is invoked. When it is finished, execution continues at the point at which the signal occurred. This arrangement can cause problems if the signal handler invokes a library function that was being executed at the time of the signal.

The warning is emitted if signal handler calls any asynchronous-unsafe function. It is based on the ​SIG30-C rule from the CERT Secure Coding Standard.

Example

 char* info;

 void handler(int signum) {
   free(info); // free is an asynchronous unsafe function,
               // so the warning will be emitted here.
   info = NULL;
 }
 
 int main(void) {
   signal(SIGINT, handler); // register 'handler' as a handler
   //...skipped
   return 0;
 }

SIGHANDLER.SELF

This checker finds a rare case of race condition where a handler tries to reinstall a signal handler from itself. On systems that deinstall signal handler after signal delivery (SysV and Windows behavior) another signal can happen before the reinstallation code is run. This will lead to default signal handler call. On systems where signal handlers need to be explicitly deinstalled (BSD and Linux behavior), reinstallation of same signal handler doesn't make sense.

The warning is emitted if a signal handler calls function 'signal' for re-registering same handler again. It is based on the ​SIG34-C rule from the CERT Secure Coding Standard.

Example

 void handler(int signum) {
   signal(signum, handler); // call to 'signal' from within 'handler' to register
                            // 'handler' again; the warning is emitted here
 }
 
 int main(void) {
   signal(SIGINT, handler); // register 'handler' as a handler
   //...skipped
   return 0;
 }

SIGHANDLER.ACCESS_SHARED

This checker detects race conditions that can be caused by accessing or modifying shared objects in signal handlers. The only way to guarantee that data is read in consistent state and remains in consistent state after modification is to read and write only variables of type volatile sig_atomic_t inside of signal handlers.

The warning is emitted if signal handler accesses or modifies global data with the type other than volatile sig_atomic_t. It is based on the ​SIG31-C rule from the CERT Secure Coding Standard.

Example

 volatile sig_atomic_t iflag = 0;
 int kflag = 0;

 void int_handler(int signum) {
   iflag = 2; // all ok, iflag is volatile sig_atomic_t
 }

 void kill_handler(int signum) {
   kflag = 3; // the warning is emitted: modifying shared object 'kflag' in a signal handler
 }
 
 int main(void) {
   signal(SIGINT, int_handler); // handler is registered
   signal(SIGKILL, kill_handler); // handler is registered
   //...skipped
   return 0;
 }

SIGHANDLER.LONGJUMP

This checker finds situations where a 'longjmp' function is called from a signal handler, which may cause inconsistent data use. Such calls can lead to problems similar to those discussed in SIGHANDLER.ASYNC_UNSAFE.

The warning is emitted if the signal handler function calls the 'longjump' function. It is based on a ​SIG32-C rule from the CERT Secure Coding Standard.

Example

 static jmp_buf env;

 void handler(int signum) {
   longjmp(env, 1); // call to 'longjump' from a signal handler
 }
 
 int main(void) {
   signal(SIGINT, handler); // handler is registered
   //...skipped
   return 0;
 }

SIGHANDLER.REC_RAISE

This checker finds situations where undefined behavior may result from calling function 'raise' from a signal handler. According to C99, Section 7.14.1.1 [ISO/IEC 9899:1999]:

If the signal occurs as the result of calling the abort or raise function, the signal handler shall not call the raise function.

The warning is emitted if function 'raise' is called from a signal handler, but only if a signal with that handler is explicitly raised using functions 'raise' or 'abort' somewhere in the program. It is based on the ​SIG33-C rule from the CERT Secure Coding Standard.

Example

 void log_msg(int signum) {
   //...skipped
 }

 void handler(int signum) {
   raise(SIGUSR1); // handler for SIGINT recusively calls 'raise'
 }
 
 int main(void) {
   signal(SIGUSR1, log_msg); // handler is registered
   signal(SIGINT, handler); // handler is registered
   //...skipped

   raise(SIGINT); // 'raise' is explicitly called for SIGINT
   //...other code
   return 0;
 }

SIGHANDLER.NO_ABORT

This checker detects cases of undefined behavior caused by returning control from certain signal handlers that should instead terminate the program. According to Section 7.14.1.1 of the C standard, returning from SIGSEGV, SIGILL, or SIGFPE signal handlers leads to undefined behavior:

If and when the function returns, if the value of sig is SIGFPE, SIGILL, SIGSEGV, or any other implementation-defined value corresponding to a computational exception, the behavior is undefined; otherwise, the program will resume execution at the point it was interrupted.

The warning is emitted if signal handler for SIGFPE, SIGILL or SIGSEGV can return without calling the 'abort' function. It is based on the ​SIG35-C rule from the CERT Secure Coding Standard.

Example

 volatile sig_atomic_t flag;

 void handler(int signum) {
   flag = 1; // no call of 'abort'
 }
 
 int main(void) {
   signal(SIGILL, handler); // handler is registered
   //...skipped
   return 0;
 }

C++ warnings

Those warnings are developed special for C++ code.

UNINIT.CTOR

This checker finds constructors (incl. copy constructor) that fail to initialize some of their class's fields.

Example

 class MyData {
 public:
   MyData();
   int kind;
   char ch;
   int sum;
 };

 MyData::MyData() : ch('q') {
   this->kind = 7; // warning: field 'sum' is not initialized
 }

Notes

Code detected by this checker doesn't necessarily lead to reading of uninitialized memory, since fields that were not initialized in the constructor might be initialized later or never accessed without additional initialization.

UNINIT_HEAP.CCTOR

This checker finds classes in which the destructor explicitly deallocates memory using a pointer, but the copy constructor doesn't initialize this pointer or doesn't exist. Not handling such pointer in copy constructors may lead to either deallocation via an uninitialized pointer, or to double deallocation of the same memory.

Example

 class MyData {
   char* str;
   int size;
 public:
   MyData() {
     str = (char*)malloc(10);
     size = 10;
   }

   MyData(const MyData& a) {
     size = a.size; // 'str' is not handled
   }

   ~MyData() {
     free(str); // deallocate memory pointed to by 'str'
   }
 };

UNINIT_HEAP.ASSIGN_OP

This checker finds classes where the destructor deallocates memory using a pointer, but the assignment operator doesn't initialize this pointer or doesn't exist. This checker is similar to UNINIT_HEAP.CCTOR, but checks assignment operators instead of copy constructors.

METHOD_CALL_BEFORE_BASE_INIT

Check for undefined behavior related to the order of initializtion of base classes such as calling a member function when base is not initialized yet, dynamic_cast of this when base is not initialized yet and calling of typeid() with this as argument when base is not initialized yet.

Example

In the example below f() is a member function of class B. Constructor of class B has base initializer A(int a) and uses return value of method f() as an argument. The call f() would be evaluated before A initialization is complete which is undefined behavior.

class A {
  public:
    A(int a);
};

class B : public A {
  public:
    int f();
    B() : A(f()) {} 
};

HEAP_INCOMPATIBLE.FREE

Warnings of this type are emitted for situations where memory is deallocated in a way that is incompatible with how it was allocated. For example, usage of C functions malloc/free must not be mixed with C++ operators new/delete.

 char* buf = (char*)malloc(strlen(str) + 12);
 //...
 delete buf; // HEAP_INCOMPATIBLE.FREE is emitted here. The bug can be fixed 
             // by using function 'free' for deallocation instead of 'delete'.

See also

• HEAP_INCOMPATIBLE.ARRAY
• HEAP_INCOMPATIBLE.CTOR

HEAP_INCOMPATIBLE.ARRAY

A subtype of HEAP_INCOMPATIBLE.FREE. Detects situations where memory was allocated using array allocation operator 'new[]', but deallocated using operator 'delete' (instead of the correct 'delete[]'). Using incorrect deallocation method can lead to undefined behavior.

 char* buf = new char[SIZE_MAX];
 //...
 delete buf; // HEAP_INCOMPATIBLE.ARRAY warning is emitted here. The bug can be fixed by using delete[].

See also

• HEAP_INCOMPATIBLE.FREE

HEAP_INCOMPATIBLE.CTOR

This checker finds classes with a constructor that allocates memory using a function (operator) that is incompatible with the function used by the destructor for deallocation. Examples of incompatible function pairs: new/free, malloc/delete, new[]/delete, new/delete[].

Example

 class C {
   int* buf;
 public:
   C() {
     buf = new int[10];
   }

   ~C() {
     free(buf);//here svace fires the warning.
   }
 };

See also

• HEAP_INCOMPATIBLE.FREE

MEMORY_LEAK.CTOR

This checker finds classes with a constructor that explicitly allocates memory, but which isn't deallocated in the destructor.

Example

 class C1 {
   int* buf;
 public:
   C1() { buf = new int[10]; }
   ~C1();
 };

 C1::~C1() { // warning: missing delete[] for buf
 }

DEAD_STRING_REF

This warning is emitted when an internal string buffer (returned by c_str()) of an STL string escapes its scope.

Example

 int func() {
   const char* p;
   {
     std::string s("Hello");
     p = s.c_str();
   } // scope of 's' ends, destructor is invoked
  
   // memory referenced by 'p' is no longer valid here
   return *p; // emit DEAD_STRING_REF
 }

ASSIGN_OP.NO_CHECK_FOR_THIS

Finds implementations of 'operator=' that fail to check their argument for equality to 'this' (which is necessary to correctly handle statements such as 'x=x;').

Example

class MyData {
 public:
   MyData& operator=(const MyData& a);
 private:
   int pkind;
 };

 MyData& MyData::operator=(const MyData& a) {
   this->pkind = a.pkind; // warning: 'a' wasn't checked for equality to 'this'
   return *this;
 }

The problem can be fixed as follows:

 MyData& MyData::operator=(const MyData& a) {
   if(&a == this)
     return *this;
   this->pkind = a.pkind; // no warning
   return *this;
 }

False positives

There are possible false positives if implicit checking is present in field copy operations.

ASSIGN_OP.NO_REFERENCE_TO_THIS

Correctly written assignment operator (operator=) should return a reference to '*this', so that code like 'a = b = c;' is legal. This checker finds situations where the assignment operator doesn't have a return type or returns wrong value.

Example 1

 class MyData {
 public:
   void operator=(const MyData& a);
 private:
   int kind;
 };

 void MyData::operator=(const MyData& a) { 
   this->kind = a.kind; // return type is void, instead of MyData&
 }

Example 2

 class Base {
 public:
   Base& operator=(const Base& a);
 private:
   Base* ptr;
 };

 Base& Base::operator=(const Base& a) {
   return *this->ptr; // return type is correct, but 'operator=' 
                      // doesn't return reference to 'this'.
 }

Example 3

 class Base {
 public:
   Base& operator=(const Base& a);
 private:
   int ptr;
 };
 
 Base& Base::operator=(const Base& a) {
   this->ptr = a.ptr;
   return *this; // correct, no warning.
 }

MISSING_COPY_CTOR_ASSIGN_OP

A class has dynamically allocated data members but does not define a copy constructor or an assignment operator. In this case, whenever an object is copied by value, dynamically allocated members will be destroyed as soon as at least one of the copies is deleted, and other copies would maintain and possibly dereference a stale pointer.

Example

In the code below, the following sequence of events leads to a dereference of a dead pointer:

• The object of the class is copied via the standard copy constructor;
• Destroy the object b and thus free memory pointed by both b.p and a.p with explicitly defined destructor;
• Try to access *(a.p) and dereference a pointer to a destructed object.

class C {
  int *p;

public:
  C() { p = new int; }
  ~C() { delete p; }
  void setVal(int x) { *p = x; }
  int getVal() const { return *p; }
};

THROW_WHILE_COPY

Checks for exception throwing in copy constructor/assignment operator which can lead to resource leaks or undefined behavior.

Example

In the following example if exception std::bad_alloc is thrown then some of the Bundle::KeyInfo class fields such as impl_->name_ are initialized while some such as impl_->own_ aren't. This leads to the assigned object being partially initialized and having an indeterminate state.

Bundle::KeyInfo& Bundle::KeyInfo::operator = (const Bundle::KeyInfo& k) {
  if (this != &k) {
    if (impl_->handle_ && impl_->own_)
      bundle_keyval_free(const_cast<bundle_keyval_t*>(impl_->handle_));
    impl_->handle_ = bundle_keyval_dup(k.impl_->handle_);
    impl_->name_ = k.impl_->name_;
    if (impl_->handle_ == nullptr)
      throw std::bad_alloc();
    impl_->own_ = true;
  }
  return *this;
}

BAD_ITERATOR.INVALID

This checker finds situations where STL iterators are used after being invalidated.

Example

using namespace std;
int last(vector<int>& v) {
  vector<int>::iterator it = v.begin();
  while(it != v.end())
    ++it;
  return (*it);
}

BAD_ITERATOR.MISMATCHED

This checker finds situations where STL iterators are used for a different container.

Example

using namespace std;
bool same(vector<int>& v1, vector<int>& v2) {
  vector<int>::iterator it = v1.begin();
  vector<int>::iterator it2 = v2.begin();
  return it == it2;
}

USE_AFTER_MOVE

The checker finds situations where an object is used after it was moved. Moved-from objects are usually left in unspecified state. Usage of such objects leads to unspecified behavior.

Example

std::string a = "Hello world";
std::string b = std::move(a);      // moved value from a. a is in unspecified state.
std::cout << a[0];                 // usage of a. USE_AFTER_MOVE emitted.

Moved-from object can be reinitialized and used again.

Example

std::vector<int> a = {1, 2, 3, 4};
std::vector<int> b(std::move(a));  // move from a
a.clear();                         // a is reinitialized
std::cout << a.size();             // USE_AFTER_MOVE is NOT emitted.

C# warning types

API.CSHARP.CULTURE

The result of a function call may differ depending on the current culture. Specify culture explicitly to choose the desired behavior.

Example

float theirVersion = 0f;
if (parts.Length > 1)
    theirVersion = float.Parse(parts[1]);

Fix (use invariant culture)

float theirVersion = 0f;
if (parts.Length > 1)
    theirVersion = float.Parse(parts[1], NumberStyles.Float, CultureInfo.InvariantCulture);

CAST_AFTER_CHECK

The variable was checked for compatibility with given type (which means that it may be incompatible with it by contract) and then casted to it without check.

Example 1

Here && is used instead of ||, so the cast will always fail.

if (!(task.Result is ResultResponse) &&
    !(((ResultResponse)task.Result).Output is OutputRows))
{
    throw new DriverInternalError("Expected rows " + task.Result);
}

Example 2

Here || is used instead of &&, so the cast will fail if request["Values"] is List<string>, but request["Names"] is not.

if (!(request["Names"] is List<string> || request["Values"] is List<string>))
    return FailureResult();

RemoveRequestParamsNotForStorage(request);
List<string> _names = (List<string>)request["Names"];

CODE_INJECTION

User input is used as code (e. g. compiled or evaluated) or as path to code.

CONDITIONAL_ASSIGN

An assignment operator (=) is used inside of condition expression. It is probably a typo for equality operator (==).

Although using = inside of condition is not necessarily a bug, this warning is useful for immediate bug fixing during coding.

Example

if (a = b || a == c) 
{
}

CONNSTR_INJECTION

User input is concatenated to database connection string, which allows the attacker to override connection parameters. DbConnectionStringBuilder should be used to create the connection string.

CROSS_SITE_REDIRECT