From 8954142b7fcc6ca952e6423c89bad58b4f526933 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Endre=20F=C3=BCl=C3=B6p?= Date: Mon, 29 Nov 2021 10:37:05 +0100 Subject: [PATCH] [analyzer][doc] Add taint analysis documentation (#3522) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/analyzer/user_guide.md | 39 +++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/analyzer/user_guide.md b/docs/analyzer/user_guide.md index 4eaecbd929..84c855f335 100644 --- a/docs/analyzer/user_guide.md +++ b/docs/analyzer/user_guide.md @@ -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) @@ -1541,6 +1542,44 @@ cross translation unit analysis arguments: analysis. (default: parse-on-demand) ``` +### Taint analysis configuration + +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 If the `clang` static analyzer binary in your installation supports