mirror of
https://github.com/hohn/codeql-info.git
synced 2025-12-16 20:53:04 +01:00
554 lines
43 KiB
HTML
554 lines
43 KiB
HTML
<!DOCTYPE html>
|
|
|
|
<html lang="en" data-content_root="../">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
|
|
<title>Analyzing data flow in Python — CodeQL</title>
|
|
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
|
|
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=93459777" />
|
|
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
|
|
<script src="../_static/doctools.js?v=888ff710"></script>
|
|
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
|
<link rel="icon" href="../_static/favicon.ico"/>
|
|
<link rel="index" title="Index" href="../genindex.html" />
|
|
<link rel="search" title="Search" href="../search.html" />
|
|
<link rel="next" title="Using API graphs in Python" href="using-api-graphs-in-python.html" />
|
|
<link rel="prev" title="CodeQL library for Python" href="codeql-library-for-python.html" />
|
|
|
|
<title>CodeQL docs</title>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
|
|
<link rel="stylesheet" href="../_static/primer.css" type="text/css" />
|
|
|
|
|
|
</head><body>
|
|
<header class="Header">
|
|
<div class="Header-item--full">
|
|
<a href="https://codeql.github.com/docs" class="Header-link f2 d-flex flex-items-center">
|
|
<!-- <%= octicon "mark-github", class: "mr-2", height: 32 %> -->
|
|
<svg height="32" class="octicon octicon-mark-github mr-2" viewBox="0 0 16 16" version="1.1" width="32"
|
|
aria-hidden="true">
|
|
<path fill-rule="evenodd"
|
|
d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z">
|
|
</path>
|
|
</svg>
|
|
<span class="hide-sm">CodeQL documentation</span>
|
|
</a>
|
|
</div>
|
|
<div class="Header-item hide-sm hide-md">
|
|
<script src="https://addsearch.com/js/?key=93b4d287e2fc079a4089412b669785d5&categories=!0xhelp.semmle.com,0xcodeql.github.com,1xdocs,1xcodeql-standard-libraries,1xcodeql-query-help"></script>
|
|
</div>
|
|
<div class="Header-item">
|
|
|
|
<details class="dropdown details-reset details-overlay d-inline-block">
|
|
<summary class="btn bg-gray-dark text-white border" aria-haspopup="true">
|
|
CodeQL resources
|
|
<div class="dropdown-caret"></div>
|
|
</summary>
|
|
|
|
<ul class="dropdown-menu dropdown-menu-se dropdown-menu-dark">
|
|
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-overview">CodeQL overview</a></li>
|
|
<li class="dropdown-divider" role="separator"></li>
|
|
<div class="dropdown-header">
|
|
CodeQL tools
|
|
</div>
|
|
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-for-visual-studio-code">CodeQL for VS Code</a>
|
|
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-cli">CodeQL CLI</a>
|
|
</li>
|
|
<li class="dropdown-divider" role="separator"></li>
|
|
<div class="dropdown-header">
|
|
CodeQL guides
|
|
</div>
|
|
<li><a class="dropdown-item" href="https://codeql.github.com/docs/writing-codeql-queries">Writing CodeQL queries</a></li>
|
|
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-language-guides">CodeQL language guides</a>
|
|
<li class="dropdown-divider" role="separator"></li>
|
|
<div class="dropdown-header">
|
|
Reference docs
|
|
</div>
|
|
<li><a class="dropdown-item" href="https://codeql.github.com/docs/ql-language-reference/">QL language
|
|
reference</a>
|
|
<li><a class="dropdown-item" href="https://codeql.github.com/codeql-standard-libraries">CodeQL
|
|
standard-libraries</a>
|
|
<li><a class="dropdown-item" href="https://codeql.github.com/codeql-query-help">CodeQL
|
|
query help</a>
|
|
<li class="dropdown-divider" role="separator"></li>
|
|
<div class="dropdown-header">
|
|
Source files
|
|
</div>
|
|
<li><a class="dropdown-item" href="https://github.com/github/codeql">CodeQL repository</a>
|
|
</ul>
|
|
</details>
|
|
|
|
</div>
|
|
|
|
</header>
|
|
<main class="bg-gray-light clearfix">
|
|
<nav class="SideNav position-sticky top-0 col-lg-3 col-md-3 float-left p-4 hide-sm hide-md overflow-y-auto">
|
|
|
|
<ul class="current">
|
|
<li class="toctree-l1"><a class="reference internal" href="../codeql-overview/index.html">CodeQL overview</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../codeql-for-visual-studio-code/index.html">CodeQL for Visual Studio Code</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../codeql-cli/index.html">CodeQL CLI</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../writing-codeql-queries/index.html">Writing CodeQL queries</a></li>
|
|
<li class="toctree-l1 current"><a class="reference internal" href="index.html">CodeQL language guides</a><ul class="current">
|
|
<li class="toctree-l2"><a class="reference internal" href="codeql-for-cpp.html">CodeQL for C and C++</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="codeql-for-csharp.html">CodeQL for C#</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="codeql-for-go.html">CodeQL for Go</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="codeql-for-java.html">CodeQL for Java</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="codeql-for-javascript.html">CodeQL for JavaScript</a></li>
|
|
<li class="toctree-l2 current"><a class="reference internal" href="codeql-for-python.html">CodeQL for Python</a><ul class="current">
|
|
<li class="toctree-l3"><a class="reference internal" href="basic-query-for-python-code.html">Basic query for Python code</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="codeql-library-for-python.html">CodeQL library for Python</a></li>
|
|
<li class="toctree-l3 current"><a class="current reference internal" href="#">Analyzing data flow in Python</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="using-api-graphs-in-python.html">Using API graphs in Python</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="functions-in-python.html">Functions in Python</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="expressions-and-statements-in-python.html">Expressions and statements in Python</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="analyzing-control-flow-in-python.html">Analyzing control flow in Python</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="codeql-for-ruby.html">CodeQL for Ruby</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../ql-language-reference/index.html">QL language reference</a></li>
|
|
</ul>
|
|
|
|
|
|
</nav>
|
|
|
|
|
|
<div class="body col-sm-12 col-md-9 col-lg-9 float-left border-left">
|
|
|
|
<div class="hide-lg hide-xl px-4 pt-4">
|
|
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|
<ul>
|
|
<li class="nav-item nav-item-0"><a href="../contents.html">CodeQL</a> »</li>
|
|
<li class="nav-item nav-item-1"><a href="index.html"
|
|
>CodeQL language guides</a> »</li>
|
|
<li class="nav-item nav-item-2"><a href="codeql-for-python.html"
|
|
accesskey="U">CodeQL for Python</a> »</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<article class="p-4 col-lg-10 col-md-10 col-sm-12">
|
|
|
|
<section id="analyzing-data-flow-in-python">
|
|
<span id="id1"></span><h1>Analyzing data flow in Python<a class="headerlink" href="#analyzing-data-flow-in-python" title="Link to this heading">¶</a></h1>
|
|
<p>You can use CodeQL to track the flow of data through a Python program to places where the data is used.</p>
|
|
<section id="about-this-article">
|
|
<h2>About this article<a class="headerlink" href="#about-this-article" title="Link to this heading">¶</a></h2>
|
|
<p>This article describes how data flow analysis is implemented in the CodeQL libraries for Python and includes examples to help you write your own data flow queries.
|
|
The following sections describe how to use the libraries for local data flow, global data flow, and taint tracking.
|
|
For a more general introduction to modeling data flow, see “<a class="reference internal" href="../writing-codeql-queries/about-data-flow-analysis.html#about-data-flow-analysis"><span class="std std-ref">About data flow analysis</span></a>.”</p>
|
|
</section>
|
|
<section id="local-data-flow">
|
|
<h2>Local data flow<a class="headerlink" href="#local-data-flow" title="Link to this heading">¶</a></h2>
|
|
<p>Local data flow is data flow within a single method or callable. Local data flow is easier, faster, and more precise than global data flow, and is sufficient for many queries.</p>
|
|
<section id="using-local-data-flow">
|
|
<h3>Using local data flow<a class="headerlink" href="#using-local-data-flow" title="Link to this heading">¶</a></h3>
|
|
<p>The local data flow library is in the module <code class="docutils literal notranslate"><span class="pre">DataFlow</span></code>, which defines the class <code class="docutils literal notranslate"><span class="pre">Node</span></code> denoting any element that data can flow through. The <code class="docutils literal notranslate"><span class="pre">Node</span></code> class has a number of useful subclasses, such as <code class="docutils literal notranslate"><span class="pre">ExprNode</span></code> for expressions, <code class="docutils literal notranslate"><span class="pre">CfgNode</span></code> for control-flow nodes, <code class="docutils literal notranslate"><span class="pre">CallCfgNode</span></code> for function and method calls, and <code class="docutils literal notranslate"><span class="pre">ParameterNode</span></code> for parameters. You can map between data flow nodes and expressions/control-flow nodes using the member predicates <code class="docutils literal notranslate"><span class="pre">asExpr</span></code> and <code class="docutils literal notranslate"><span class="pre">asCfgNode</span></code>:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>class Node {
|
|
/** Gets the expression corresponding to this node, if any. */
|
|
Expr asExpr() { ... }
|
|
|
|
/** Gets the control-flow node corresponding to this node, if any. */
|
|
ControlFlowNode asCfgNode() { ... }
|
|
|
|
...
|
|
}
|
|
</pre></div>
|
|
</div>
|
|
<p>or using the predicate <code class="docutils literal notranslate"><span class="pre">exprNode</span></code>:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>/**
|
|
* Gets a node corresponding to expression `e`.
|
|
*/
|
|
ExprNode exprNode(Expr e) { ... }
|
|
</pre></div>
|
|
</div>
|
|
<p>Due to the control-flow graph being split, there can be multiple data-flow nodes associated with a single expression.</p>
|
|
<p>The predicate <code class="docutils literal notranslate"><span class="pre">localFlowStep(Node</span> <span class="pre">nodeFrom,</span> <span class="pre">Node</span> <span class="pre">nodeTo)</span></code> holds if there is an immediate data flow edge from the node <code class="docutils literal notranslate"><span class="pre">nodeFrom</span></code> to the node <code class="docutils literal notranslate"><span class="pre">nodeTo</span></code>. You can apply the predicate recursively, by using the <code class="docutils literal notranslate"><span class="pre">+</span></code> and <code class="docutils literal notranslate"><span class="pre">*</span></code> operators, or you can use the predefined recursive predicate <code class="docutils literal notranslate"><span class="pre">localFlow</span></code>.</p>
|
|
<p>For example, you can find flow from an expression <code class="docutils literal notranslate"><span class="pre">source</span></code> to an expression <code class="docutils literal notranslate"><span class="pre">sink</span></code> in zero or more local steps:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>DataFlow::localFlow(DataFlow::exprNode(source), DataFlow::exprNode(sink))
|
|
</pre></div>
|
|
</div>
|
|
</section>
|
|
<section id="using-local-taint-tracking">
|
|
<h3>Using local taint tracking<a class="headerlink" href="#using-local-taint-tracking" title="Link to this heading">¶</a></h3>
|
|
<p>Local taint tracking extends local data flow by including non-value-preserving flow steps. For example:</p>
|
|
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">temp</span> <span class="o">=</span> <span class="n">x</span>
|
|
<span class="n">y</span> <span class="o">=</span> <span class="n">temp</span> <span class="o">+</span> <span class="s2">", "</span> <span class="o">+</span> <span class="n">temp</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>If <code class="docutils literal notranslate"><span class="pre">x</span></code> is a tainted string then <code class="docutils literal notranslate"><span class="pre">y</span></code> is also tainted.</p>
|
|
<p>The local taint tracking library is in the module <code class="docutils literal notranslate"><span class="pre">TaintTracking</span></code>. Like local data flow, a predicate <code class="docutils literal notranslate"><span class="pre">localTaintStep(DataFlow::Node</span> <span class="pre">nodeFrom,</span> <span class="pre">DataFlow::Node</span> <span class="pre">nodeTo)</span></code> holds if there is an immediate taint propagation edge from the node <code class="docutils literal notranslate"><span class="pre">nodeFrom</span></code> to the node <code class="docutils literal notranslate"><span class="pre">nodeTo</span></code>. You can apply the predicate recursively, by using the <code class="docutils literal notranslate"><span class="pre">+</span></code> and <code class="docutils literal notranslate"><span class="pre">*</span></code> operators, or you can use the predefined recursive predicate <code class="docutils literal notranslate"><span class="pre">localTaint</span></code>.</p>
|
|
<p>For example, you can find taint propagation from an expression <code class="docutils literal notranslate"><span class="pre">source</span></code> to an expression <code class="docutils literal notranslate"><span class="pre">sink</span></code> in zero or more local steps:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>TaintTracking::localTaint(DataFlow::exprNode(source), DataFlow::exprNode(sink))
|
|
</pre></div>
|
|
</div>
|
|
</section>
|
|
<section id="using-local-sources">
|
|
<h3>Using local sources<a class="headerlink" href="#using-local-sources" title="Link to this heading">¶</a></h3>
|
|
<p>When asking for local data flow or taint propagation between two expressions as above, you would normally constrain the expressions to be relevant to a certain investigation. The next section will give some concrete examples, but there is a more abstract concept that we should call out explicitly, namely that of a local source.</p>
|
|
<p>A local source is a data-flow node with no local data flow into it. As such, it is a local origin of data flow, a place where a new value is created. This includes parameters (which only receive global data flow) and most expressions (because they are not value-preserving). Restricting attention to such local sources gives a much lighter and more performant data-flow graph and in most cases also a more suitable abstraction for the investigation of interest. The class <code class="docutils literal notranslate"><span class="pre">LocalSourceNode</span></code> represents data-flow nodes that are also local sources. It comes with a useful member predicate <code class="docutils literal notranslate"><span class="pre">flowsTo(DataFlow::Node</span> <span class="pre">node)</span></code>, which holds if there is local data flow from the local source to <code class="docutils literal notranslate"><span class="pre">node</span></code>.</p>
|
|
</section>
|
|
<section id="examples">
|
|
<h3>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h3>
|
|
<p>Python has builtin functionality for reading and writing files, such as the function <code class="docutils literal notranslate"><span class="pre">open</span></code>. However, there is also the library <code class="docutils literal notranslate"><span class="pre">os</span></code> which provides low-level file access. This query finds the filename passed to <code class="docutils literal notranslate"><span class="pre">os.open</span></code>:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import python
|
|
import semmle.python.dataflow.new.DataFlow
|
|
import semmle.python.ApiGraphs
|
|
|
|
from DataFlow::CallCfgNode call
|
|
where
|
|
call = API::moduleImport("os").getMember("open").getACall()
|
|
select call.getArg(0)
|
|
</pre></div>
|
|
</div>
|
|
<p>➤ <a class="reference external" href="https://lgtm.com/query/8635258505893505141/">See this in the query console on LGTM.com</a>. Two of the demo projects make use of this low-level API.</p>
|
|
<p>Notice the use of the <code class="docutils literal notranslate"><span class="pre">API</span></code> module for referring to library functions. For more information, see “<a class="reference internal" href="using-api-graphs-in-python.html"><span class="doc">Using API graphs in Python</span></a>.”</p>
|
|
<p>Unfortunately this will only give the expression in the argument, not the values which could be passed to it. So we use local data flow to find all expressions that flow into the argument:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import python
|
|
import semmle.python.dataflow.new.DataFlow
|
|
import semmle.python.ApiGraphs
|
|
|
|
from DataFlow::CallCfgNode call, DataFlow::ExprNode expr
|
|
where
|
|
call = API::moduleImport("os").getMember("open").getACall() and
|
|
DataFlow::localFlow(expr, call.getArg(0))
|
|
select call, expr
|
|
</pre></div>
|
|
</div>
|
|
<p>➤ <a class="reference external" href="https://lgtm.com/query/8213643003890447109/">See this in the query console on LGTM.com</a>. Many expressions flow to the same call.</p>
|
|
<p>We see that we get several data-flow nodes for an expression as it flows towards a call (notice repeated locations in the <code class="docutils literal notranslate"><span class="pre">call</span></code> column). We are mostly interested in the “first” of these, what might be called the local source for the file name. To restrict attention to such local sources, and to simultaneously make the analysis more performant, we have the QL class <code class="docutils literal notranslate"><span class="pre">LocalSourceNode</span></code>. We could demand that <code class="docutils literal notranslate"><span class="pre">expr</span></code> is such a node:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import python
|
|
import semmle.python.dataflow.new.DataFlow
|
|
import semmle.python.ApiGraphs
|
|
|
|
from DataFlow::CallCfgNode call, DataFlow::ExprNode expr
|
|
where
|
|
call = API::moduleImport("os").getMember("open").getACall() and
|
|
DataFlow::localFlow(expr, call.getArg(0)) and
|
|
expr instanceof DataFlow::LocalSourceNode
|
|
select call, expr
|
|
</pre></div>
|
|
</div>
|
|
<p>However, we could also enforce this by casting. That would allow us to use the member function <code class="docutils literal notranslate"><span class="pre">flowsTo</span></code> on <code class="docutils literal notranslate"><span class="pre">LocalSourceNode</span></code> like so:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import python
|
|
import semmle.python.dataflow.new.DataFlow
|
|
import semmle.python.ApiGraphs
|
|
|
|
from DataFlow::CallCfgNode call, DataFlow::ExprNode expr
|
|
where
|
|
call = API::moduleImport("os").getMember("open").getACall() and
|
|
expr.(DataFlow::LocalSourceNode).flowsTo(call.getArg(0))
|
|
select call, expr
|
|
</pre></div>
|
|
</div>
|
|
<p>As an alternative, we can ask more directly that <code class="docutils literal notranslate"><span class="pre">expr</span></code> is a local source of the first argument, via the predicate <code class="docutils literal notranslate"><span class="pre">getALocalSource</span></code>:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import python
|
|
import semmle.python.dataflow.new.DataFlow
|
|
import semmle.python.ApiGraphs
|
|
|
|
from DataFlow::CallCfgNode call, DataFlow::ExprNode expr
|
|
where
|
|
call = API::moduleImport("os").getMember("open").getACall() and
|
|
expr = call.getArg(0).getALocalSource()
|
|
select call, expr
|
|
</pre></div>
|
|
</div>
|
|
<p>➤ <a class="reference external" href="https://lgtm.com/query/6602079735954016687/">See this in the query console on LGTM.com</a>. All these three queries give identical results. We now mostly have one expression per call.</p>
|
|
<p>We still have some cases of more than one expression flowing to a call, but then they flow through different code paths (possibly due to control-flow splitting, as in the second case).</p>
|
|
<p>We might want to make the source more specific, for example a parameter to a function or method. This query finds instances where a parameter is used as the name when opening a file:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import python
|
|
import semmle.python.dataflow.new.DataFlow
|
|
import semmle.python.ApiGraphs
|
|
|
|
from DataFlow::CallCfgNode call, DataFlow::ParameterNode p
|
|
where
|
|
call = API::moduleImport("os").getMember("open").getACall() and
|
|
DataFlow::localFlow(p, call.getArg(0))
|
|
select call, p
|
|
</pre></div>
|
|
</div>
|
|
<p>➤ <a class="reference external" href="https://lgtm.com/query/3998032643497238063/">See this in the query console on LGTM.com</a>. Very few results now; these could feasibly be inspected manually.</p>
|
|
<p>Using the exact name supplied via the parameter may be too strict. If we want to know if the parameter influences the file name, we can use taint tracking instead of data flow. This query finds calls to <code class="docutils literal notranslate"><span class="pre">os.open</span></code> where the filename is derived from a parameter:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import python
|
|
import semmle.python.dataflow.new.TaintTracking
|
|
import semmle.python.ApiGraphs
|
|
|
|
from DataFlow::CallCfgNode call, DataFlow::ParameterNode p
|
|
where
|
|
call = API::moduleImport("os").getMember("open").getACall() and
|
|
TaintTracking::localTaint(p, call.getArg(0))
|
|
select call, p
|
|
</pre></div>
|
|
</div>
|
|
<p>➤ <a class="reference external" href="https://lgtm.com/query/2129957933670836953/">See this in the query console on LGTM.com</a>. Now we get more results and in more projects.</p>
|
|
</section>
|
|
</section>
|
|
<section id="global-data-flow">
|
|
<h2>Global data flow<a class="headerlink" href="#global-data-flow" title="Link to this heading">¶</a></h2>
|
|
<p>Global data flow tracks data flow throughout the entire program, and is therefore more powerful than local data flow. However, global data flow is less precise than local data flow, and the analysis typically requires significantly more time and memory to perform.</p>
|
|
<blockquote class="pull-quote">
|
|
<div><p>Note</p>
|
|
<p>You can model data flow paths in CodeQL by creating path queries. To view data flow paths generated by a path query in CodeQL for VS Code, you need to make sure that it has the correct metadata and <code class="docutils literal notranslate"><span class="pre">select</span></code> clause. For more information, see <a class="reference internal" href="../writing-codeql-queries/creating-path-queries.html#creating-path-queries"><span class="std std-ref">Creating path queries</span></a>.</p>
|
|
</div></blockquote>
|
|
<section id="using-global-data-flow">
|
|
<h3>Using global data flow<a class="headerlink" href="#using-global-data-flow" title="Link to this heading">¶</a></h3>
|
|
<p>The global data flow library is used by extending the class <code class="docutils literal notranslate"><span class="pre">DataFlow::Configuration</span></code>:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import python
|
|
|
|
class MyDataFlowConfiguration extends DataFlow::Configuration {
|
|
MyDataFlowConfiguration() { this = "..." }
|
|
|
|
override predicate isSource(DataFlow::Node source) {
|
|
...
|
|
}
|
|
|
|
override predicate isSink(DataFlow::Node sink) {
|
|
...
|
|
}
|
|
}
|
|
</pre></div>
|
|
</div>
|
|
<p>These predicates are defined in the configuration:</p>
|
|
<ul class="simple">
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">isSource</span></code> - defines where data may flow from.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">isSink</span></code> - defines where data may flow to.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">isBarrier</span></code> - optionally, restricts the data flow.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">isAdditionalFlowStep</span></code> - optionally, adds additional flow steps.</p></li>
|
|
</ul>
|
|
<p>The characteristic predicate (<code class="docutils literal notranslate"><span class="pre">MyDataFlowConfiguration()</span></code>) defines the name of the configuration, so <code class="docutils literal notranslate"><span class="pre">"..."</span></code> must be replaced with a unique name (for instance the class name).</p>
|
|
<p>The data flow analysis is performed using the predicate <code class="docutils literal notranslate"><span class="pre">hasFlow(DataFlow::Node</span> <span class="pre">source,</span> <span class="pre">DataFlow::Node</span> <span class="pre">sink)</span></code>:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>from MyDataFlowConfiguation dataflow, DataFlow::Node source, DataFlow::Node sink
|
|
where dataflow.hasFlow(source, sink)
|
|
select source, "Dataflow to $@.", sink, sink.toString()
|
|
</pre></div>
|
|
</div>
|
|
</section>
|
|
<section id="using-global-taint-tracking">
|
|
<h3>Using global taint tracking<a class="headerlink" href="#using-global-taint-tracking" title="Link to this heading">¶</a></h3>
|
|
<p>Global taint tracking is to global data flow what local taint tracking is to local data flow. That is, global taint tracking extends global data flow with additional non-value-preserving steps. The global taint tracking library is used by extending the class <code class="docutils literal notranslate"><span class="pre">TaintTracking::Configuration</span></code>:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import python
|
|
|
|
class MyTaintTrackingConfiguration extends TaintTracking::Configuration {
|
|
MyTaintTrackingConfiguration() { this = "..." }
|
|
|
|
override predicate isSource(DataFlow::Node source) {
|
|
...
|
|
}
|
|
|
|
override predicate isSink(DataFlow::Node sink) {
|
|
...
|
|
}
|
|
}
|
|
</pre></div>
|
|
</div>
|
|
<p>These predicates are defined in the configuration:</p>
|
|
<ul class="simple">
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">isSource</span></code> - defines where taint may flow from.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">isSink</span></code> - defines where taint may flow to.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">isSanitizer</span></code> - optionally, restricts the taint flow.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">isAdditionalTaintStep</span></code> - optionally, adds additional taint steps.</p></li>
|
|
</ul>
|
|
<p>Similar to global data flow, the characteristic predicate (<code class="docutils literal notranslate"><span class="pre">MyTaintTrackingConfiguration()</span></code>) defines the unique name of the configuration and the taint analysis is performed using the predicate <code class="docutils literal notranslate"><span class="pre">hasFlow(DataFlow::Node</span> <span class="pre">source,</span> <span class="pre">DataFlow::Node</span> <span class="pre">sink)</span></code>.</p>
|
|
</section>
|
|
<section id="predefined-sources-and-sinks">
|
|
<h3>Predefined sources and sinks<a class="headerlink" href="#predefined-sources-and-sinks" title="Link to this heading">¶</a></h3>
|
|
<p>The data flow library contains a number of predefined sources and sinks, providing a good starting point for defining data flow based security queries.</p>
|
|
<ul class="simple">
|
|
<li><p>The class <code class="docutils literal notranslate"><span class="pre">RemoteFlowSource</span></code> (defined in module <code class="docutils literal notranslate"><span class="pre">semmle.python.dataflow.new.RemoteFlowSources</span></code>) represents data flow from remote network inputs. This is useful for finding security problems in networked services.</p></li>
|
|
<li><p>The library <code class="docutils literal notranslate"><span class="pre">Concepts</span></code> (defined in module <code class="docutils literal notranslate"><span class="pre">semmle.python.Concepts</span></code>) contain several subclasses of <code class="docutils literal notranslate"><span class="pre">DataFlow::Node</span></code> that are security relevant, such as <code class="docutils literal notranslate"><span class="pre">FileSystemAccess</span></code> and <code class="docutils literal notranslate"><span class="pre">SqlExecution</span></code>.</p></li>
|
|
<li><p>The module <code class="docutils literal notranslate"><span class="pre">Attributes</span></code> (defined in module <code class="docutils literal notranslate"><span class="pre">semmle.python.dataflow.new.internal.Attributes</span></code>) defines <code class="docutils literal notranslate"><span class="pre">AttrRead</span></code> and <code class="docutils literal notranslate"><span class="pre">AttrWrite</span></code> which handle both ordinary and dynamic attribute access.</p></li>
|
|
</ul>
|
|
<p>For global flow, it is also useful to restrict sources to instances of <code class="docutils literal notranslate"><span class="pre">LocalSourceNode</span></code>. The predefined sources generally do that.</p>
|
|
</section>
|
|
<section id="class-hierarchy">
|
|
<h3>Class hierarchy<a class="headerlink" href="#class-hierarchy" title="Link to this heading">¶</a></h3>
|
|
<ul>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">DataFlow::Configuration</span></code> - base class for custom global data flow analysis.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">DataFlow::Node</span></code> - an element behaving as a data flow node.</p>
|
|
<blockquote>
|
|
<div><ul>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">DataFlow::CfgNode</span></code> - a control-flow node behaving as a data flow node.</p>
|
|
<blockquote>
|
|
<div><ul class="simple">
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">DataFlow::ExprNode</span></code> - an expression behaving as a data flow node.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">DataFlow::ParameterNode</span></code> - a parameter data flow node representing the value of a parameter at function entry.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">DataFlow::CallCfgNode</span></code> - a control-flow node for a function or method call behaving as a data flow node.</p></li>
|
|
</ul>
|
|
</div></blockquote>
|
|
</li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">RemoteFlowSource</span></code> - data flow from network/remote input.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">Attributes::AttrRead</span></code> - an attribute read as a data flow node.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">Attributes::AttrWrite</span></code> - an attribute write as a data flow node.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">Concepts::SystemCommandExecution</span></code> - a data-flow node that executes an operating system command, for instance by spawning a new process.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">Concepts::FileSystemAccess</span></code> - a data flow node that performs a file system access, including reading and writing data, creating and deleting files and folders, checking and updating permissions, and so on.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">Concepts::Path::PathNormalization</span></code> - a data-flow node that performs path normalization. This is often needed in order to safely access paths.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">Concepts::Decoding</span></code> - a data-flow node that decodes data from a binary or textual format. A decoding (automatically) preserves taint from input to output. However, it can also be a problem in itself, for example if it allows code execution or could result in denial-of-service.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">Concepts::Encoding</span></code> - a data-flow node that encodes data to a binary or textual format. An encoding (automatically) preserves taint from input to output.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">Concepts::CodeExecution</span></code> - a data-flow node that dynamically executes Python code.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">Concepts::SqlExecution</span></code> - a data-flow node that executes SQL statements.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">Concepts::HTTP::Server::RouteSetup</span></code> - a data-flow node that sets up a route on a server.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">Concepts::HTTP::Server::HttpResponse</span></code> - a data-flow node that creates a HTTP response on a server.</p></li>
|
|
</ul>
|
|
</div></blockquote>
|
|
</li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">TaintTracking::Configuration</span></code> - base class for custom global taint tracking analysis.</p></li>
|
|
</ul>
|
|
</section>
|
|
<section id="id2">
|
|
<h3>Examples<a class="headerlink" href="#id2" title="Link to this heading">¶</a></h3>
|
|
<p>This query shows a data flow configuration that uses all network input as data sources:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import python
|
|
import semmle.python.dataflow.new.DataFlow
|
|
import semmle.python.dataflow.new.TaintTracking
|
|
import semmle.python.dataflow.new.RemoteFlowSources
|
|
import semmle.python.Concepts
|
|
|
|
class RemoteToFileConfiguration extends TaintTracking::Configuration {
|
|
RemoteToFileConfiguration() { this = "RemoteToFileConfiguration" }
|
|
|
|
override predicate isSource(DataFlow::Node source) {
|
|
source instanceof RemoteFlowSource
|
|
}
|
|
|
|
override predicate isSink(DataFlow::Node sink) {
|
|
sink = any(FileSystemAccess fa).getAPathArgument()
|
|
}
|
|
}
|
|
|
|
from DataFlow::Node input, DataFlow::Node fileAccess, RemoteToFileConfiguration config
|
|
where config.hasFlow(input, fileAccess)
|
|
select fileAccess, "This file access uses data from $@.",
|
|
input, "user-controllable input."
|
|
</pre></div>
|
|
</div>
|
|
<p>This data flow configuration tracks data flow from environment variables to opening files:</p>
|
|
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import python
|
|
import semmle.python.dataflow.new.TaintTracking
|
|
import semmle.python.ApiGraphs
|
|
|
|
class EnvironmentToFileConfiguration extends DataFlow::Configuration {
|
|
EnvironmentToFileConfiguration() { this = "EnvironmentToFileConfiguration" }
|
|
|
|
override predicate isSource(DataFlow::Node source) {
|
|
source = API::moduleImport("os").getMember("getenv").getACall()
|
|
}
|
|
|
|
override predicate isSink(DataFlow::Node sink) {
|
|
exists(DataFlow::CallCfgNode call |
|
|
call = API::moduleImport("os").getMember("open").getACall() and
|
|
sink = call.getArg(0)
|
|
)
|
|
}
|
|
}
|
|
|
|
from Expr environment, Expr fileOpen, EnvironmentToFileConfiguration config
|
|
where config.hasFlow(DataFlow::exprNode(environment), DataFlow::exprNode(fileOpen))
|
|
select fileOpen, "This call to 'os.open' uses data from $@.",
|
|
environment, "call to 'os.getenv'"
|
|
</pre></div>
|
|
</div>
|
|
<p>➤ <a class="reference external" href="https://lgtm.com/query/6582374907796191895/">Running this in the query console on LGTM.com</a> unsurprisingly yields no results in the demo projects.</p>
|
|
</section>
|
|
</section>
|
|
<section id="further-reading">
|
|
<h2>Further reading<a class="headerlink" href="#further-reading" title="Link to this heading">¶</a></h2>
|
|
<ul class="simple">
|
|
<li><p>“<a class="reference internal" href="../codeql-for-visual-studio-code/exploring-data-flow-with-path-queries.html#exploring-data-flow-with-path-queries"><span class="std std-ref">Exploring data flow with path queries</span></a>”</p></li>
|
|
</ul>
|
|
<ul class="simple">
|
|
<li><p><a class="reference external" href="https://github.com/github/codeql/tree/main/python/ql/src">CodeQL queries for Python</a></p></li>
|
|
<li><p><a class="reference external" href="https://github.com/github/codeql/tree/main/python/ql/examples">Example queries for Python</a></p></li>
|
|
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/python/">CodeQL library reference for Python</a></p></li>
|
|
</ul>
|
|
<ul class="simple">
|
|
<li><p>“<a class="reference internal" href="../ql-language-reference/index.html#ql-language-reference"><span class="std std-ref">QL language reference</span></a>”</p></li>
|
|
<li><p>“<a class="reference internal" href="../codeql-overview/codeql-tools.html#codeql-tools"><span class="std std-ref">CodeQL tools</span></a>”</p></li>
|
|
</ul>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
</article>
|
|
|
|
<!-- GitHub footer, with links to terms and privacy statement -->
|
|
<div class="px-3 px-md-6 f6 py-4 d-sm-flex flex-justify-between flex-row-reverse flex-items-center border-top">
|
|
<ul class="list-style-none d-flex flex-items-center mb-3 mb-sm-0 lh-condensed-ultra">
|
|
<li class="mr-3">
|
|
<a href="https://twitter.com/github" title="GitHub on Twitter" style="color: #959da5;">
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 273.5 222.3" class="d-block" height="18">
|
|
<path
|
|
d="M273.5 26.3a109.77 109.77 0 0 1-32.2 8.8 56.07 56.07 0 0 0 24.7-31 113.39 113.39 0 0 1-35.7 13.6 56.1 56.1 0 0 0-97 38.4 54 54 0 0 0 1.5 12.8A159.68 159.68 0 0 1 19.1 10.3a56.12 56.12 0 0 0 17.4 74.9 56.06 56.06 0 0 1-25.4-7v.7a56.11 56.11 0 0 0 45 55 55.65 55.65 0 0 1-14.8 2 62.39 62.39 0 0 1-10.6-1 56.24 56.24 0 0 0 52.4 39 112.87 112.87 0 0 1-69.7 24 119 119 0 0 1-13.4-.8 158.83 158.83 0 0 0 86 25.2c103.2 0 159.6-85.5 159.6-159.6 0-2.4-.1-4.9-.2-7.3a114.25 114.25 0 0 0 28.1-29.1"
|
|
fill="currentColor"></path>
|
|
</svg>
|
|
</a>
|
|
</li>
|
|
<li class="mr-3">
|
|
<a href="https://www.facebook.com/GitHub" title="GitHub on Facebook" style="color: #959da5;">
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 15.3 15.4" class="d-block" height="18">
|
|
<path
|
|
d="M14.5 0H.8a.88.88 0 0 0-.8.9v13.6a.88.88 0 0 0 .8.9h7.3v-6h-2V7.1h2V5.4a2.87 2.87 0 0 1 2.5-3.1h.5a10.87 10.87 0 0 1 1.8.1v2.1h-1.3c-1 0-1.1.5-1.1 1.1v1.5h2.3l-.3 2.3h-2v5.9h3.9a.88.88 0 0 0 .9-.8V.8a.86.86 0 0 0-.8-.8z"
|
|
fill="currentColor"></path>
|
|
</svg>
|
|
</a>
|
|
</li>
|
|
<li class="mr-3">
|
|
<a href="https://www.youtube.com/github" title="GitHub on YouTube" style="color: #959da5;">
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 19.17 13.6" class="d-block" height="16">
|
|
<path
|
|
d="M18.77 2.13A2.4 2.4 0 0 0 17.09.42C15.59 0 9.58 0 9.58 0a57.55 57.55 0 0 0-7.5.4A2.49 2.49 0 0 0 .39 2.13 26.27 26.27 0 0 0 0 6.8a26.15 26.15 0 0 0 .39 4.67 2.43 2.43 0 0 0 1.69 1.71c1.52.42 7.5.42 7.5.42a57.69 57.69 0 0 0 7.51-.4 2.4 2.4 0 0 0 1.68-1.71 25.63 25.63 0 0 0 .4-4.67 24 24 0 0 0-.4-4.69zM7.67 9.71V3.89l5 2.91z"
|
|
fill="currentColor"></path>
|
|
</svg>
|
|
</a>
|
|
</li>
|
|
<li class="mr-3 flex-self-start">
|
|
<a href="https://www.linkedin.com/company/github" title="GitHub on Linkedin" style="color: #959da5;">
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 19 18" class="d-block" height="18">
|
|
<path
|
|
d="M3.94 2A2 2 0 1 1 2 0a2 2 0 0 1 1.94 2zM4 5.48H0V18h4zm6.32 0H6.34V18h3.94v-6.57c0-3.66 4.77-4 4.77 0V18H19v-7.93c0-6.17-7.06-5.94-8.72-2.91z"
|
|
fill="currentColor"></path>
|
|
</svg>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="https://github.com/github" title="GitHub's organization" style="color: #959da5;">
|
|
<svg version="1.1" width="20" height="20" viewBox="0 0 16 16" class="octicon octicon-mark-github"
|
|
aria-hidden="true">
|
|
<path fill-rule="evenodd"
|
|
d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z">
|
|
</path>
|
|
</svg>
|
|
</a>
|
|
</li>
|
|
</ul>
|
|
<ul class="list-style-none d-flex text-gray">
|
|
<li class="mr-3">©
|
|
<script type="text/javascript">document.write(new Date().getFullYear());</script> GitHub, Inc.</li>
|
|
<li class="mr-3"><a
|
|
href="https://docs.github.com/github/site-policy/github-terms-of-service"
|
|
class="link-gray">Terms </a></li>
|
|
<li><a href="https://docs.github.com/github/site-policy/github-privacy-statement"
|
|
class="link-gray">Privacy </a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</main>
|
|
|
|
<script type="text/javascript">
|
|
$(document).ready(function () {
|
|
$(".toggle > *").hide();
|
|
$(".toggle .name").show();
|
|
$(".toggle .name").click(function () {
|
|
$(this).parent().children().not(".name").toggle(400);
|
|
$(this).parent().children(".name").toggleClass("open");
|
|
})
|
|
});
|
|
</script>
|
|
|
|
</body>
|
|
</html> |