.. _specifying-additional-remote-flow-sources-for-javascript:

Specifying additional remote flow sources for JavaScript

You can model potential sources of untrusted user input in your code without making changes to the CodeQL standard library by specifying extra remote flow sources in an external file.

.. pull-quote::

Note

Specifying remote flow sources in external files is currently in beta and subject to change.

As mentioned in the :doc:`Data flow cheat sheet for JavaScript <data-flow-cheat-sheet-for-javascript>`, the CodeQL libraries for JavaScript

provide a class `RemoteFlowSource <https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/security/dataflow/RemoteFlowSources.qll/type.RemoteFlowSources$RemoteFlowSource.html>`__ to represent sources of untrusted user input, sometimes also referred to as remote flow

sources.

To model a new source of untrusted input, such as a previously unmodelled library API, you can

define a subclass of ``RemoteFlowSource`` that covers all uses of that API. All standard analyses

will then automatically pick up this new source of remote flow.

However, this approach requires writing QL code and adding it to the standard library, which is not

always easy to do. Instead, you can also add a JSON file describing custom sources of untrusted

input to your code base and have it picked up without needing to modify the standard library. This

JSON file can be hand-written or generated by another tool. The custom remote flow sources are only available to the code base containing the JSON file. This means that you need to copy the JSON file into each code base that requires the customizations.

Specification format

The JSON file must be called ``codeql-javascript-remote-flow-sources.json`` and

can be located anywhere in your code base. It should consist of a single JSON object. The property

names of this object are interpreted as `source types`. The values they map to should be arrays of

strings. Each string should be of the form ``window.props``, where ``props`` is a sequence of one

or more property names separated by dots. This notation specifies that any value reachable from the global window

object by this sequence of property names should be considered as untrusted user input of the

associated source type.

Example

Consider the following specification:

.. code-block:: json

It declares that the contents of global variable ``dob``, as well as the contents of properties

``name`` and ``address`` of global variable ``user``, should be considered as remote flow sources,

with source type "user input".

lgtm,codescanning

* Custom remote flow sources can now be specified by including a file named `codeql-javascript-remote-flow-sources.json` in your code base. See documentation for more details.

// include .eslintrc files, package.json files, tsconfig.json files, and

// codeql-javascript-*.json files

patterns.add("**/codeql-javascript-*.json");

private class RemoteFlowSourceAccessPath extends JSONString {

string sourceType;

RemoteFlowSourceAccessPath() {

exists(JSONObject specs |

specs.isTopLevel() and

this.getFile().getBaseName() = "codeql-javascript-remote-flow-sources.json" and

this = specs.getPropValue(sourceType).(JSONArray).getElementValue(_) and

this.getValue().regexpMatch("window(\\.\\w+)+")

)

}

/** Gets the source type of this remote flow source. */

string getSourceType() { result = sourceType }

/** Gets the `i`th component of the access path specifying this remote flow source. */

string getComponent(int i) {

exists(string raw | raw = this.getValue().splitAt(".", i + 1) |

i = 0 and

result = "ExternalRemoteFlowSourceSpec " + raw

or

i > 0 and

result = API::EdgeLabel::member(raw)

)

}

/** Gets the index of the last component of this access path. */

int getMaxComponentIndex() { result = max(int i | exists(getComponent(i))) }

/**

private API::Node resolveUpTo(int i) {

i = -1 and

result = API::root()

or

result = resolveUpTo(i - 1).getASuccessor(getComponent(i))

}

/** Gets the API node to which this access path resolves. */

API::Use resolve() { result = resolveUpTo(getMaxComponentIndex()) }

private class ExternalRemoteFlowSourceSpecEntryPoint extends API::EntryPoint {

string name;

ExternalRemoteFlowSourceSpecEntryPoint() {

this = any(RemoteFlowSourceAccessPath s).getComponent(0) and

this = "ExternalRemoteFlowSourceSpec " + name

}

override DataFlow::SourceNode getAUse() { result = DataFlow::globalVarRef(name) }

override DataFlow::Node getARhs() { none() }

private class ExternalRemoteFlowSource extends RemoteFlowSource {

RemoteFlowSourceAccessPath ap;

ExternalRemoteFlowSource() { this = ap.resolve().getAnImmediateUse() }

override string getSourceType() { result = ap.getSourceType() }

missing

spurious

import javascript

predicate remoteFlowSourceSpec(Comment c, string path, int line, string sourceType) {

c.getLocation().hasLocationInfo(path, line, _, _, _) and

sourceType = c.getText().regexpCapture("\\s*RemoteFlowSource\\s*:\\s*(.+)", 1)

predicate remoteFlowSource(RemoteFlowSource rfs, string path, int line, string sourceType) {

rfs.hasLocationInfo(path, line, _, _, _) and

sourceType = rfs.getSourceType()

query predicate missing(Comment c, string sourceType) {

exists(string path, int line |

remoteFlowSourceSpec(c, path, line, sourceType) and

not remoteFlowSource(_, path, line, sourceType)

)

query predicate spurious(RemoteFlowSource rfs, string sourceType) {

exists(string path, int line |

not remoteFlowSourceSpec(_, path, line, sourceType) and

remoteFlowSource(rfs, path, line, sourceType)

)

{

"user input": [

"window.user.name",

"window.user.address",

"window.dob"

],

"uncontrolled path": [

"window.upload"

]

}

window.user.name; // RemoteFlowSource: user input

window.user.address; // RemoteFlowSource: user input

window.dob; // RemoteFlowSource: user input

window.upload; // RemoteFlowSource: uncontrolled path

this.user.name; // RemoteFlowSource: user input

this.user.address; // RemoteFlowSource: user input

this.dob; // RemoteFlowSource: user input

this.upload; // RemoteFlowSource: uncontrolled path

user.name; // RemoteFlowSource: user input

user.address; // RemoteFlowSource: user input

dob; // RemoteFlowSource: user input

upload; // RemoteFlowSource: uncontrolled path

(function (global) {

global.user.name; // RemoteFlowSource: user input

global.user.address; // RemoteFlowSource: user input

global.dob; // RemoteFlowSource: user input

global.upload; // RemoteFlowSource: uncontrolled path