gamesh411 updated this revision to Diff 388132.
gamesh411 added a comment.
Fix the review comments of @steakhal
Repository:
rG LLVM Github Monorepo
CHANGES SINCE LAST ACTION
https://reviews.llvm.org/D113251/new/
https://reviews.llvm.org/D113251
Files:
clang/docs/analyzer/checkers.rst
clang/docs/analyzer/user-docs/TaintAnalysisConfiguration.rst
Index: clang/docs/analyzer/user-docs/TaintAnalysisConfiguration.rst
===================================================================
--- clang/docs/analyzer/user-docs/TaintAnalysisConfiguration.rst
+++ clang/docs/analyzer/user-docs/TaintAnalysisConfiguration.rst
@@ -15,9 +15,9 @@
Overview
________
-Taint analysis works by checking for the occurrence of special events during the symbolic execution of the program.
-Taint analysis defines sources, sinks, and propagation rules. It identifies errors by detecting a flow of information that originates in a taint source, touches a taint sink, and propagates through the program paths via propagation rules.
-A source, sink, or an event that propagates taint is mainly domain-specific knowledge, but there are some built-in defaults provided by :ref:`alpha-security-taint-TaintPropagation`.
+Taint analysis works by checking for the occurrence of special operations during the symbolic execution of the program.
+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.
+A source, sink, or an operation that propagates taint is mainly domain-specific knowledge, but there are some built-in defaults provided by :ref:`alpha-security-taint-TaintPropagation`.
The checker's documentation also specifies how to provide a custom taint configuration with command-line options.
.. _taint-configuration-example:
@@ -39,6 +39,8 @@
Propagations:
# sources:
+ # The omission of SrcArgs key indicates unconditional taint propagation,
+ # which is conceptually what a source does.
# signature:
# size_t fread(void *ptr, size_t size, size_t nmemb, FILE * stream)
#
@@ -46,11 +48,13 @@
# FILE* f = fopen("file.txt");
# char buf[1024];
# size_t read = fread(buf, sizeof(buf[0]), sizeof(buf)/sizeof(buf[0]), f);
- # // read and buf is tainted
+ # // both read and buf are tainted
- Name: fread
DstArgs: [0, -1]
# propagations:
+ # The presence of SrcArgs key indicates conditional taint propagation,
+ # which is conceptually what a propagator does.
# signature:
# char *dirname(char *path)
#
@@ -73,7 +77,7 @@
Args: [0]
In the example file above, the entries under the `Propagation` key implement the conceptual sources and propagations, and sinks have their dedicated `Sinks` key.
-The user can define program points where the tainted values should be cleansed by listing entries under the `Filters` key.
+The user can define operations (function calls) where the tainted values should be cleansed by listing entries under the `Filters` key.
Filters model the sanitization of values done by the programmer, and providing these is key to avoiding false-positive findings.
Configuration file syntax and semantics
@@ -86,50 +90,54 @@
- Propagations
- Sinks
-Under the `Filters` entry, the user can specify a list of events that remove taint (see :ref:`taint-filter-details` for details).
+Under the `Filters` key, the user can specify a list of operations that remove taint (see :ref:`taint-filter-details` for details).
-Under the `Propagations` entry, the user can specify a list of events that generate and propagate taint (see :ref:`taint-propagation-details` for details).
-The user can identify taint sources with a `SrcArgs` key in the `Propagation` entry, while propagations have none.
+Under the `Propagations` key, the user can specify a list of operations that introduce and propagate taint (see :ref:`taint-propagation-details` for details).
+The user can mark taint sources with a `SrcArgs` key in the `Propagation` key, while propagations have none.
+The lack of the `SrcArgs` key means unconditional propagation, which is how sources are modeled.
+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.
-Under the `Sinks` entry, the user can specify a list of events where the checker should emit a bug report if taint reaches there (see :ref:`taint-sink-details` for details).
+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:`taint-sink-details` for details).
.. _taint-filter-details:
Filter syntax and semantics
###########################
+
An entry under `Filters` is a `YAML <https://yaml.org/>`_ object with the following mandatory keys:
- `Name` is a string that specifies the name of a function.
- Encountering this function during symbolic execution will clean taint on some parameters or the return value.
+ 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.
- `Args` is a list of numbers in the range of [-1..int_max].
- It indicates the indexes of arguments in the function call event.
+ It indicates the indexes of arguments in the function call.
The number -1 signifies the return value; other numbers identify call arguments.
The values of these arguments are considered clean after the function call.
The following keys are optional:
- - `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.
+ - `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.
.. _taint-propagation-details:
Propagation syntax and semantics
################################
+
An entry under `Propagation` is a `YAML <https://yaml.org/>`_ object with the following mandatory keys:
- `Name` is a string that specifies the name of a function.
- Encountering this function during symbolic execution propagate taint from one or more parameters to other parameters and possibly the return value.
+ Encountering this function during symbolic execution propagate taint from one or more arguments to other arguments and possibly the return value.
It helps model the taint-related behavior of functions that are not analyzable otherwise.
The following keys are optional:
- `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.
- - `SrcArgs` is a list of numbers in the range of [0..int_max] that indicates the indexes of arguments in the function call event.
+ - `SrcArgs` is a list of numbers in the range of [0..int_max] that indicates the indexes of arguments in the function call.
Taint-propagation considers the values of these arguments during the evaluation of the function call.
If any `SrcArgs` arguments are tainted, the checker will consider all `DstArgs` arguments tainted after the call.
- - `DstArgs` is a list of numbers in the range of [-1..int_max] that indicates the indexes of arguments in the function call event.
+ - `DstArgs` is a list of numbers in the range of [-1..int_max] that indicates the indexes of arguments in the function call.
The number -1 specifies the return value of the function.
If any `SrcArgs` arguments are tainted, the checker will consider all `DstArgs` arguments tainted after the call.
- `VariadicType` is a string that can be one of ``None``, ``Dst``, ``Src``.
It is used in conjunction with `VariadicIndex` to specify arguments inside a variadic argument.
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`).
The value of ``Dst`` will treat every call site argument that is part of a variadic argument list a destination concerning propagation rules.
- 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 entire variadic entry).
+ 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).
- `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.
@@ -141,7 +149,7 @@
An entry under `Sinks` is a `YAML <https://yaml.org/>`_ object with the following mandatory keys:
- `Name` is a string that specifies the name of a function.
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.
- - `Args` is a list of numbers in the range of [0..int_max] that indicates the indexes of arguments in the function call event.
+ - `Args` is a list of numbers in the range of [0..int_max] that indicates the indexes of arguments in the function call.
The checker reports an error if any of the specified arguments are tainted.
The following keys are optional:
Index: clang/docs/analyzer/checkers.rst
===================================================================
--- clang/docs/analyzer/checkers.rst
+++ clang/docs/analyzer/checkers.rst
@@ -2340,23 +2340,19 @@
// warn: untrusted data as buffer size
}
-Default sources defined by `GenericTaintChecker`:
+Default sources defined by ``GenericTaintChecker``:
``fdopen``, ``fopen``, ``freopen``, ``getch``, ``getchar``, ``getchar_unlocked``, ``gets``, ``scanf``, ``socket``, ``wgetch``
-Default propagations defined by `GenericTaintChecker`:
+Default propagations defined by ``GenericTaintChecker``:
``atoi``, ``atol``, ``atoll``, ``fgetc``, ``fgetln``, ``fgets``, ``fscanf``, ``sscanf``, ``getc``, ``getc_unlocked``, ``getdelim``, ``getline``, ``getw``, ``pread``, ``read``, ``strchr``, ``strrchr``, ``tolower``, ``toupper``
-Default sinks defined in `GenericTaintChecker`:
+Default sinks defined in ``GenericTaintChecker``:
``printf``, ``setproctitle``, ``system``, ``popen``, ``execl``, ``execle``, ``execlp``, ``execv``, ``execvp``, ``execvP``, ``execve``, ``dlopen``, ``memcpy``, ``memmove``, ``strncpy``, ``strndup``, ``malloc``, ``calloc``, ``alloca``, ``memccpy``, ``realloc``, ``bcopy``
The user can configure taint sources, sinks, and propagation rules by providing a configuration file via checker option ``alpha.security.taint.TaintPropagation:Config``.
-.. code-block:: sh
-
- clang --analyze ... -Xclang -analyzer-config -Xclang alpha.security.taint.TaintPropagation:Config=taint_config.yaml
-
External taint configuration is in `YAML <https://yaml.org/>`_ format. The taint-related options defined in the config file extend but do not override the built-in sources, rules, sinks.
-
+The format of the external taint configuration file is not stable, and could change without any notice even in a non-backward compatible way.
For a more detailed description of configuration options, please see the :doc:`user-docs/TaintAnalysisConfiguration`. For an example see :ref:`taint-configuration-example`.
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
