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

Specifying additional remote flow sources for JavaScript
========================================================

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, but note that these customizations
are specific to the code base containing the JSON file. To use them in other code bases, you need
to copy over the JSON file.

Specification format
--------------------

The JSON file must be called ``codeql-javascript-remote-flow-sources.json`` (case-sensitive) 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, specifying 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
-------

As an example, consider the following specification:

.. code-block:: json

  {
    "user input": [ "window.user.name", "window.user.address", "window.dob" ]
  }

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".

Add documentation about new way of adding remote flow sources.
JavaScript: Add documentation about new way of adding remote flow sources.
