|
| 1 | +.. _using-api-graphs-in-ruby: |
| 2 | + |
| 3 | +Using API graphs in Ruby |
| 4 | +========================== |
| 5 | + |
| 6 | +API graphs are a uniform interface for referring to functions, classes, and methods defined in |
| 7 | +external libraries. |
| 8 | + |
| 9 | +About this article |
| 10 | +------------------ |
| 11 | + |
| 12 | +This article describes how you can use API graphs to reference classes and functions defined in library |
| 13 | +code. API graphs are particularly useful when you want to model the remote flow sources available from external library functions. |
| 14 | + |
| 15 | + |
| 16 | +Module and class references |
| 17 | +--------------------------- |
| 18 | + |
| 19 | +The most common entry point into the API graph is when a top-level module or class is accessed. |
| 20 | +For example, you can access the API graph node corresponding to the ``::Regexp`` class |
| 21 | +by using the ``API::getTopLevelMember`` method defined in the ``codeql.ruby.ApiGraphs`` module, as the |
| 22 | +following snippet demonstrates. |
| 23 | + |
| 24 | +.. code-block:: ql |
| 25 | +
|
| 26 | + import codeql.ruby.ApiGraphs |
| 27 | +
|
| 28 | + select API::getTopLevelMember("Regexp") |
| 29 | +
|
| 30 | +The example above finds references to a top-level class. For nested |
| 31 | +modules and classes, you can use the ``getMember`` method. For example the following query selects |
| 32 | +references to the ``Net::HTTP`` class. |
| 33 | + |
| 34 | +.. code-block:: ql |
| 35 | +
|
| 36 | + import codeql.ruby.ApiGraphs |
| 37 | +
|
| 38 | + select API::getTopLevelMember("Net").getMember("HTTP") |
| 39 | +
|
| 40 | +Note that you should specify module names without ``::`` symbols. If you write ``API::getTopLevelMember("Net::HTTP")``, it will not do what you expect. Instead, you need to decompose this name |
| 41 | +into an access of the ``HTTP`` member of the API graph node for ``Net``, as shown in the example above. |
| 42 | + |
| 43 | +Calls and class instantiations |
| 44 | +------------------------------ |
| 45 | + |
| 46 | +To track the calls of externally defined functions, you can use the ``getMethod`` method. The |
| 47 | +following snippet finds all calls of ``Regexp.compile``: |
| 48 | + |
| 49 | +.. code-block:: ql |
| 50 | +
|
| 51 | + import codeql.ruby.ApiGraphs |
| 52 | +
|
| 53 | + select API::getTopLevelMember("Regexp").getMethod("compile") |
| 54 | +
|
| 55 | +The example above is for a call to a class method. Tracking calls to instance methods, is a two-step |
| 56 | +process, first you need to find instances of the class before you can find the calls |
| 57 | +to methods on those instances. The following snippet finds instantiations of the ``Regexp`` class: |
| 58 | + |
| 59 | +.. code-block:: ql |
| 60 | +
|
| 61 | + import codeql.ruby.ApiGraphs |
| 62 | +
|
| 63 | + select API::getTopLevelMember("Regexp").getInstance() |
| 64 | +
|
| 65 | +Note that the ``getInstance`` method also includes subclasses. For example if there is a |
| 66 | +``class SpecialRegexp < Regexp`` then ``getInstance`` also finds ``SpecialRegexp.new``. |
| 67 | + |
| 68 | +The following snippet builds on the above to find calls of the ``Regexp#match?`` instance method: |
| 69 | + |
| 70 | +.. code-block:: ql |
| 71 | +
|
| 72 | + import codeql.ruby.ApiGraphs |
| 73 | +
|
| 74 | + select API::getTopLevelMember("Regexp").getInstance().getMethod("match?") |
| 75 | +
|
| 76 | +Subclasses |
| 77 | +---------- |
| 78 | + |
| 79 | +Many libraries are used by extending one or more library classes. To track this |
| 80 | +in the API graph, you can use the ``getASubclass`` method to get the API graph node corresponding to |
| 81 | +the immediate subclasses of a node. To find *all* subclasses, use ``*`` or ``+`` to apply the |
| 82 | +method repeatedly. You can see an example where all subclasses are identified using ``getASubclass*`` below. |
| 83 | + |
| 84 | +Note that ``getASubclass`` can only return subclasses that are extracted as part of the CodeQL database |
| 85 | +that you are analyzing. When libraries have predefined subclasses, you will need to explicitly include them in your model. |
| 86 | +For example, the ``ActionController::Base`` class has a predefined subclass ``Rails::ApplicationController``. To find |
| 87 | +all subclasses of ``ActionController::Base``, you must explicitly include the subclasses of ``Rails::ApplicationController`` as well. |
| 88 | + |
| 89 | +.. code-block:: ql |
| 90 | +
|
| 91 | + import codeql.ruby.ApiGraphs |
| 92 | +
|
| 93 | +
|
| 94 | + API::Node actionController() { |
| 95 | + result = |
| 96 | + [ |
| 97 | + API::getTopLevelMember("ActionController").getMember("Base"), |
| 98 | + API::getTopLevelMember("Rails").getMember("ApplicationController") |
| 99 | + ].getASubclass*() |
| 100 | + } |
| 101 | +
|
| 102 | + select actionController() |
| 103 | +
|
| 104 | +
|
| 105 | +Using the API graph in dataflow queries |
| 106 | +--------------------------------------- |
| 107 | + |
| 108 | +Dataflow queries often search for points where data from external sources enters the code base |
| 109 | +as well as places where data leaves the code base. API graphs provide a convenient way to refer |
| 110 | +to external API components such as library functions and their inputs and outputs. |
| 111 | +However, you do not use API graph nodes directly in dataflow queries. |
| 112 | + |
| 113 | +- API graph nodes model entities that are defined outside your code base. |
| 114 | +- Dataflow nodes model entities defined within the current code base. |
| 115 | + |
| 116 | +You bridge the gap between the entities outside and inside your code base using |
| 117 | +the API node class methods: ``asSource()`` and ``asSink()``. |
| 118 | + |
| 119 | +The ``asSource()`` method is used to select dataflow nodes where a value from an external source |
| 120 | +enters the current code base. A typical example is the return value of a library function such as |
| 121 | +``File.read(path)``: |
| 122 | + |
| 123 | +.. code-block:: ql |
| 124 | +
|
| 125 | + import codeql.ruby.ApiGraphs |
| 126 | +
|
| 127 | + select API::getTopLevelMember("File").getMethod("read").getReturn().asSource() |
| 128 | +
|
| 129 | +
|
| 130 | +The ``asSink()`` method is used to select dataflow nodes where a value leaves the |
| 131 | +current code base and flows into an external library. For example the second parameter |
| 132 | +of the ``File.write(path, value)`` method. |
| 133 | + |
| 134 | +.. code-block:: ql |
| 135 | +
|
| 136 | + import codeql.ruby.ApiGraphs |
| 137 | +
|
| 138 | + select API::getTopLevelMember("File").getMethod("write").getParameter(1).asSink() |
| 139 | +
|
| 140 | +A more complex example is a call to ``File.open`` with a block argument. This function creates a ``File`` instance |
| 141 | +and passes it to the supplied block. In this case, we are interested in the first parameter of the block because this is where an |
| 142 | +externally created value enters the code base, that is, the ``|file|`` in the Ruby example below: |
| 143 | + |
| 144 | +.. code-block:: ruby |
| 145 | +
|
| 146 | + File.open("/my/file.txt", "w") { |file| file << "Hello world" } |
| 147 | +
|
| 148 | +The following snippet of CodeQL finds parameters of blocks of ``File.open`` method calls: |
| 149 | + |
| 150 | +.. code-block:: ql |
| 151 | +
|
| 152 | + import codeql.ruby.ApiGraphs |
| 153 | +
|
| 154 | + select API::getTopLevelMember("File").getMethod("open").getBlock().getParameter(0).asSource() |
| 155 | +
|
| 156 | +The following example is a dataflow query that that uses API graphs to find cases where data that |
| 157 | +is read flows into a call to ``File.write``. |
| 158 | + |
| 159 | +.. code-block:: ql |
| 160 | +
|
| 161 | + import codeql.ruby.DataFlow |
| 162 | + import codeql.ruby.ApiGraphs |
| 163 | +
|
| 164 | + class Configuration extends DataFlow::Configuration { |
| 165 | + Configuration() { this = "File read/write Configuration" } |
| 166 | +
|
| 167 | + override predicate isSource(DataFlow::Node source) { |
| 168 | + source = API::getTopLevelMember("File").getMethod("read").getReturn().asSource() |
| 169 | + } |
| 170 | +
|
| 171 | + override predicate isSink(DataFlow::Node sink) { |
| 172 | + sink = API::getTopLevelMember("File").getMethod("write").getParameter(1).asSink() |
| 173 | + } |
| 174 | + } |
| 175 | +
|
| 176 | + from DataFlow::Node src, DataFlow::Node sink, Configuration config |
| 177 | + where config.hasFlow(src, sink) |
| 178 | + select src, "The data read here flows into a $@ call.", sink, "File.write" |
| 179 | +
|
| 180 | +Further reading |
| 181 | +--------------- |
| 182 | + |
| 183 | + |
| 184 | +.. include:: ../reusables/ruby-further-reading.rst |
| 185 | +.. include:: ../reusables/codeql-ref-tools-further-reading.rst |
0 commit comments