Parameterize
============

Extracting untrusted input and replacing these with a configured binding method.

.. contents::

.. toctree::
    :hidden:

    parameterize/array
    parameterize/methodsOnObject

Description
-----------

This action replaces untrusted input with placeholders and extracts them as specified in the configured
binding.

.. warning::

    The parameterize action will only work when the search uses ``containsUntrustedInput`` (for example
    in the :doc:`/ref/targets/expression` target) and its value is set to ``true``.

Configuration Options
---------------------

.. _placeholderFormat:

placeholderFormat
~~~~~~~~~~~~~~~~~

This is the placeholder that's used to replace the untrusted input. The placeholder is simple to
configure, being a text value.

For the example below the placeholder was configured as ``?``.

.. code-block:: diff

    - String sql = "SELECT * FROM users WHERE name='" + name + "'";
    + String sql = "SELECT * FROM users WHERE name=?";

Some variables are available:

.. list-table::
    :header-rows: 1
    :widths: 25 50

    * - variable
      - functionality
    * - ``{{{index}}}``
      - starts at 0 and increments for each untrusted input
    * - ``{{{indexFrom0}}}``
      - same as ``{{{index}}}``
    * - ``{{{indexFrom1}}}``
      - starts at 1 and increments for each untrusted input
    * - ``{{{name}}}``
      - a suitable name for the untrusted input it replaces

.. seealso::

    For more information on mustache variables see :doc:`/ref/templating`

extractUntrustedInput
~~~~~~~~~~~~~~~~~~~~~

The ``extractUntrustedInput`` property describes how the untrusted input elements will be extracted
and where these will be placed.

into array
^^^^^^^^^^

.. code-block:: diff
    :emphasize-lines: 5

       public User searchUser(DirContext ctx, String user, String password) {
     -     String filter = "(&(uid=" + user + ")(userpassword=" + password + "))";
     +     String filter = "(&(uid={0})(userpassword={1}))";
     -     ctx.search("ou=system", filter, new SearchControls());
     +     ctx.search("ou=system", filter, new String[]{user, password}, new SearchControls());
           // ...
       }

.. seealso::

    See :doc:`parameterize/array` for more details on this extraction option

into methodcalls on objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: diff
    :emphasize-lines: 6

      public int x() throws SQLException
      {
          PreparedStatement stmt;
    -     stmt = this.con.prepareStatement("SELECT id FROM users WHERE email='" + getEmail() + "'");
    +     stmt = this.con.prepareStatement("SELECT id FROM users WHERE email=?");
    +     stmt.setString(1, getEmail());
          return stmt.executeQuery().next().getInt(0);
      }

.. code-block:: diff
    :emphasize-lines: 6

      public void x() throws Exception {
          String q;
    -     q = "SELECT * FROM users WHERE email='" + this.getEmail() + "'";
    +     q = "SELECT * FROM users WHERE email=:email";
          HashMap<String, Object> map = new HashMap<>();
    +     map.put("email", this.getEmail());
          getSimpleJdbcTemplate().update(q, map);
      }

.. code-block:: diff
    :emphasize-lines: 5

      public void x(SQLiteQueryBuilder b) throws Exception {
          // ...
    -     b.appendWhere("email = '" + this.getEmail() + "'");
    +     b.appendWhere("email = ");
    +     b.appendWhereEscapeString(this.getEmail());
          // ..
      }

.. seealso::

    See :doc:`parameterize/methodsOnObject` for more details on this extraction option