Tai-e Reference Documentation

To execute an analysis, you need to specify its id and options (if necessary). All available analyses in Tai-e and their information (e.g., id and available options) are listed in the analysis configuration file src/main/resources/tai-e-analyses.yml.

There are two mutually-exclusive approaches to specify the analyses, by command-line options or by file, as described below.

Specify analyses by command-line options. For running analysis with id A, just give -a A. For specifying some analysis options for A, just append them to analysis id (connected by =), and separate them by ;, for example:

The option system is expressive, and it supports various types of option values, such as boolean, string, integer, and list.

Option -a is repeatable, so that if you need to execute multiple analyses in a single run of Tai-e, say A1 and A2, just repeat -a like: -a A1 -a A2.

Alternatively, you can specify the analyses to be executed (called an analysis plan) in a plan file, and use -p to process the file. Similar to -a, you need to specify the id and options (if necessary) for each analysis in the file. The plan file should be written in YAML.

Note that options -a and -p are mutually-exclusive, thus you cannot specify them simultaneously. See Analysis Management for more information about these two options.

By default, Tai-e keeps results of all executed analyses in memory. If you run multiple analyses and care about the results of only some of them, you could use this option to specify these analyses, then every time Tai-e executes an analysis, it will automatically detect and clean the analysis results which are not used by subsequent analyses to save memory.

The signatures for the eight Java primitive types are simply their names: byte, short, int, long, float, double, char, and boolean.

Java reference types include class types (encompassing interfaces and enums) and array types. The signature formats for these types are outlined below.

The signature for the void type is simply void. This appears in Method Signatures for methods that do not return a value.

For analysis developers, Tai-e provides convenient APIs to access various types. All the classes related to types, mentioned below, are located in the pascal.taie.language.type package.

In Tai-e, the TypeSystem class (accessible via World.get().getTypeSystem()) offers APIs to retrieve all types (except void, which is discussed later):

Additionally, primitive types and the void type are implemented as enums in Tai-e, and can be directly accessed through their respective classes, such as IntType.INT and VoidType.VOID.

Unsurprisingly, the format for class signatures is identical to that of class types, so we won’t repeat the details here.

The format of a method signature is as follows:

Here are some examples of method signatures:

As mentioned earlier, constructors are treated as methods in Tai-e. Each constructor has the name <init>, and its return type is always void. For example, the constructor signatures for ArrayList are:

Another special class member is the static initializer (also known as the class initializer), which is treated as a method with no arguments and no return value in Tai-e. The method name for a static initializer is <clinit>. For example, the signature of static initializer for Object is <java.lang.Object: void <clinit>()>.

Like methods, field signatures uniquely identify fields within a Java program. The format of a field signature is as follows:

For example, the signature for the field info in the following code:

is:

Tai-e offers convenient APIs through the pascal.taie.language.classes.ClassHierarchy class, allowing analysis developers to access a class or member by its signature. The available methods are:

Signatures are composed of various names, including class names, method names, field names, and type names within method and field signatures. To simplify specifying these names, we introduce the concept of name wildcards, which form the foundation of signature patterns. A name wildcard is any name that contains zero or more * characters, where each * can match any sequence of characters.

Here are some examples:

Class signature patterns come in two forms:

The subclass pattern is particularly useful when you need to capture an entire class hierarchy without listing each class individually.

Method signature patterns follow a format similar to method signatures but with added flexibility to match multiple methods. The general format is:

Each component of the method signature pattern supports different matching mechanisms:

Type Signature Patterns:

Parameter Wildcards: Method signature patterns support parameter wildcards, allowing you to specify repetition of type signature patterns. There are three types of repetition:

Here are some examples of method signature patterns:

This pattern matches all methods in List and its implementations that start with get and have one parameter of any type.

This pattern matches all methods in classes directly under the java.lang package that start with set, return void, and have two parameters: a String and any other type.

This pattern matches toString methods that return String and have no parameters, in any class.

This pattern matches all methods in Map and its implementations that have two parameters: the first being Object or any of its subclasses, and the second being any type.

This pattern matches format methods in the String class that take a String parameter followed by zero or more Object (or subclass) parameters.

This pattern matches asList methods in the Arrays class that take between 1 and 5 Object parameters.

Method signature patterns provide a powerful way to specify groups of related methods across multiple classes, greatly simplifying configuration in various analyses. The addition of parameter wildcards further enhances this flexibility, allowing for precise matching of methods with varying numbers of parameters.

Field signature patterns follow a format similar to field signatures but with added flexibility to match multiple fields. The format of a field signature pattern is:

This format is simpler than the method signature pattern, as field signatures do not include a parameter list. Each component (CLASS_PATTERN, FIELD_TYPE_PATTERN, and FIELD_NAME_PATTERN) supports the same matching mechanisms as in method signature patterns.

Example:

This pattern matches the size field in java.util.List and its subclasses, regardless of the field’s type.

Tai-e provides convenient APIs for analysis developers to retrieve multiple classes or members using signature patterns. To use these, developers first create a pascal.taie.language.classes.SignatureMatcher object, passing a ClassHierarchy as an argument. They can then use the following APIs:

In Tai-e, taint analysis is designed and implemented as a plugin of pointer analysis framework. To enable taint analysis with the YAML configuration file, simply start pointer analysis with option taint-config, for example:

