clang/docs/analyzer/user-docs/TaintAnalysisConfiguration.rst

   1 ============================
   2 Taint Analysis Configuration
   3 ============================
   4
   5 The Clang Static Analyzer uses taint analysis to detect injection vulnerability related issues in code.
   6 The backbone of taint analysis in the Clang SA is the ``TaintPropagation`` modeling checker.
   7 The reports are emitted via the :ref:`optin-taint-GenericTaint` checker.
   8 The ``TaintPropagation`` checker has a default taint-related configuration.
   9 The built-in default settings are defined in code, and they are always in effect.
  10 The checker also provides a configuration interface for extending the default settings via the ``optin.taint.TaintPropagation:Config`` checker config parameter
  11 by providing a configuration file to the in `YAML <http://llvm.org/docs/YamlIO.html#introduction-to-yaml>`_ format.
  12 This documentation describes the syntax of the configuration file and gives the informal semantics of the configuration options.
  13
  14 .. contents::
  15    :local:
  16
  17 .. _clangsa-taint-configuration-overview:
  18
  19 Overview
  20 ________
  21
  22 Taint analysis works by checking for the occurrence of special operations during the symbolic execution of the program.
  23 Taint analysis defines sources, sinks, and propagation rules. It identifies errors by detecting a flow of information that originates from a taint source, reaches a taint sink, and propagates through the program paths via propagation rules.
  24 A source, sink, or an operation that propagates taint is mainly domain-specific knowledge, but there are some built-in defaults provided by the ``TaintPropagation`` checker.
  25 It is possible to express that a statement sanitizes tainted values by providing a ``Filters`` section in the external configuration (see :ref:`clangsa-taint-configuration-example` and :ref:`clangsa-taint-filter-details`).
  26 There are no default filters defined in the built-in settings.
  27 The checker's documentation also specifies how to provide a custom taint configuration with command-line options.
  28
  29 .. _clangsa-taint-configuration-example:
  30
  31 Example configuration file
  32 __________________________
  33
  34 .. code-block:: yaml
  35
  36   # The entries that specify arguments use 0-based indexing when specifying
  37   # input arguments, and -1 is used to denote the return value.
  38
  39   Filters:
  40     # Filter functions
  41     # Taint is sanitized when tainted variables are pass arguments to filters.
  42
  43     # Filter function
  44     #   void cleanse_first_arg(int* arg)
  45     #
  46     # Result example:
  47     #   int x; // x is tainted
  48     #   cleanse_first_arg(&x); // x is not tainted after the call
  49     - Name: cleanse_first_arg
  50       Args: [0]
  51
  52   Propagations:
  53     # Source functions
  54     # The omission of SrcArgs key indicates unconditional taint propagation,
  55     # which is conceptually what a source does.
  56
  57     # Source function
  58     #   size_t fread(void *ptr, size_t size, size_t nmemb, FILE * stream)
  59     #
  60     # Result example:
  61     #   FILE* f = fopen("file.txt");
  62     #   char buf[1024];
  63     #   size_t read = fread(buf, sizeof(buf[0]), sizeof(buf)/sizeof(buf[0]), f);
  64     #   // both read and buf are tainted
  65     - Name: fread
  66       DstArgs: [0, -1]
  67
  68     # Propagation functions
  69     # The presence of SrcArgs key indicates conditional taint propagation,
  70     # which is conceptually what a propagator does.
  71
  72     # Propagation function
  73     #   char *dirname(char *path)
  74     #
  75     # Result example:
  76     #   char* path = read_path();
  77     #   char* dir = dirname(path);
  78     #   // dir is tainted if path was tainted
  79     - Name: dirname
  80       SrcArgs: [0]
  81       DstArgs: [-1]
  82
  83   Sinks:
  84     # Sink functions
  85     # If taint reaches any of the arguments specified, a warning is emitted.
  86
  87     # Sink function
  88     #   int system(const char* command)
  89     #
  90     # Result example:
  91     #   const char* command = read_command();
  92     #   system(command); // emit diagnostic if command is tainted
  93     - Name: system
  94       Args: [0]
  95
  96 In the example file above, the entries under the `Propagation` key implement the conceptual sources and propagations, and sinks have their dedicated `Sinks` key.
  97 The user can define operations (function calls) where the tainted values should be cleansed by listing entries under the `Filters` key.
  98 Filters model the sanitization of values done by the programmer, and providing these is key to avoiding false-positive findings.
  99
 100 Configuration file syntax and semantics
 101 _______________________________________
 102
 103 The configuration file should have valid `YAML <http://llvm.org/docs/YamlIO.html#introduction-to-yaml>`_ syntax.
 104
 105 The configuration file can have the following top-level keys:
 106  - Filters
 107  - Propagations
 108  - Sinks
 109
 110 Under the `Filters` key, the user can specify a list of operations that remove taint (see :ref:`clangsa-taint-filter-details` for details).
 111
 112 Under the `Propagations` key, the user can specify a list of operations that introduce and propagate taint (see :ref:`clangsa-taint-propagation-details` for details).
 113 The user can mark taint sources with a `SrcArgs` key in the `Propagation` key, while propagations have none.
 114 The lack of the `SrcArgs` key means unconditional propagation, which is how sources are modeled.
 115 The semantics of propagations are such, that if any of the source arguments are tainted (specified by indexes in `SrcArgs`) then all of the destination arguments (specified by indexes in `DstArgs`) also become tainted.
 116
 117 Under the `Sinks` key, the user can specify a list of operations where the checker should emit a bug report if tainted data reaches it (see :ref:`clangsa-taint-sink-details` for details).
 118
 119 .. _clangsa-taint-filter-details:
 120
 121 Filter syntax and semantics
 122 ###########################
 123
 124 An entry under `Filters` is a `YAML <http://llvm.org/docs/YamlIO.html#introduction-to-yaml>`_ object with the following mandatory keys:
 125  - `Name` is a string that specifies the name of a function.
 126    Encountering this function during symbolic execution the checker will sanitize taint from the memory region referred to by the given arguments or return a sanitized value.
 127  - `Args` is a list of numbers in the range of ``[-1..int_max]``.
 128    It indicates the indexes of arguments in the function call.
 129    The number ``-1`` signifies the return value; other numbers identify call arguments.
 130    The values of these arguments are considered clean after the function call.
 131
 132 The following keys are optional:
 133  - `Scope` is a string that specifies the prefix of the function's name in its fully qualified name. This option restricts the set of matching function calls. It can encode not only namespaces but struct/class names as well to match member functions.
 134
 135  .. _clangsa-taint-propagation-details:
 136
 137 Propagation syntax and semantics
 138 ################################
 139
 140 An entry under `Propagation` is a `YAML <http://llvm.org/docs/YamlIO.html#introduction-to-yaml>`_ object with the following mandatory keys:
 141  - `Name` is a string that specifies the name of a function.
 142    Encountering this function during symbolic execution propagate taint from one or more arguments to other arguments and possibly the return value.
 143    It helps model the taint-related behavior of functions that are not analyzable otherwise.
 144
 145 The following keys are optional:
 146  - `Scope` is a string that specifies the prefix of the function's name in its fully qualified name. This option restricts the set of matching function calls.
 147  - `SrcArgs` is a list of numbers in the range of ``[0..int_max]`` that indicates the indexes of arguments in the function call.
 148    Taint-propagation considers the values of these arguments during the evaluation of the function call.
 149    If any `SrcArgs` arguments are tainted, the checker will consider all `DstArgs` arguments tainted after the call.
 150  - `DstArgs` is a list of numbers in the range of ``[-1..int_max]`` that indicates the indexes of arguments in the function call.
 151    The number ``-1`` specifies the return value of the function.
 152    If any `SrcArgs` arguments are tainted, the checker will consider all `DstArgs` arguments tainted after the call.
 153  - `VariadicType` is a string that can be one of ``None``, ``Dst``, ``Src``.
 154    It is used in conjunction with `VariadicIndex` to specify arguments inside a variadic argument.
 155    The value of ``Src`` will treat every call site argument that is part of a variadic argument list as a source concerning propagation rules (as if specified by `SrcArg`).
 156    The value of ``Dst`` will treat every call site argument that is part of a variadic argument list a destination concerning propagation rules.
 157    The value of ``None`` will not consider the arguments that are part of a variadic argument list (this option is redundant but can be used to temporarily switch off handling of a particular variadic argument option without removing the VariadicIndex key).
 158  - `VariadicIndex` is a number in the range of ``[0..int_max]``. It indicates the starting index of the variadic argument in the signature of the function.
 159
 160
 161 .. _clangsa-taint-sink-details:
 162
 163 Sink syntax and semantics
 164 #########################
 165
 166 An entry under `Sinks` is a `YAML <http://llvm.org/docs/YamlIO.html#introduction-to-yaml>`_ object with the following mandatory keys:
 167  - `Name` is a string that specifies the name of a function.
 168    Encountering this function during symbolic execution will emit a taint-related diagnostic if any of the arguments specified with `Args` are tainted at the call site.
 169  - `Args` is a list of numbers in the range of ``[0..int_max]`` that indicates the indexes of arguments in the function call.
 170    The checker reports an error if any of the specified arguments are tainted.
 171
 172 The following keys are optional:
 173  - `Scope` is a string that specifies the prefix of the function's name in its fully qualified name. This option restricts the set of matching function calls.