dk.brics.string
Class StringAnalysis

java.lang.Object
  dk.brics.string.StringAnalysis

public class StringAnalysis
extends Object

A StringAnalysis object encapsulates a string analysis performed on a collection of classes. The class also contains some convenience methods for loading and traversing the classes to be analyzed.

Constructor Summary

StringAnalysis()
Performs a string analysis on the current application classes.

StringAnalysis(Collection<ValueBox> hotspots)
Performs a string analysis on the current application classes.

StringAnalysis(Collection<ValueBox> hotspots, ExternalVisibility ext)

StringAnalysis(Collection<ValueBox> hotspots, ExternalVisibility ext, TaintAnalysisStrategy taintAnalysisStrategy)

StringAnalysis(Collection<ValueBox> hotspots, ExternalVisibility externallyVisible, TaintAnalysisStrategy taintAnalysisStrategy, DiagnosticsStrategy diagnostics)
Performs a string analysis on the current application classes.

StringAnalysis(Collection<ValueBox> hotspots, ExternalVisibility externallyVisible, TaintAnalysisStrategy taintAnalysisStrategy, StaticStringTypes staticStringTypes, DiagnosticsStrategy diagnostics)

StringAnalysis(ExternalVisibility ext)
Performs a string analysis on the current application classes.

Method Summary

static void	addDirectoryToClassPath(String dir) Adds the specified directory or jar file to the internal classpath, so library classes can be loaded from there.
static boolean	addJarsToClassPath(String libDir) Adds all jar files found in the specified directory to the internal classpath, so library classes can be loaded from those.
static void	addResolver(Resolver r) Adds the given resolver to the list of active resolvers used during the string analysis.
static void	clearResolvers() Removes all active resolvers.
static List<ValueBox>	getArgumentExpressions(String sig, int argnum) Returns a list containing all expressions occurring as argument to the specified method.
Automaton	getAutomaton(ValueBox box) Computes the automaton describing the possible string values at the given expression.
String	getClassName(ValueBox box) Returns the name of the class containing the given expression.
int	getLineNumber(ValueBox box) Returns the source line number of the given expression.
String	getMethodName(ValueBox box) Returns the name of the method containing the given expression.
int	getNumExps() Returns the total number of analyzable expressions in the program.
static List<ValueBox>	getReturnExpressions(String sig) Returns a list of all expressions that occur as the return value from the specified method or any method that overrides/implements it.
String	getSourceFile(ValueBox box) Returns the name of the source file containing the given expression.
Automaton	getTypeAutomaton(Type t) Computes the automaton describing the possible string values that can occur as a result of converting the given type into a string.
static boolean	hasValidType(ValueBox box) Returns whether or not the given expression has a type that the string analysis is able to handle.
boolean	isTaint(ValueBox box) Returns whether the strings that this valuebox contains can be taint.
static SootClass	loadClass(String name) Loads the named class into the Soot scene, marks it as an application class, and generates bodies for all of its concrete methods.
static int	loadDirectory(String dir) Loads all classes in the specified directory, where the directory refers to the root of the package tree.
static void	removeResolver(Resolver r) Removes the given resolver from the list of active resolvers used during the string analysis.
static void	reset() Resets Soot's globals and the list of resolvers.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StringAnalysis

public StringAnalysis()

Performs a string analysis on the current application classes. All expressions are considered hot spots.

StringAnalysis

public StringAnalysis(Collection<ValueBox> hotspots)

Performs a string analysis on the current application classes.

Parameters:

hotspots - a set of ValueBox objects indicating the desired hot spots

StringAnalysis

public StringAnalysis(Collection<ValueBox> hotspots,
                      ExternalVisibility ext)

StringAnalysis

public StringAnalysis(Collection<ValueBox> hotspots,
                      ExternalVisibility ext,
                      TaintAnalysisStrategy taintAnalysisStrategy)

StringAnalysis

public StringAnalysis(Collection<ValueBox> hotspots,
                      ExternalVisibility externallyVisible,
                      TaintAnalysisStrategy taintAnalysisStrategy,
                      DiagnosticsStrategy diagnostics)

Performs a string analysis on the current application classes.

Parameters:

hotspots - a set of ValueBox objects indicating the desired hot spots

externallyVisible - defines which methods are externally visible.

StringAnalysis

public StringAnalysis(Collection<ValueBox> hotspots,
                      ExternalVisibility externallyVisible,
                      TaintAnalysisStrategy taintAnalysisStrategy,
                      StaticStringTypes staticStringTypes,
                      DiagnosticsStrategy diagnostics)

StringAnalysis

public StringAnalysis(ExternalVisibility ext)

Performs a string analysis on the current application classes. All expressions are considered hot spots.

Parameters:

ext - defines which methods are externally visible.

Method Detail

addDirectoryToClassPath

public static void addDirectoryToClassPath(String dir)

Adds the specified directory or jar file to the internal classpath, so library classes can be loaded from there. The classes in the directory or jar file will not be considered application classes.