then Tai-e will run taint analysis (together with pointer analysis) using a configuration file specified by <path/to/config> (if you need to specify multiple configuration files, please refer to Multiple Configuration Files). In the upcoming section, we will provide a comprehensive guide on crafting a configuration file.

In addition to the YAML configuration file, Tai-e also supports programmatic taint configuration.

To enable it, start pointer analysis with option taint-config-providers, for example:

The class my.example.MyTaintConfigProvider should extend the interface pascal.taie.analysis.pta.plugin.taint.TaintConfigProvider.

We first present several basic concepts employed in the configuration.

Taint objects are generated by sources. In the configuration file, sources are specified as a list of source entries following key sources, for example:

Our taint analysis supports several kinds of sources, as introduced in the next sections.

At present, our taint analysis supports specifying specific variables at call sites of sink methods as sinks. In the configuration file, sinks are defined as a list of sink entries under the key sinks:

If you include this type of sink in the configuration, when the taint analysis identifies that the method METHOD_SIGNATURE is invoked at call site l and the reference at l, as indicated by INDEX_REF, points to any taint objects, it will generate reports for the detected taint flows.

For guidance on specifying METHOD_SIGNATURE and INDEX_REF, please refer to Type, Method, and Field Signatures and Variable Index of A Method.

In taint analysis, taint is associated with data content and can move between objects. This process, known as taint transfer, is common in real-world code. Effectively managing these transfers is crucial for detecting potential security vulnerabilities.

Our taint analysis allows users to define sanitizers in order to reduce false positives. This can be accomplished by writing a list of sanitizer entries under the key sanitizers in the configuration, as demonstrated below:

Subsequently, the taint analysis will prevent the propagation of taint objects to the parameter specified by INDEX in the method METHOD_SIGNATURE.

The taint analysis supports the loading of multiple configuration files, eliminating the need for users to consolidate all configurations into a single extensive file. Users can simply place all relevant configuration files within a designated directory and then provide the path to this directory (<path/to/config>) when enabling the taint analysis.

In console output, the taint analysis reports the detected taint flows using the following format:

Each taint flow is a pair of source point and sink point. A source point refers to a variable that points to a newly-generated taint object, while a sink point designates a variable pointing to taint objects that have flowed from the source point.

Given that there are several kinds of Sources, each kind has a corresponding source point representation with a specific format:

The [i@Ln] represent the position of a statement, where i is the index of the statement in the IR, and n is the line number of the statement in the source code, which can help you locate the statement.

Here are some examples of source points for each kind:

The format of the sink point is exactly the same as call source point, so we won’t repeat the explanation here.

The console output only provides the starting and ending points of the taint flows. However, for users to validate the reported taint flows and associated security vulnerabilities, it is crucial to investigate the detailed propagation path of taint objects. To meet such needs, we define taint flow graph (TFG for short), whose nodes are the program pointers (e.g., variables and fields) that point to taint objects, and edges represent how taint objects flow among the pointers, so that users can check taint flows by going over the TFG.

To address this requirement, we introduce the concept of taint flow graph (TFG). In a TFG, nodes represent program pointers (such as variables and fields) that point to taint objects, while edges illustrate how taint objects move between these pointers. This allows users to review taint flows by analyzing the TFG.

Tai-e will output the path of the dumped TFG:

TFG is dumped as a DOT graph. For a better experience, we recommend installing Graphviz and using it to convert DOT to SVG with the following command:

then you can open the TFG with your web browser and examine it.

The structure of this project is as follows:

Specifically, this project firstly categorizes the configuration files into three main categories: sink, source, and transfer.

Additionally, each subdirectory contains a corresponding README file that provides a brief overview of the relevant vulnerability types.

Users can directly integrate the configuration files from this collection into the Configuration File for the Tai-e taint analysis, or modify and extend them as needed to better meet specific analysis requirements.

Here is an example of how to use the configuration files from this collection. If the user needs to detect an RCE (Remote Code Execution) injection vulnerability in a Java project using the Jetty software library, the following steps can be taken to modify the taint configuration file:

After these steps, the taint configuration file will be as follows:

Exp → Var | Literal | FieldAccess | ArrayAccess | NewExp | InvokeExp | UnaryExp | BinaryExp | InstanceOfExp | CastExp

Stmt → AssignStmt | JumpStmt | Invoke | Return | Throw | Catch | Monitor | Nop

If you specify analyses, say A1,…​,An, via option -a, Tai-e will resolve all analyses directly/indirectly required by A1,…​,An, and generate an analysis plan (including all these analyses) by topological sorting.

Alternatively, you can specify analyses by a plan file, which is a YAML file consisting of a list of analysis entries. Each entry has two attributes:

When using option -p, Tai-e will execute the analyses in strict accordance with the plan file, i.e., it neither resolve analysis dependencies nor sort the analyses, thus, the file should include all required analyses, and each analysis should be placed in front of all the other analyses that require it; otherwise, Tai-e will alert.

Composing a plan file from scratch might be tedious. To ease this task, Tai-e always generate a plan file output/tai-e-plan.yml each time you specify analyses with option -a, so that you can easily obtain a plan file and then edit your plan based on it. In addition, we provide auxiliary option -g (--gen-plan-file) and when you use it together with -a, Tai-e will merely generates plan file without actually running the analyses.