Gadget Inspector Documentation

The tool outputs discovered gadget chains to gadget-chains.txt. Each chain is represented as a sequence of method calls. The numbers in parentheses indicate the depth or index within the chain.

Example output structure:

com/package/Class.method(Ljava/lang/Object;...) (-1)
  com/package/Class.method(Ljava/lang/Object;...) (0)
  org/apache/package/Class.method(Ljava/lang/Object;...) (0)

In these chains, the tool identifies entry points (like readObject or InvocationHandler implementations) and follows the flow to 'sinks' (like Method.invoke()) where attacker-controlled data can trigger dangerous actions.

To build the application, ensure you have a JDK installed. Use the Gradle wrapper to create a shadow JAR containing all dependencies.

./gradlew shadowJar

The tool supports detecting SQL injection gadgets (currently supporting JdbcTemplate). For Spring Boot projects where dependencies are nested within the main JAR, use the --boot flag to specify the dependency JAR.

If using MyBatis, you can specify the directory containing mapper XML files using --mybatis.xml <path> to enable MyBatis SQL injection mining.

Example command:

--config sqlinject --boot /path/to/jdbc-1.0-SNAPSHOT.jar

--config sqlinject --boot /xxxxx/xxxx/jdbc-1.0-SNAPSHOT.jar

Use the webservice configuration to scan web projects where the source points are defined by routing entries. This mode is useful for identifying vulnerabilities in web application entry points.

Example command:

--config webservice
--noTaintTrack
--maxChainLength 16
--similarLevel 4
--maxRepeatBranchesTimes 10
--skipSourcesFile /myGadgetinspector/webservice-skip-sources.demo
/temp/halo.jar

Once built, run the application using the java -jar command. You must provide either a path to a .war file (which will be exploded and used as the classpath) or one or more .jar files as arguments.

Memory Warning: The analysis is memory-intensive. It is recommended to allocate at least 2GB of heap size using the -Xmx2G flag for small libraries. For larger applications, allocate as much memory as possible.

java -jar build/libs/gadget-inspector-all.jar <args>

Gadget Inspector uses static analysis and makes simplifying assumptions, which can lead to the following:

1. False Positives: The tool may report chains that cannot actually be triggered because it does not solve for the satisfiability of branch conditions (e.g., it might report a chain inside an if (false) block).
2. Incomplete Control: It may flag reflection as interesting even if an attacker can only influence a subset of possible method names rather than having full control.
3. Blindspots: The tool has a narrow set of 'sink' functions it considers dangerous. It also currently does not follow reflection calls, meaning it may miss chains that rely on dynamic method resolution.
4. No Guarantee of Safety: Finding no chains does not mean an application is safe; it only means no chains matching the tool's specific criteria were found.

To inspect a specific library for gadget chains, pass the path to the JAR file as an argument. The results will be written to a file named gadget-chains.txt in the current directory.

java -Xmx2G -jar build/libs/gadget-inspector-all.jar commons-collections-3.2.1.jar

To specifically target Fastjson gadget chains, use the --config fastjson parameter. You can provide multiple JAR files as targets.

Example command:

--config fastjson /path/to/target1.jar /path/to/target2.jar

--config fastjson /xxxxx/xxxxx/xxxxx/xxxxx.jar /xxxxx/xxxxx/xxxxx/xxxxx2.jar /xxxxx/xxxxx/xxxxx/xxxxx3.jar

When using --config webservice, you can tune the following parameters to manage path explosion and branch frequency:

• --similarLevel n: Mitigates path explosion by using the first n chains and the last 1 chain as deduplication factors. If duplicates exist, the shortest chain is kept.
• --maxRepeatBranchesTimes n: Limits how many times a specific branch function can appear across all identified gadget chains. The default is 20.
• --skipSourcesFile <path>: A file containing classes or routes that should be ignored to reduce false positives.
• --noTaintTrack: Disables taint analysis to find a more comprehensive set of chains. Note that this significantly increases the volume of results requiring manual audit.