SourcesSinksManager

SourcesSinksManager and SourceSinkConfiguration

Use immutable SourceSinkConfiguration for new taint analyses. SourcesSinksManager remains available for integrations that need mutable AndroidMethod sets. It now supports independent instances; the deprecated v() accessor is only the shared legacy instance.

Immutable definitions

API	Result
SourceSinkConfiguration.empty()	No sources or sinks
builder().source(signature).sink(signature).build()	Explicit immutable definitions
fromFile(path)	Exactly the definitions in that UTF-8 file; bundled entries are not added
bundledDefaults()	Independent immutable snapshot of the library's bundled definitions
builder().include(configuration).build()	Explicit additive composition
sources() / sinks()	Immutable normalized signature sets, sorted lexicographically
toSourceMethods() / toSinkMethods()	Fresh mutable sets of fresh AndroidMethod descriptors for a backend call

The managed session default is empty. To reuse definitions for its no-argument analyzeTaint(), set AndroidAnalysis.builder(apk, platforms).sourcesAndSinks(definitions) before open(). Alternatively, pass them to analyzeTaint(definitions) for one run.

This complete SourceDefinitions.java application takes one definition-file argument. It loads only that file first and then demonstrates an explicit union with the bundled definitions.

import com.jordansamhi.androspecter.files.SourceSinkConfiguration;
import java.nio.file.Path;

/**
 * Command-line example loading immutable file definitions and explicitly adding bundled definitions.
 * The default constructor performs no loading; invoke {@link #main(String[])} to run it.
 */
public final class SourceDefinitions {
    /**
     * Prints file-specific counts and the explicitly combined source/sink signatures without initializing Soot.
     * The supplied file must use the library's UTF-8 {@code TYPE|signature} format.
     *
     * @param args one path to a source/sink definition file
     * @throws IllegalArgumentException if the argument count or a definition record is invalid
     * @throws java.io.UncheckedIOException if a definition file or bundled resource cannot be read
     * @throws IllegalStateException if the bundled classpath resource is missing
     */
    public static void main(String[] args) {
        if (args.length != 1) {
            throw new IllegalArgumentException("Usage: SourceDefinitions <sources-sinks-file>");
        }
        var custom = SourceSinkConfiguration.fromFile(Path.of(args[0]));
        System.out.println("File sources: " + custom.sources().size());
        System.out.println("File sinks: " + custom.sinks().size());

        var combined = SourceSinkConfiguration.builder()
                .include(SourceSinkConfiguration.bundledDefaults())
                .include(custom)
                .build();
        combined.sources().forEach(signature -> System.out.println("SOURCE|" + signature));
        combined.sinks().forEach(signature -> System.out.println("SINK|" + signature));
    }
}

Configuration contains strings, not live Soot objects, and remains usable after reset. Signature validation does not load classes or prove the methods exist. Builders validate added signature syntax at build(); later builder changes cannot alter previous configurations. Mutating objects returned by a to...Methods() conversion cannot change the configuration or another conversion.

File format and errors

# Example definitions; choose APIs relevant to your APK.
SOURCE|<android.telephony.TelephonyManager: java.lang.String getLine1Number()>
SINK|<android.util.Log: int d(java.lang.String,java.lang.String)>

Records are TYPE|<class: returnType method(parameters)>, with case-sensitive SOURCE or SINK. The parser accepts constructors and arrays. Surrounding whitespace is trimmed; blank lines and lines starting with # after trimming are ignored. Parameters are comma-separated. Duplicates are deduplicated, and a method can appear in both sets.

Malformed records throw IllegalArgumentException with context, including the file and line for file loading. Read failures throw UncheckedIOException; null arguments are rejected. File loading validates the entire file before merging entries into a mutable manager, so a read/parse failure does not partially apply its contents. The required bundled classpath resource must be packaged with the library, including when the immutable file loader creates its internal manager.

Mutable legacy manager

new SourcesSinksManager() creates independent sets initialized from the bundled definitions. loadSourcesSinksFromFile(file) adds validated entries to those existing sets; it does not replace the defaults. reset() clears custom entries and restores the bundled records read when that manager was constructed; it does not reread custom files.

The following method-scope snippet needs an existing UTF-8 sources-sinks.txt in the working directory and no initialized Soot scene. Add these imports to the surrounding class:

import com.jordansamhi.androspecter.files.SourcesSinksManager;
import java.io.File;

var manager = new SourcesSinksManager();
manager.loadSourcesSinksFromFile(new File("sources-sinks.txt"));
manager.getSources().forEach(method -> System.out.println(method.getSignature()));
manager.getSinks().forEach(method -> System.out.println(method.getSignature()));

getSources() and getSinks() return live mutable sets, and their AndroidMethod elements are mutable. These descriptors are not resolved SootMethod objects, but changing them can affect set equality/hash behavior. The manager is not thread-safe. SourcesSinksManager.v() shares the same mutable manager across callers; prefer independent construction or the immutable configuration.

Source: SourceSinkConfiguration.java, SourcesSinksManager.java.