Skip to content

Commit

Permalink
[analyzer][doc] Add taint analysis documentation (#3522)
Browse files Browse the repository at this point in the history
Clang SA uses taint analysis to detect bugs and security issues in code.
This change documents basic taint analysis usage and how to configure the
checker implementing the analysis.

Co-authored-by: Márton Csordás <csordasmarton92@gmail.com>
  • Loading branch information
gamesh411 and csordasmarton authored Nov 29, 2021
1 parent 198ab83 commit eca941c
Showing 1 changed file with 39 additions and 0 deletions.
39 changes: 39 additions & 0 deletions docs/analyzer/user_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ Table of Contents
* [`--enable-all`](#enable-all)
* [Toggling compiler warnings](#toggling-warnings)
* [Cross Translation Unit (CTU) analysis mode](#ctu)
* [Taint analysis configuration](#taint)
* [Statistical analysis mode](#statistical)
* [`parse`](#parse)
* [Exporting source code suppression to suppress file](#suppress-file)
Expand Down Expand Up @@ -1541,6 +1542,44 @@ cross translation unit analysis arguments:
analysis. (default: parse-on-demand)
```

### Taint analysis configuration <a name="taint"></a>

Taint analysis is used to detect bugs and potential security-related errors
caused by untrusted data sources.
An untrusted data source is usually an IO operation in code, often related to
the file-system, database, network, or environment variables.
Taint analysis works by defining operations that introduce tainted values
(`sources`), operations that cause taint to spread from tainted values
(`propagators`), and operations that are sensitive to tainted values (`sinks`).
Developers can also use an additional category of `filters` to express that some
operations sanitize tainted values, and after sanitization,
the value is trusted and safe to use.

Taint analysis can be used with the default configuration by enabling the
`alpha.security.taint.TaintPropagation` checker:
```sh
CodeChecker analyze -e alpha.security.taint.TaintPropagation
```

Taint analysis can be used with custom configuration by specifying the taint
configuration file as a checker-option in addition to enabling the
`alpha.security.taint.TaintPropagation` checker:
```sh
CodeChecer analyze \
-e alpha.security.taint.TaintPropagation \
--checker-config 'alpha.security.taint.TaintPropagation:Config=my-cutom-taint-config.yaml'
```

Taint analysis false positives can be handled by either using the warning
suppression via comments in the code (same as with other CodeChecker reports),
or by providing filter operations via a custom configuration file.

The default configuration options of taint analysis are documented in the
[checker's documentation](https://clang.llvm.org/docs/analyzer/checkers.html#alpha-security-taint-taintpropagation-c-c).

Clang SA's conceptual model of taint analysis and the checker's configuration
file format is documented in the [Taint Analysis Configuration docs](https://clang.llvm.org/docs/analyzer/user-docs/TaintAnalysisConfiguration.html).

### Statistical analysis mode <a name="statistical"></a>

If the `clang` static analyzer binary in your installation supports
Expand Down

0 comments on commit eca941c

Please sign in to comment.