mirror of
https://github.com/hohn/codeql-info.git
synced 2025-12-16 20:53:04 +01:00
673 lines
64 KiB
HTML
673 lines
64 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>Customizing Library Models for JavaScript — 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" />
|
||
|
||
<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>
|
||
<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"><a class="reference internal" href="index.html">CodeQL language guides</a></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>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
<article class="p-4 col-lg-10 col-md-10 col-sm-12">
|
||
|
||
<section id="id1">
|
||
<h1>Customizing Library Models for JavaScript<a class="headerlink" href="#id1" title="Link to this heading">¶</a></h1>
|
||
<blockquote class="pull-quote">
|
||
<div><p>Beta Notice - Unstable API</p>
|
||
<p>Library customization using data extensions is currently in beta and subject to change.</p>
|
||
<p>Breaking changes to this format may occur while in beta.</p>
|
||
</div></blockquote>
|
||
<p>JavaScript analysis can be customized by adding library models in data extension files.</p>
|
||
<p>A data extension for JavaScript is a YAML file of the form:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain"><name of extensible predicate></span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain"><tuple1></span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain"><tuple2></span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The CodeQL library for JavaScript exposes the following extensible predicates:</p>
|
||
<ul class="simple">
|
||
<li><p><strong>sourceModel</strong>(type, path, kind)</p></li>
|
||
<li><p><strong>sinkModel</strong>(type, path, kind)</p></li>
|
||
<li><p><strong>typeModel</strong>(type1, type2, path)</p></li>
|
||
<li><p><strong>summaryModel</strong>(type, path, input, output, kind)</p></li>
|
||
</ul>
|
||
<p>See the <a class="reference external" href="https://docs.google.com/document/d/14IYCHX8wWuU-HTvJ2gPSdXQKHKYbWCHQKOgn8oLaa80/edit#heading=h.m0v53lpi6w2n">CLI documentation for how to load and use data extensions in a CodeQL evaluation run</a> (internal access required).</p>
|
||
<p>We’ll explain how to use these using a few examples, and provide some reference material at the end of this article.</p>
|
||
<section id="example-taint-sink-in-the-execa-package">
|
||
<h2>Example: Taint sink in the ‘execa’ package<a class="headerlink" href="#example-taint-sink-in-the-execa-package" title="Link to this heading">¶</a></h2>
|
||
<p>In this example, we’ll show how to add the following argument, passed to <strong>execa</strong>, as a command-line injection sink:</p>
|
||
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="k">import</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">shell</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s2">"execa"</span><span class="p">;</span>
|
||
<span class="nx">shell</span><span class="p">(</span><span class="nx">cmd</span><span class="p">);</span><span class="w"> </span><span class="c1">// <-- add 'cmd' as a taint sink</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that this sink is already recognized by the CodeQL JS analysis, but for this example, you could use the following data extension:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sinkModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"execa"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"Member[shell].Argument[0]"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"command-injection"</span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p>Since we’re adding a new sink, we add a tuple to the <strong>sinkModel</strong> extensible predicate.</p></li>
|
||
<li><p>The first column, <strong>“execa”</strong>, identifies a set of values from which to begin the search for the sink.
|
||
The string <strong>“execa”</strong> means we start at the places where the codebase imports the NPM package <strong>execa</strong>.</p></li>
|
||
<li><p>The second column is an access path that is evaluated from left to right, starting at the values that were identified by the first column.</p>
|
||
<ul>
|
||
<li><p><strong>Member[shell]</strong> selects accesses to the <strong>shell</strong> member of the <strong>execa</strong> package.</p></li>
|
||
<li><p><strong>Argument[0]</strong> selects the first argument to calls to that member.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><strong>command-injection</strong> indicates that this is considered a sink for the command injection query.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="example-taint-sources-from-window-message-events">
|
||
<h2>Example: Taint sources from window ‘message’ events<a class="headerlink" href="#example-taint-sources-from-window-message-events" title="Link to this heading">¶</a></h2>
|
||
<p>In this example, we’ll show how the <strong>event.data</strong> expression below could be marked as a remote flow source:</p>
|
||
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="nb">window</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s2">"message"</span><span class="p">,</span><span class="w"> </span><span class="kd">function</span><span class="w"> </span><span class="p">(</span><span class="nx">event</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="kd">let</span><span class="w"> </span><span class="nx">data</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">event</span><span class="p">.</span><span class="nx">data</span><span class="p">;</span><span class="w"> </span><span class="c1">// <-- add 'event.data' as a taint source</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that this source is already known by the CodeQL JS analysis, but for this example, you could use the following data extension:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sourceModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span>
|
||
<span class="w"> </span><span class="s">"global"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"Member[addEventListener].Argument[1].Parameter[0].Member[data]"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"remote"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p>Since we’re adding a new taint source, we add a tuple to the <strong>sourceModel</strong> extensible predicate.</p></li>
|
||
<li><p>The first column, <strong>“global”</strong>, begins the search at references to the global object (also known as <strong>window</strong> in browser contexts). This is a special JavaScript object that contains all global variables and methods.</p></li>
|
||
<li><p><strong>Member[addEventListener]</strong> selects accesses to the <strong>addEventListener</strong> member.</p></li>
|
||
<li><p><strong>Argument[1]</strong> selects the second argument of calls to that member (the argument containing the callback).</p></li>
|
||
<li><p><strong>Parameter[0]</strong> selects the first parameter of the callback (the parameter named <strong>event</strong>).</p></li>
|
||
<li><p><strong>Member[data]</strong> selects accesses to the <strong>data</strong> property of the event object.</p></li>
|
||
<li><p>Finally, the kind <strong>remote</strong> indicates that this is considered a source of remote flow.</p></li>
|
||
</ul>
|
||
<p>In the next section, we’ll show how to restrict the model to recognize events of a specific type.</p>
|
||
</section>
|
||
<section id="continued-example-restricting-the-event-type">
|
||
<h2>Continued example: Restricting the event type<a class="headerlink" href="#continued-example-restricting-the-event-type" title="Link to this heading">¶</a></h2>
|
||
<p>The model above treats all events as sources of remote flow, not just <strong>message</strong> events.
|
||
For example, it would also pick up this irrelevant source:</p>
|
||
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="nb">window</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s2">"onclick"</span><span class="p">,</span><span class="w"> </span><span class="kd">function</span><span class="w"> </span><span class="p">(</span><span class="nx">event</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="kd">let</span><span class="w"> </span><span class="nx">data</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">event</span><span class="p">.</span><span class="nx">data</span><span class="p">;</span><span class="w"> </span><span class="c1">// <-- 'event.data' became a spurious taint source</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>We can refine the model by adding the <strong>WithStringArgument</strong> component to restrict the set of calls being considered:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sourceModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span>
|
||
<span class="w"> </span><span class="s">"global"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"Member[addEventListener].WithStringArgument[0=message].Argument[1].Parameter[0].Member[data]"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"remote"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <strong>WithStringArgument[0=message]</strong> component here selects the subset of calls to <strong>addEventListener</strong> where the first argument is a string literal with the value <strong>“message”</strong>.</p>
|
||
</section>
|
||
<section id="example-using-types-to-add-mysql-injection-sinks">
|
||
<h2>Example: Using types to add MySQL injection sinks<a class="headerlink" href="#example-using-types-to-add-mysql-injection-sinks" title="Link to this heading">¶</a></h2>
|
||
<p>In this example, we’ll show how to add the following SQL injection sink:</p>
|
||
<div class="highlight-ts notranslate"><div class="highlight"><pre><span></span><span class="k">import</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">Connection</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s2">"mysql"</span><span class="p">;</span>
|
||
|
||
<span class="kd">function</span><span class="w"> </span><span class="nx">submit</span><span class="p">(</span><span class="nx">connection</span><span class="o">:</span><span class="w"> </span><span class="kt">Connection</span><span class="p">,</span><span class="w"> </span><span class="nx">q</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nx">connection</span><span class="p">.</span><span class="nx">query</span><span class="p">(</span><span class="nx">q</span><span class="p">);</span><span class="w"> </span><span class="c1">// <-- add 'q' as a SQL injection sink</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>We can recognize this using the following extension:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sinkModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"mysql.Connection"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"Member[query].Argument[0]"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"sql-injection"</span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p>The first column, <strong>“mysql.Connection”</strong>, begins the search at any expression whose value is known to be an instance of
|
||
the <strong>Connection</strong> type from the <strong>mysql</strong> package. This will select the <strong>connection</strong> parameter above because of its type annotation.</p></li>
|
||
<li><p><strong>Member[query]</strong> selects the <strong>query</strong> member from the connection object.</p></li>
|
||
<li><p><strong>Argument[0]</strong> selects the first argument of a call to that member.</p></li>
|
||
<li><p><strong>sql-injection</strong> indicates that this is considered a sink for the SQL injection query.</p></li>
|
||
</ul>
|
||
<p>This works in this example because the <strong>connection</strong> parameter has a type annotation that matches what the model is looking for.</p>
|
||
<p>Note that there is a significant difference between the following two rows:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"mysql.Connection"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">""</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">...</span><span class="p p-Indicator">]</span>
|
||
<span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"mysql"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"Member[Connection]"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">...</span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The first row matches instances of <strong>mysql.Connection</strong>, which are objects that encapsulate a MySQL connection.
|
||
The second row would match something like <strong>require(‘mysql’).Connection</strong>, which is not itself a connection object.</p>
|
||
<p>In the next section, we’ll show how to generalize the model to handle the absence of type annotations.</p>
|
||
</section>
|
||
<section id="continued-example-dealing-with-untyped-code">
|
||
<h2>Continued example: Dealing with untyped code<a class="headerlink" href="#continued-example-dealing-with-untyped-code" title="Link to this heading">¶</a></h2>
|
||
<p>Suppose we want the model from above to detect the sink in this snippet:</p>
|
||
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="k">import</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">getConnection</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s2">"@example/db"</span><span class="p">;</span>
|
||
<span class="kd">let</span><span class="w"> </span><span class="nx">connection</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">getConnection</span><span class="p">();</span>
|
||
<span class="nx">connection</span><span class="p">.</span><span class="nx">query</span><span class="p">(</span><span class="nx">q</span><span class="p">);</span><span class="w"> </span><span class="c1">// <-- add 'q' as a SQL injection sink</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>There is no type annotation on <strong>connection</strong>, and there is no indication of what <strong>getConnection()</strong> returns.
|
||
Using a <strong>typeModel</strong> tuple we can tell our model that this function returns an instance of <strong>mysql.Connection</strong>:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">typeModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"mysql.Connection"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"@example/db"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"Member[getConnection].ReturnValue"</span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p>Since we’re providing type information, we add a tuple to the <strong>typeModel</strong> extensible predicate.</p></li>
|
||
<li><p>The first column, <strong>“mysql.Connection”</strong>, names the type that we’re adding a new definition for.</p></li>
|
||
<li><p>The second column, <strong>“@example/db”</strong>, begins the search at imports of the hypothetical NPM package <strong>@example/db</strong>.</p></li>
|
||
<li><p><strong>Member[getConnection]</strong> selects references to the <strong>getConnection</strong> member from that package.</p></li>
|
||
<li><p><strong>ReturnValue</strong> selects the return value from a call to that member.</p></li>
|
||
</ul>
|
||
<p>The new model states that the return value of <strong>getConnection()</strong> has type <strong>mysql.Connection</strong>.
|
||
Combining this with the sink model we added earlier, the sink in the example is detected by the model.</p>
|
||
<p>The mechanism used here is how library models work for both TypeScript and plain JavaScript.
|
||
A good library model contains <strong>typeModel</strong> tuples to ensure it works even in codebases without type annotations.
|
||
For example, the <strong>mysql</strong> model that is included with the CodeQL JS analysis includes this type definition (among many others):</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"mysql.Connection"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"mysql"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"Member[createConnection].ReturnValue"</span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="example-using-fuzzy-models-to-simplify-modeling">
|
||
<h2>Example: Using fuzzy models to simplify modeling<a class="headerlink" href="#example-using-fuzzy-models-to-simplify-modeling" title="Link to this heading">¶</a></h2>
|
||
<p>In this example, we’ll show how to add the following SQL injection sink using a “fuzzy” model:</p>
|
||
<div class="highlight-ts notranslate"><div class="highlight"><pre><span></span><span class="k">import</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="kr">as</span><span class="w"> </span><span class="nx">mysql</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s1">'mysql'</span><span class="p">;</span>
|
||
<span class="kd">const</span><span class="w"> </span><span class="nx">pool</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">mysql</span><span class="p">.</span><span class="nx">createPool</span><span class="p">({...});</span>
|
||
<span class="nx">pool</span><span class="p">.</span><span class="nx">getConnection</span><span class="p">((</span><span class="nx">err</span><span class="p">,</span><span class="w"> </span><span class="nx">conn</span><span class="p">)</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nx">conn</span><span class="p">.</span><span class="nx">query</span><span class="p">(</span><span class="nx">q</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="nx">err</span><span class="p">,</span><span class="w"> </span><span class="nx">rows</span><span class="p">)</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="p">{...});</span><span class="w"> </span><span class="c1">// <-- add 'q' as a SQL injection sink</span>
|
||
<span class="p">});</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>We can recognize this using a fuzzy model, as shown in the following extension:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sinkModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"mysql"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"Fuzzy.Member[query].Argument[0]"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"sql-injection"</span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p>The first column, <strong>“mysql”</strong>, begins the search at places where the <cite>mysql</cite> package is imported.</p></li>
|
||
<li><p><strong>Fuzzy</strong> selects all objects that appear to originate from the <cite>mysql</cite> package, such as the <cite>pool</cite>, <cite>conn</cite>, <cite>err</cite>, and <cite>rows</cite> objects.</p></li>
|
||
<li><p><strong>Member[query]</strong> selects the <strong>query</strong> member from any of those objects. In this case, the only such member is <cite>conn.query</cite>.
|
||
In principle, this would also find expressions such as <cite>pool.query</cite> and <cite>err.query</cite>, but in practice such expressions
|
||
are not likely to occur, because the <cite>pool</cite> and <cite>err</cite> objects do not have a member named <cite>query</cite>.</p></li>
|
||
<li><p><strong>Argument[0]</strong> selects the first argument of a call to the selected member, that is, the <cite>q</cite> argument to <cite>conn.query</cite>.</p></li>
|
||
<li><p><strong>sql-injection</strong> indicates that this is considered as a sink for the SQL injection query.</p></li>
|
||
</ul>
|
||
<p>For reference, a more detailed model might look like this, as described in the preceding examples:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sinkModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"mysql.Connection"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"Member[query].Argument[0]"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"sql-injection"</span><span class="p p-Indicator">]</span>
|
||
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">typeModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"mysql.Pool"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"mysql"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"Member[createPool].ReturnValue"</span><span class="p p-Indicator">]</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"mysql.Connection"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"mysql.Pool"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"Member[getConnection].Argument[0].Parameter[1]"</span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The model using the <strong>Fuzzy</strong> component is simpler, at the cost of being approximate.
|
||
This technique is useful when modeling a large or complex library, where it is difficult to write a detailed model.</p>
|
||
</section>
|
||
<section id="example-adding-flow-through-decodeuricomponent">
|
||
<h2>Example: Adding flow through ‘decodeURIComponent’<a class="headerlink" href="#example-adding-flow-through-decodeuricomponent" title="Link to this heading">¶</a></h2>
|
||
<p>In this example, we’ll show how to add flow through calls to <cite>decodeURIComponent</cite>:</p>
|
||
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="kd">let</span><span class="w"> </span><span class="nx">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">decodeURIComponent</span><span class="p">(</span><span class="nx">x</span><span class="p">);</span><span class="w"> </span><span class="c1">// add taint flow from 'x' to 'y'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that this flow is already recognized by the CodeQL JS analysis, but for this example, you could use the following data extension:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">summaryModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span>
|
||
<span class="w"> </span><span class="s">"global"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"Member[decodeURIComponent]"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"Argument[0]"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"ReturnValue"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"taint"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p>Since we’re adding flow through a function call, we add a tuple to the <strong>summaryModel</strong> extensible predicate.</p></li>
|
||
<li><p>The first column, <strong>“global”</strong>, begins the search for relevant calls at references to the global object.
|
||
In JavaScript, global variables are properties of the global object, so this lets us access global variables or functions.</p></li>
|
||
<li><p>The second column, <strong>Member[decodeURIComponent]</strong>, is a path leading to the function calls we wish to model.
|
||
In this case, we select references to the <strong>decodeURIComponent</strong> member from the global object, that is,
|
||
the global variable named <strong>decodeURIComponent</strong>.</p></li>
|
||
<li><p>The third column, <strong>Argument[0]</strong>, indicates the input of the flow. In this case, the first argument to the function call.</p></li>
|
||
<li><p>The fourth column, <strong>ReturnValue</strong>, indicates the output of the flow. In this case, the return value of the function call.</p></li>
|
||
<li><p>The last column, <strong>taint</strong>, indicates the kind of flow to add. The value <strong>taint</strong> means the output is not necessarily equal
|
||
to the input, but was derived from the input in a taint-preserving way.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="example-adding-flow-through-underscore-foreach">
|
||
<h2>Example: Adding flow through ‘underscore.forEach’<a class="headerlink" href="#example-adding-flow-through-underscore-foreach" title="Link to this heading">¶</a></h2>
|
||
<p>In this example, we’ll show how to add flow through calls to <strong>forEach</strong> from the <strong>underscore</strong> package:</p>
|
||
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="nx">require</span><span class="p">(</span><span class="s1">'underscore'</span><span class="p">).</span><span class="nx">forEach</span><span class="p">([</span><span class="nx">x</span><span class="p">,</span><span class="w"> </span><span class="nx">y</span><span class="p">],</span><span class="w"> </span><span class="p">(</span><span class="nx">v</span><span class="p">)</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">});</span><span class="w"> </span><span class="c1">// add value flow from 'x' and 'y' to 'v'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that this flow is already recognized by the CodeQL JS analysis, but for this example, you could use the following data extension:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">summaryModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span>
|
||
<span class="w"> </span><span class="s">"underscore"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"Member[forEach]"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"Argument[0].ArrayElement"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"Argument[1].Parameter[0]"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"value"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p>Since we’re adding flow through a function call, we add a tuple to the <strong>summaryModel</strong> extensible predicate.</p></li>
|
||
<li><p>The first column, <strong>“underscore”</strong>, begins the search for relevant calls at places where the <strong>underscore</strong> package is imported.</p></li>
|
||
<li><p>The second column, <strong>Member[forEach]</strong>, selects references to the <strong>forEach</strong> member from the <strong>underscore</strong> package.</p></li>
|
||
<li><p>The third column specifies the input of the flow:</p>
|
||
<ul>
|
||
<li><p><strong>Argument[0]</strong> selects the first argument of <strong>forEach</strong>, which is the array being iterated over.</p></li>
|
||
<li><p><strong>ArrayElement</strong> selects the elements of that array (the expressions <strong>x</strong> and <strong>y</strong>).</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p>The fourth column specifies the output of the flow:</p>
|
||
<ul>
|
||
<li><p><strong>Argument[1]</strong> selects the second argument of <strong>forEach</strong> (the argument containing the callback function).</p></li>
|
||
<li><p><strong>Parameter[0]</strong> selects the first parameter of the callback function (the parameter named <strong>v</strong>).</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p>The last column, <strong>value</strong>, indicates the kind of flow to add. The value <strong>value</strong> means the input value is unchanged as
|
||
it flows to the output.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="reference-material">
|
||
<h2>Reference material<a class="headerlink" href="#reference-material" title="Link to this heading">¶</a></h2>
|
||
<p>The following sections provide reference material for extensible predicates, access paths, types, and kinds.</p>
|
||
</section>
|
||
<section id="extensible-predicates">
|
||
<h2>Extensible predicates<a class="headerlink" href="#extensible-predicates" title="Link to this heading">¶</a></h2>
|
||
<section id="sourcemodel-type-path-kind">
|
||
<h3>sourceModel(type, path, kind)<a class="headerlink" href="#sourcemodel-type-path-kind" title="Link to this heading">¶</a></h3>
|
||
<p>Adds a new taint source. Most taint-tracking queries will use the new source.</p>
|
||
<ul class="simple">
|
||
<li><p><strong>type</strong>: Name of a type from which to evaluate <strong>path</strong>.</p></li>
|
||
<li><p><strong>path</strong>: Access path leading to the source.</p></li>
|
||
<li><p><strong>kind</strong>: Kind of source to add. Currently only <strong>remote</strong> is used.</p></li>
|
||
</ul>
|
||
<p>Example:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sourceModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"global"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"Member[user].Member[name]"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"remote"</span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="sinkmodel-type-path-kind">
|
||
<h3>sinkModel(type, path, kind)<a class="headerlink" href="#sinkmodel-type-path-kind" title="Link to this heading">¶</a></h3>
|
||
<p>Adds a new taint sink. Sinks are query-specific and will typically affect one or two queries.</p>
|
||
<ul class="simple">
|
||
<li><p><strong>type</strong>: Name of a type from which to evaluate <strong>path</strong>.</p></li>
|
||
<li><p><strong>path</strong>: Access path leading to the sink.</p></li>
|
||
<li><p><strong>kind</strong>: Kind of sink to add. See the section on sink kinds for a list of supported kinds.</p></li>
|
||
</ul>
|
||
<p>Example:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sinkModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"global"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"Member[eval].Argument[0]"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"code-injection"</span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="summarymodel-type-path-input-output-kind">
|
||
<h3>summaryModel(type, path, input, output, kind)<a class="headerlink" href="#summarymodel-type-path-input-output-kind" title="Link to this heading">¶</a></h3>
|
||
<p>Adds flow through a function call.</p>
|
||
<ul class="simple">
|
||
<li><p><strong>type</strong>: Name of a type from which to evaluate <strong>path</strong>.</p></li>
|
||
<li><p><strong>path</strong>: Access path leading to a function call.</p></li>
|
||
<li><p><strong>input</strong>: Path relative to the function call that leads to input of the flow.</p></li>
|
||
<li><p><strong>output</strong>: Path relative to the function call leading to the output of the flow.</p></li>
|
||
<li><p><strong>kind</strong>: Kind of summary to add. Can be <strong>taint</strong> for taint-propagating flow, or <strong>value</strong> for value-preserving flow.</p></li>
|
||
</ul>
|
||
<p>Example:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">summaryModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span>
|
||
<span class="w"> </span><span class="s">"global"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"Member[decodeURIComponent]"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"Argument[0]"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"ReturnValue"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"taint"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="typemodel-type1-type2-path">
|
||
<h3>typeModel(type1, type2, path)<a class="headerlink" href="#typemodel-type1-type2-path" title="Link to this heading">¶</a></h3>
|
||
<p>Adds a new definition of a type.</p>
|
||
<ul class="simple">
|
||
<li><p><strong>type1</strong>: Name of the type to define.</p></li>
|
||
<li><p><strong>type2</strong>: Name of the type from which to evaluate <strong>path</strong>.</p></li>
|
||
<li><p><strong>path</strong>: Access path leading from <strong>type2</strong> to <strong>type1</strong>.</p></li>
|
||
</ul>
|
||
<p>Example:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">extensions</span><span class="p">:</span>
|
||
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">addsTo</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">pack</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">codeql/javascript-all</span>
|
||
<span class="w"> </span><span class="nt">extensible</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">typeModel</span>
|
||
<span class="w"> </span><span class="nt">data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span>
|
||
<span class="w"> </span><span class="s">"mysql.Connection"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"@example/db"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="s">"Member[getConnection].ReturnValue"</span><span class="p p-Indicator">,</span>
|
||
<span class="w"> </span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="types">
|
||
<h2>Types<a class="headerlink" href="#types" title="Link to this heading">¶</a></h2>
|
||
<p>A type is a string that identifies a set of values.
|
||
In each of the extensible predicates mentioned in previous section, the first column is always the name of a type.
|
||
A type can be defined by adding <strong>typeModel</strong> tuples for that type. Additionally, the following built-in types are available:</p>
|
||
<ul class="simple">
|
||
<li><p>The name of an NPM package matches imports of that package. For example, the type <strong>express</strong> matches the expression <strong>require(“express”)</strong>. If the package name includes dots, it must be surrounded by single quotes, such as in <strong>‘lodash.escape’</strong>.</p></li>
|
||
<li><p>The type <strong>global</strong> identifies the global object, also known as <strong>window</strong>. In JavaScript, global variables are properties of the global object, so global variables can be identified using this type. (This type also matches imports of the NPM package named <strong>global</strong>, which is a package that happens to export the global object.)</p></li>
|
||
<li><p>A qualified type name of form <strong><package>.<type></strong> identifies expressions of type <strong><type></strong> from <strong><package></strong>. For example, <strong>mysql.Connection</strong> identifies expression of type <strong>Connection</strong> from the <strong>mysql</strong> package. Note that this only works if type annotations are present in the codebase, or if sufficient <strong>typeModel</strong> tuples have been provided for that type.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="access-paths">
|
||
<h2>Access paths<a class="headerlink" href="#access-paths" title="Link to this heading">¶</a></h2>
|
||
<p>The <strong>path</strong>, <strong>input</strong>, and <strong>output</strong> columns consist of a <strong>.</strong>-separated list of components, which is evaluated from left to right, with each step selecting a new set of values derived from the previous set of values.</p>
|
||
<p>The following components are supported:</p>
|
||
<ul class="simple">
|
||
<li><p><strong>Argument[</strong><cite>number</cite><strong>]</strong> selects the argument at the given index.</p></li>
|
||
<li><p><strong>Argument[this]</strong> selects the receiver of a method call.</p></li>
|
||
<li><p><strong>Parameter[</strong><cite>number</cite><strong>]</strong> selects the parameter at the given index.</p></li>
|
||
<li><p><strong>Parameter[this]</strong> selects the <strong>this</strong> parameter of a function.</p></li>
|
||
<li><p><strong>ReturnValue</strong> selects the return value of a function or call.</p></li>
|
||
<li><p><strong>Member[</strong><cite>name</cite><strong>]</strong> selects the property with the given name.</p></li>
|
||
<li><p><strong>AnyMember</strong> selects any property regardless of name.</p></li>
|
||
<li><p><strong>ArrayElement</strong> selects an element of an array.</p></li>
|
||
<li><p><strong>Element</strong> selects an element of an array, iterator, or set object.</p></li>
|
||
<li><p><strong>MapValue</strong> selects a value of a map object.</p></li>
|
||
<li><p><strong>Awaited</strong> selects the value of a promise.</p></li>
|
||
<li><p><strong>Instance</strong> selects instances of a class.</p></li>
|
||
<li><p><strong>Fuzzy</strong> selects all values that are derived from the current value through a combination of the other operations described in this list.
|
||
For example, this can be used to find all values that appear to originate from a particular package. This can be useful for finding method calls
|
||
from a known package, but where the receiver type is not known or is difficult to model.</p></li>
|
||
</ul>
|
||
<p>The following components are called “call site filters”. They select a subset of the previously-selected calls, if the call fits certain criteria:</p>
|
||
<ul class="simple">
|
||
<li><p><strong>WithArity[</strong><cite>number</cite><strong>]</strong> selects the subset of calls that have the given number of arguments.</p></li>
|
||
<li><p><strong>WithStringArgument[</strong><cite>number</cite><strong>=</strong><cite>value</cite><strong>]</strong> selects the subset of calls where the argument at the given index is a string literal with the given value.</p></li>
|
||
</ul>
|
||
<p>Components related to decorators:</p>
|
||
<ul class="simple">
|
||
<li><p><strong>DecoratedClass</strong> selects a class that has the current value as a decorator. For example, <strong>Member[Component].DecoratedClass</strong> selects any class that is decorated with <strong>@Component</strong>.</p></li>
|
||
<li><p><strong>DecoratedParameter</strong> selects a parameter that is decorated by the current value.</p></li>
|
||
<li><p><strong>DecoratedMember</strong> selects a method, field, or accessor that is decorated by the current value.</p></li>
|
||
</ul>
|
||
<p>Additional notes about the syntax of operands:</p>
|
||
<ul class="simple">
|
||
<li><p>Multiple operands may be given to a single component, as a shorthand for the union of the operands. For example, <strong>Member[foo,bar]</strong> matches the union of <strong>Member[foo]</strong> and <strong>Member[bar]</strong>.</p></li>
|
||
<li><p>Numeric operands to <strong>Argument</strong>, <strong>Parameter</strong>, and <strong>WithArity</strong> may be given as an interval. For example, <strong>Argument[0..2]</strong> matches argument 0, 1, or 2.</p></li>
|
||
<li><p><strong>Argument[N-1]</strong> selects the last argument of a call, and <strong>Parameter[N-1]</strong> selects the last parameter of a function, with <strong>N-2</strong> being the second-to-last and so on.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="kinds">
|
||
<h2>Kinds<a class="headerlink" href="#kinds" title="Link to this heading">¶</a></h2>
|
||
<section id="source-kinds">
|
||
<h3>Source kinds<a class="headerlink" href="#source-kinds" title="Link to this heading">¶</a></h3>
|
||
<ul class="simple">
|
||
<li><p><strong>remote</strong>: A generic source of remote flow. Most taint-tracking queries will use such a source. Currently this is the only supported source kind.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="sink-kinds">
|
||
<h3>Sink kinds<a class="headerlink" href="#sink-kinds" title="Link to this heading">¶</a></h3>
|
||
<p>Unlike sources, sinks tend to be highly query-specific, rarely affecting more than one or two queries. Not every query supports customizable sinks. If the following sinks are not suitable for your use case, you should add a new query.</p>
|
||
<ul class="simple">
|
||
<li><p><strong>code-injection</strong>: A sink that can be used to inject code, such as in calls to <strong>eval</strong>.</p></li>
|
||
<li><p><strong>command-injection</strong>: A sink that can be used to inject shell commands, such as in calls to <strong>child_process.spawn</strong>.</p></li>
|
||
<li><p><strong>path-injection</strong>: A sink that can be used for path injection in a file system access, such as in calls to <strong>fs.readFile</strong>.</p></li>
|
||
<li><p><strong>sql-injection</strong>: A sink that can be used for SQL injection, such as in a MySQL <strong>query</strong> call.</p></li>
|
||
<li><p><strong>nosql-injection</strong>: A sink that can be used for NoSQL injection, such as in a MongoDB <strong>findOne</strong> call.</p></li>
|
||
<li><p><strong>html-injection</strong>: A sink that can be used for HTML injection, such as in a jQuery <strong>$()</strong> call.</p></li>
|
||
<li><p><strong>request-forgery</strong>: A sink that controls the URL of a request, such as in a <strong>fetch</strong> call.</p></li>
|
||
<li><p><strong>url-redirection</strong>: A sink that can be used to redirect the user to a malicious URL.</p></li>
|
||
<li><p><strong>unsafe-deserialization</strong>: A deserialization sink that can lead to code execution or other unsafe behaviour, such as an unsafe YAML parser.</p></li>
|
||
<li><p><strong>log-injection</strong>: A sink that can be used for log injection, such as in a <strong>console.log</strong> call.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="summary-kinds">
|
||
<h3>Summary kinds<a class="headerlink" href="#summary-kinds" title="Link to this heading">¶</a></h3>
|
||
<ul class="simple">
|
||
<li><p><strong>taint</strong>: A summary that propagates taint. This means the output is not necessarily equal to the input, but it was derived from the input in an unrestrictive way. An attacker who controls the input will have significant control over the output as well.</p></li>
|
||
<li><p><strong>value</strong>: A summary that preserves the value of the input or creates a copy of the input such that all of its object properties are preserved.</p></li>
|
||
</ul>
|
||
</section>
|
||
</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> |