Parameters:

dir - classpath to append. May contain either one directoy or jar file, or several ones separated by File.pathSeparator.

addJarsToClassPath

public static boolean addJarsToClassPath(String libDir)

Adds all jar files found in the specified directory to the internal classpath, so library classes can be loaded from those. The classes in the jar files will not be considered application classes.

Parameters:

libDir - path to a directory containing jar files.

Returns:

true if at least one jar file was found.

addResolver

public static void addResolver(Resolver r)

Adds the given resolver to the list of active resolvers used during the string analysis.

Parameters:

r - the resolver to add.

See Also:

Resolver

clearResolvers

public static void clearResolvers()

Removes all active resolvers.

See Also:

Resolver

getArgumentExpressions

public static List<ValueBox> getArgumentExpressions(String sig,
                                                    int argnum)

Returns a list containing all expressions occurring as argument to the specified method.

Parameters:

sig - the signature of the method to collect arguments to, e.g. "<java.io.PrintStream: void println(java.lang.String)>".

argnum - the index of the argument to the call

Returns:

a newly created mutable list of Soot's representation of those expressions.

getAutomaton

public final Automaton getAutomaton(ValueBox box)

Computes the automaton describing the possible string values at the given expression. The expression given can have any type. If the type is String, StringBuffer, StringBuilder, or array (of any dimension) of String, the inferred result is returned directly. If it is of a simple type or a wrapper class, the corresponding type automaton is returned. Otherwise, the inferred result for the return values of the relevant toString methods is returned. If a specific set of hotspots has been supplied to the analysis, and the expression is of one of the string types metioned above, the expression given must be one of these hotspots.

Parameters:

box - the Soot value box containing the expression.

Returns:

an automaton whose language contains all possible run-time values of the given expression.

Throws:

IllegalArgumentException - if the expression is not a marked hotspot.

getClassName

public final String getClassName(ValueBox box)

Returns the name of the class containing the given expression.

Parameters:

box - the expression.

Returns:

the fully qualified class name.

getLineNumber

public final int getLineNumber(ValueBox box)

Returns the source line number of the given expression.

Parameters:

box - the expression.

Returns:

the line number.

getMethodName

public final String getMethodName(ValueBox box)

Returns the name of the method containing the given expression.

Parameters:

box - the expression.

Returns:

the method name.

getNumExps

public final int getNumExps()

Returns the total number of analyzable expressions in the program.

Returns:

the number of expressions in the analyzed program that has a type that the string analysis is able to handle.

getReturnExpressions

public static List<ValueBox> getReturnExpressions(String sig)

Returns a list of all expressions that occur as the return value from the specified method or any method that overrides/implements it.

Parameters:

sig - the signature of the method to collect return expression from, e.g. "<com.example.Action: String getSomeURL()>".

Returns:

a newly created list of Soot's representation of those expressions.

getSourceFile

public final String getSourceFile(ValueBox box)

Returns the name of the source file containing the given expression.

Parameters:

box - the expression.

Returns:

the source file name.

getTypeAutomaton

public final Automaton getTypeAutomaton(Type t)

Computes the automaton describing the possible string values that can occur as a result of converting the given type into a string. If the type is a simple type or a wrapper class, the corresponding type automaton is returned. Otherwise, the result is the union of the inferred results for the return values of the toString methods of the type and all its subclasses.

Parameters:

t - the Soot type.

Returns:

an automaton whose language contains all possible values of the result of converting this type into a string.

hasValidType

public static boolean hasValidType(ValueBox box)

Returns whether or not the given expression has a type that the string analysis is able to handle.

Parameters:

box - the Soot value box containing the expression.

Returns:

true if the expression has type String, StringBuffer, StringBuilder, or array (of any dimension) of String; false otherwise;

isTaint

public boolean isTaint(ValueBox box)

Returns whether the strings that this valuebox contains can be taint. The strategy is defined by TaintAnalysisStrategy.

loadClass

public static SootClass loadClass(String name)

Loads the named class into the Soot scene, marks it as an application class, and generates bodies for all of its concrete methods.

Parameters:

name - the fully qualified name of the class to be loaded.

Returns:

soot's representation of the class

loadDirectory

public static int loadDirectory(String dir)
                         throws IOException

Loads all classes in the specified directory, where the directory refers to the root of the package tree.

The classes are loaded immediately, so make sure the classpath is set accordingly using addJarsToClassPath(String) or addDirectoryToClassPath(String) first. If classes should be loaded from more than one directory, all directories should first be added to the classpath and then loaded.

Parameters:

dir - directory root of the package tree

Returns:

the number of classes loaded

Throws:

IOException

removeResolver

public static void removeResolver(Resolver r)

Removes the given resolver from the list of active resolvers used during the string analysis.

Parameters:

r - the resolver to remove.

See Also:

Resolver

reset

public static void reset()

Resets Soot's globals and the list of resolvers.