Path query examples¶

The easiest way to get started writing your own path query is to modify one of the existing queries. For more information, see theCodeQL query help.

The Security Lab researchers have used path queries to find security vulnerabilities in various open source projects. To see articles describing how these queries were written, as well as other posts describing other aspects of security research such as exploiting vulnerabilities, see theGitHub Security Lab website.

Path query metadata¶

Path query metadata must contain the property@kindpath-problem–this ensures that query results are interpreted and displayed correctly.The other metadata requirements depend on how you intend to run the query. For more information, see “Metadata for CodeQL queries.”

Generating path explanations¶

In order to generate path explanations, your query needs to compute a graph.To do this you need to define aquery predicate callededges in your query.This predicate defines the edge relations of the graph you are computing, and it is used to compute the paths related to each result that your query generates.You can import a predefinededges predicate from a path graph module in one of the standard data flow libraries. In addition to the path graph module, the data flow libraries contain the otherclasses,predicates, andmodules that are commonly used in data flow analysis.

importMyFlow::PathGraph

This statement imports thePathGraph module from the data flow library (DataFlow.qll), in whichedges is defined.

You can also import libraries specifically designed to implement data flow analysis in various common frameworks and environments, and many additional libraries are included with CodeQL. To see examples of the different libraries used in data flow analysis, see the links to the built-in queries above or browse thestandard libraries.

For all languages, you can also optionally define anodes query predicate, which specifies the nodes of the path graph that you are interested in. Ifnodes is defined, only edges with endpoints defined by these nodes are selected. Ifnodes is not defined, you select all possible endpoints ofedges.

querypredicateedges(PathNodea,PathNodeb){/* Logical conditions which hold if `(a,b)` is an edge in the data flow graph */}

Declaring sources and sinks¶

You must provide information about thesource andsink in your path query. These are objects that correspond to the nodes of the paths that you are exploring.The name and the type of thesource and thesink must be declared in thefrom statement of the query, and the types must be compatible with the nodes of the graph computed by theedges predicate.

If you are querying C/C++, C#, Go, Java/Kotlin, JavaScript/TypeScript, Python, or Ruby code (and you have usedimportMyFlow::PathGraph in your query), the definitions of thesource andsink are accessed via the module resulting from the application of theGlobal<..> module in the data flow library. You should declare both of these objects in thefrom statement.For example:

moduleMyFlow=DataFlow::Global<MyConfiguration>;fromMyFlow::PathNodesource,MyFlow::PathNodesink

The configuration module must be defined to include definitions of sources and sinks. For example:

moduleMyConfigurationimplementsDataFlow::ConfigSig{predicateisSource(DataFlow::Nodesource){...}predicateisSink(DataFlow::Nodesource){...}}

• isSource() defines where data may flow from.

• isSink() defines where data may flow to.

For more information on using the configuration class in your analysis see the sections on global data flow in “Analyzing data flow in C/C++,” “Analyzing data flow in C#,” and “Analyzing data flow in Python.”

You can also create a configuration for different frameworks and environments by extending theConfiguration class. For more information, see “Types” in the QL language reference.

Defining flow conditions¶

Thewhere clause defines the logical conditions to apply to the variables declared in thefrom clause to generate your results.This clause can useaggregations,predicates, and logicalformulas to limit the variables of interest to a smaller set which meet the defined conditions.

When writing a path queries, you would typically include a predicate that holds only if data flows from thesource to thesink.

You can use theflowPath predicate to specify flow from thesource to thesink for a givenConfiguration:

whereMyFlow::flowPath(source,sink)

Select clause¶

Select clauses for path queries consist of four ‘columns’, with the following structure:

select element, source, sink, string

Theelement andstring columns represent the location of the alert and the alert message respectively, as explained in “About CodeQL queries.” The second and third columns,source andsink, are nodes on the path graph selected by the query.Each result generated by your query is displayed at a single location in the same way as an alert query. Additionally, each result also has an associated path, which can be viewed in theCodeQL extension for VS Code.

Theelement that you select in the first column depends on the purpose of the query and the type of issue that it is designed to find. This is particularly important for security issues. For example, if you believe thesource value to be globally invalid or malicious it may be best to display the alert at thesource. In contrast, you should consider displaying the alert at thesink if you believe it is the element that requires sanitization.

The alert message defined in the final column in theselect statement can be developed to give more detail about the alert or path found by the query using links and placeholders. For more information, see “Defining the results of a query.”

Further reading¶

• Exploring data flow with path queries in the GitHub documentation.

• CodeQL repository