Fuzz Introspector datatypes

Represents the main data types in Fuzz Introspector. These are relevant when developing analysis plugins as they expose the data from Fuzz Introspector.

Project profile

Project profile

class fuzz_introspector.datatypes.project_profile.MergedProjectProfile(profiles: List[FuzzerProfile])

Bases: object

Class for storing information about all fuzzers combined in a given project. This means, it contains data for all fuzzers in a given project, and digests the manner in a way that makes sense from a project-scope perspective. For example, it does project-wide analysis of reachable/unreachable functions by digesting data from all the fuzzers in the project.

get_all_functions() → Dict[str, FunctionProfile]

Returns all function profiles of this project. This includes both functions of the module where file paths are available, and, also functions of external dependencies that are just destinations of callsites, namely where there was no source code to inspect.

Use only this for accessing/inspecting/operating on the functions, and not the internal all_functions dictionary.

get_all_functions_with_source() → Dict[str, FunctionProfile]

Returns all functions where there was a source code location attached, which roughly corresponds to functions declared in the project or third parties where source code was pulled in.

get_all_runtime_covered_functions() → List[str]

Gets the name of all functions that are covered by runtime code coverage analysis.

Return type:

List[str]

Returns:

List of strings corresponding to function names

get_complexity_summaries() → Tuple[int, int, int, float, float]

Gets data points summarising cyclomatic complexity across the project, including total complexity, the amount of complexity that is statically reached and the amount of complexity that is statically unreached.

get_direct_parent_list(target_function: FunctionProfile) → Tuple[List[FunctionProfile], List[str]]

Search through list of parent functions of the target function and return a subset of functions in list which is the immediate parent function calling the target function.

get_func_hit_percentage(func_name)

Returns the percentage of lines covered of a function at runtime. Returns 0.0 in case any error happens.

get_function_callpaths(target_function: FunctionProfile, handled_functions: List[FunctionProfile]) → Tuple[List[List[FunctionProfile]], List[List[str]]]

Recursively resolve the incoming reference of a function profile and build up lists of function callpaths from each of the incoming functions to the target function.

get_function_summaries() → Tuple[int, int, int, float, float]

Gets data points summarising data with respect to static reachability of all functions in the project.

property target_lang

Language the fuzzers are written in

Fuzzer profile

Fuzzer profile

class fuzz_introspector.datatypes.fuzzer_profile.FuzzerProfile(cfg_file: str, frontend_yaml: Dict[Any, Any], target_lang: str = 'c-cpp')

Bases: object

Class for storing information about a given Fuzzer. This class essentially holds data corresponding to the output of run of the LLVM plugin. That means, the output from the plugin for a single fuzzer.

accummulate_profile(target_folder: str) → None

Triggers various analyses on the data of the fuzzer. This is used after a profile has been initialised to generate more interesting data.

property entrypoint_function

The name of the fuzzer entrypoint

get_cov_metrics(funcname: str) → Tuple[Optional[int], Optional[int], Optional[float]]

Fethes data points on runtime code coverage for a given function.

A triplet is returned where the first element is the total number of lines in the function, the second element is a list of whether each line was covered at runtime or not, and the third element is the percentage of lines covered by runtime covevrage.

Parameters:

funcname (str) – function to check for.

Return type:

Tuple[Optional[int], Optional[int], Optional[float]]

Returns:

Triplet of int, int, float indicated numbers described above. Or, a triplet of None in the event an error ocurred.

get_cov_uncovered_reachable_funcs() → List[str]

Gets all functions that are statically reachable but are not covered by runtime coverage.

Returns:

List with names of all the functions that are reachable but not covered. If there is no coverage information returns empty list.

get_key() → str

Returns the “key” we use to identify this Fuzzer profile.

has_entry_point() → bool

Returns whether an entrypoint is identified

property identifier

Fuzzer identifier

is_file_covered(file_name: str, basefolder: Optional[str] = None) → bool

Identifies whether a file is covered by runtime code coverage

Parameters:

  • file_name (str) – file name

  • basefolder (str) – basefolder to apply on the file name

Return type:

bool

Returns:

True if the file is covered by runtime code coverage, False otherwise.

property max_func_call_depth

The maximum depth of all callsites in the fuzzer’s calltree.

reaches_file(file_name: str, basefolder: Optional[str] = None) → bool

Identifies if the fuzzer statically reaches a given file

Parameters:

  • file_name (str) – file to check if fuzzer reaches

  • basefolder (str) – basefolder path. If not None will removed from file_name argument.

Returns:

True if the fuzzer statically reaches the file. False otherwise.

Return type:

bool

reaches_func(func_name: str) → bool

Identifies if the fuzzer statically reaches a given function

Parameters:

func_name (str) – function to check for

Return type:

bool

Returns:

True if the fuzzer statically reaches the function. False otherwise.

refine_paths(basefolder: str) → None

Iterate over source files in the calltree and file_targets and remove the fuzzer’s basefolder from the path.

The main point for doing this is clearing any prefixed path that may exist. This is, for example, the case in OSS-Fuzz projects where most files will be prefixed with /src/project_name.

Resolves a link to a coverage report.

property target_lang

Language the fuzzer is written in

Function profile

Function profile

class fuzz_introspector.datatypes.function_profile.FunctionProfile(elem: Dict[Any, Any])

Bases: object

Class for storing information about a given Function

Branch profile

Branch profiler

class fuzz_introspector.datatypes.branch_profile.BranchProfile

Bases: object

Class for storing information about conditional branches collected by LLVM pass.

dump() → None

For debugging purposes, may be removed later.

get_side_unique_reachable_funcnames(branch_side_idx: int) → Set[str]

Returns the set of unique functions reachable from the specified branch side

class fuzz_introspector.datatypes.branch_profile.BranchSide

Bases: object

Class for representing a branch side.

Bug

Represents an issue found by a fuzzer

class fuzz_introspector.datatypes.bug.Bug(source_file: str, source_line: str, function_name: str, fuzzer_name: str, description: str, bug_type: str)

Bases: object

Holds data about a given bug found by fuzzers.