Fuzz Introspector analyses

Fuzz Introspector is architected to support plugin-style development of analysis tooling. This makes it possible to construct tooling that uses Fuzz Introspector’s core functionality and extends it for specific applications.

This page contains details about the current analysis plugins.

All plugins are located in src/fuzz-introspector/analyses

Optimal targets

Analysis for identifying optimal targets

class fuzz_introspector.analyses.optimal_targets.OptimalTargets

Bases: AnalysisInterface

Analysis for capturing optimal set of targets.

analysis_func(table_of_contents: HtmlTableOfContents, tables: List[str], proj_profile: MergedProjectProfile, profiles: List[FuzzerProfile], basefolder: str, coverage_url: str, conclusions: List[HTMLConclusion], out_dir, should_synthetise: bool = False) → str

Performs an analysis based on optimal target selection. Finds a set of optimal functions based on complexity reach and:

Displays the functions in a table.
Calculates how the new all-function table will be in case the optimal targets are implemented.
Performs a simple synthesis on how to create fuzzers that target the ptimal functions.

The “optimal target function” is focused on code that is currently not hit by any fuzzers. This means it can be used to expand the current fuzzing harness rather than substitute it.

analysis_get_optimal_targets(merged_profile: MergedProjectProfile) → List[FunctionProfile]: Finds the top reachable functions with minimum overlap. Each of these functions is not be reachable by another function in the returned set, but, they may reach some of the same functions.

get_consequential_section(new_profile: MergedProjectProfile, conclusions: List[HTMLConclusion], tables: List[str], table_of_contents: HtmlTableOfContents, coverage_url: str, basefolder: str, out_dir: str = '') → str: Create section showing state of project if optimal targets are hit

get_json_string_result() → str: Helper for getting json string

classmethod get_name(): Return name of analysis

iteratively_get_optimal_targets(merged_profile: MergedProjectProfile) → Tuple[MergedProjectProfile, List[FunctionProfile]]: Function for synthesizing fuzz targets. The way this one works is by finding optimal targets that don’t overlap too much with each other. The fuzz targets are created to target functions in specific files, so all functions targeted in each fuzzer will be from the same source file. In a sense, this is more of a PoC wy to do some analysis on the data we have. It is likely that we could do something much better.

qualifies_as_optimal_target(fd: FunctionProfile) → bool: Hard conditions for whether a target qualifies as a potential optimal target. These are minimum conditions, i.e. the analysis will still pick a subset of all functions that satisfy the conditions.

set_json_string_result(json_string: str) → None: Helper for setting json string

fuzz_introspector.analyses.optimal_targets.add_func_to_reached_and_clone(merged_profile_old: MergedProjectProfile, func_to_add: FunctionProfile) → MergedProjectProfile: Add new functions as “reached” in a merged profile, and returns a new copy of the merged profile with reachability information as if the functions in func_to_add are added to the merged profile. The use of this is to calculate what the state will be of a merged profile by targetting a new set of functions. We can use this function in a computation of “optimum fuzzer target analysis”, which computes what the combination of ideal function targets.

Runtime coverage analysis

Analysis for creating optimal coverage targets

class fuzz_introspector.analyses.runtime_coverage_analysis.RuntimeCoverageAnalysis

Bases: AnalysisInterface

analysis_func(table_of_contents: HtmlTableOfContents, tables: List[str], proj_profile: MergedProjectProfile, profiles: List[FuzzerProfile], basefolder: str, coverage_url: str, conclusions: List[HTMLConclusion], out_dir) → str

Entrypoint for analysis instance. This function can have side effects on many of the arguments passed to it.

Parameters:

table_of_contents (html_helpers.HtmlTableOfContents) – table of content list for adding sections to HTML report.
tables (List[str]) – list of table ids to be styled in the report.
proj_profile (project_profile.MergedProjectProfile) – project profile involved in the analysis.
profiles (List[fuzzer_profile.FuzzerProfile]) – all fuzzer profiles involved in the current analysis.
basefolder (str) – Basefolder of the files as placed on the file system.
coverage_url (str) – Base coverage URL.
conclusions (List[html_helpers.HTMLConclusion]) – List of high level conclusions to be shown in the final report. Append to this list any conclusions that should be shown at the top of the report page.
out_dir (str) – Output directory of analysis report.

Return type:

str

Returns:

A string that corresponds to HTML that can be embedded in the html report.

get_json_string_result(): Return json_string_result

get_low_cov_high_line_funcs(profiles: List[FuzzerProfile], merged_profile: MergedProjectProfile, min_total_lines: int, max_hit_proportion: int) → List[str]: Identifies the functions that have high line count in source code but only a fraction of the lines are hit at runtime. This is useful to highlight functions that need inspection and is in contrast to statically-extracted data which gives a hit/not-hit verdict on a given function entirely.

classmethod get_name(): Return name of analysis

set_json_string_result(json_string): Set json_string_result

Calltree analysis

Logic related to calltree analysis

class fuzz_introspector.analyses.calltree_analysis.FuzzCalltreeAnalysis

Bases: AnalysisInterface

analysis_func(table_of_contents: HtmlTableOfContents, tables: List[str], proj_profile: MergedProjectProfile, profiles: List[FuzzerProfile], basefolder: str, coverage_url: str, conclusions: List[HTMLConclusion], out_dir) → str: Creates the HTML of the calltree. Returns the HTML as a string.

collect_calltree_nodes(branch_blockers: List[FuzzBranchBlocker], func_call_depth: Optional[CalltreeCallsite]) → Dict[FuzzBranchBlocker, CalltreeCallsite]: Map branch blockers to the calltree nodes

create_branch_blocker_table(profile: FuzzerProfile, tables: List[str], file_link: str, max_number_of_blockers: int) → Optional[str]: Creates HTML string for table showing branch blockers.

create_fuzz_blocker_table(profile: FuzzerProfile, tables: List[str], calltree_file_name: str, fuzz_blockers: Optional[List[CalltreeCallsite]] = None, file_link: Optional[str] = None) → Optional[str]: Creates HTML string for table showing fuzz blockers.

get_fuzz_blockers(profile: FuzzerProfile, max_blockers_to_extract: int = 999) → List[CalltreeCallsite]: Gets a list of fuzz blockers

get_json_string_result(): Helper for getting json string

classmethod get_name(): Return name of analysis

html_create_dedicated_calltree_file(calltree_html_string: str, filename: str, profile: FuzzerProfile) → None: Write a wrapped HTML file with the tags needed from fuzz-introspector We use this only for wrapping calltrees at the moment, however, down the line it makes sense to have an easy wrapper for other HTML pages too.

set_json_string_result(json_string): Helper for setting json string

Driver synthesizer

Analysis for synthesizing fuzz drivers.

class fuzz_introspector.analyses.driver_synthesizer.DriverSynthesizer

Bases: AnalysisInterface

analysis_func(table_of_contents: HtmlTableOfContents, tables: List[str], proj_profile: MergedProjectProfile, profiles: List[FuzzerProfile], basefolder: str, coverage_url: str, conclusions: List[HTMLConclusion], out_dir, fuzz_targets=None) → str

Entrypoint for analysis instance. This function can have side effects on many of the arguments passed to it.

Parameters:

table_of_contents (html_helpers.HtmlTableOfContents) – table of content list for adding sections to HTML report.
tables (List[str]) – list of table ids to be styled in the report.
proj_profile (project_profile.MergedProjectProfile) – project profile involved in the analysis.
profiles (List[fuzzer_profile.FuzzerProfile]) – all fuzzer profiles involved in the current analysis.
basefolder (str) – Basefolder of the files as placed on the file system.
coverage_url (str) – Base coverage URL.
conclusions (List[html_helpers.HTMLConclusion]) – List of high level conclusions to be shown in the final report. Append to this list any conclusions that should be shown at the top of the report page.
out_dir (str) – Output directory of analysis report.

Return type:

str

Returns:

A string that corresponds to HTML that can be embedded in the html report.

get_json_string_result(): Return json_string_result

classmethod get_name(): Return name of analysis

set_json_string_result(json_string): Set json_string_result

Filepath analyser

Analysis for reasoning about file paths in the project

class fuzz_introspector.analyses.filepath_analyser.FilePathAnalysis

Bases: AnalysisInterface

analysis_func(table_of_contents: HtmlTableOfContents, tables: List[str], proj_profile: MergedProjectProfile, profiles: List[FuzzerProfile], basefolder: str, coverage_url: str, conclusions: List[HTMLConclusion], out_dir) → str

Entrypoint for analysis instance. This function can have side effects on many of the arguments passed to it.

Parameters:

table_of_contents (html_helpers.HtmlTableOfContents) – table of content list for adding sections to HTML report.
tables (List[str]) – list of table ids to be styled in the report.
proj_profile (project_profile.MergedProjectProfile) – project profile involved in the analysis.
profiles (List[fuzzer_profile.FuzzerProfile]) – all fuzzer profiles involved in the current analysis.
basefolder (str) – Basefolder of the files as placed on the file system.
coverage_url (str) – Base coverage URL.
conclusions (List[html_helpers.HTMLConclusion]) – List of high level conclusions to be shown in the final report. Append to this list any conclusions that should be shown at the top of the report page.
out_dir (str) – Output directory of analysis report.

Return type:

str

Returns:

A string that corresponds to HTML that can be embedded in the html report.

get_json_string_result(): Return json_string_result

classmethod get_name(): Return name of analysis

set_json_string_result(json_string): Set json_string_result

Engine input

Analysis for creating input consumed by a fuzzer, e.g. a dictionary

class fuzz_introspector.analyses.engine_input.EngineInput

Bases: AnalysisInterface

Generates content that can be used by fuzz engines.

add_to_json_file(json_file_path: str, fuzzer_name: str, key: str, val: List[str]) → None: Add key to json dictionary in json_file_path.

analysis_func(table_of_contents: HtmlTableOfContents, tables: List[str], proj_profile: MergedProjectProfile, profiles: List[FuzzerProfile], basefolder: str, coverage_url: str, conclusions: List[HTMLConclusion], out_dir) → str

Entrypoint for analysis instance. This function can have side effects on many of the arguments passed to it.

Parameters:

table_of_contents (html_helpers.HtmlTableOfContents) – table of content list for adding sections to HTML report.
tables (List[str]) – list of table ids to be styled in the report.
proj_profile (project_profile.MergedProjectProfile) – project profile involved in the analysis.
profiles (List[fuzzer_profile.FuzzerProfile]) – all fuzzer profiles involved in the current analysis.
basefolder (str) – Basefolder of the files as placed on the file system.
coverage_url (str) – Base coverage URL.
conclusions (List[html_helpers.HTMLConclusion]) – List of high level conclusions to be shown in the final report. Append to this list any conclusions that should be shown at the top of the report page.
out_dir (str) – Output directory of analysis report.

Return type:

str

Returns:

A string that corresponds to HTML that can be embedded in the html report.

get_dictionary(profile: FuzzerProfile, out_dir) → str: Extracts a fuzzer dictionary

get_dictionary_section(profile: FuzzerProfile, table_of_contents: HtmlTableOfContents, out_dir) → str: Returns a HTML string with dictionary content, and adds the section link to the table_of_contents.

get_fuzzer_focus_function_section(profile: FuzzerProfile, table_of_contents: HtmlTableOfContents) → str: Returns HTML string with fuzzer focus function

get_json_string_result(): Return json_string_result

classmethod get_name(): Return name of analysis

set_json_string_result(json_string): Set json_string_result

Sink function analyser

Analysis plugin for introspection sink functions of interest for different CWE

class fuzz_introspector.analyses.sinks_analyser.SinkCoverageAnalyser

Bases: AnalysisInterface

This analyser aims to analyse and generate reports to show the occurrence of possible sink functions/methods existed in the target project and if those functions/methods are statically reached or dynamically covered by any of the fuzzers. If not, it provides the information of the parent functions that directly invoke the sink functions and possible call path information to reach the parent functions. This information helps the fuzzer developers to create fuzzers that target specific sink functions. If the target sink function is statically reached by at least a fuzzer but it fails to be covered by a fuzzer during runtime, information of the possible blocking functions are provided to help the fuzzer developers to modify the the fuzzers to make it cover the target sink functions. It is one of the analyser class implementing the analysis.AnalysisInterface class.

Parameters:

json_string_result (str) – JSON result stored when this analyser is first invoked
index (int) – Storing the index using to keep track of the separate callpath html file generated
display_html (bool) – A boolean value to turn html report generation on and off

analysis_func(table_of_contents: HtmlTableOfContents, tables: List[str], proj_profile: MergedProjectProfile, profiles: List[FuzzerProfile], basefolder: str, coverage_url: str, conclusions: List[HTMLConclusion], out_dir) → str

Performs an analysis based on the sink function discovery and analysis. Show all possible sensitive sink functions/methods for each supported CWE found in the project and display if any fuzzers statically or dynamically reached them. If no fuzzers statically reach the specific sink function and it does exist in the project, display the possible call path that could reach that sink function. For each sink function found, it may have more than one accessible call path, the maximum number of call paths generated is configurable by the variable SINK_FUNCTION_CALLPATH_MAX_COUNT in constants.py. If there exist fuzzers that statically reach a specific sink function but no dynamical reaching path is found, then the possible blocking functions together with their information are displayed to help the developer to update their fuzzers. Currently, The OWASP top 10 CWEs are supported on c-cpp/python/java language. All the possible sink functions for each CWE are stored in data/cwe_data.py. Support for more CWEs or refining the sink functions for each CWE could be done by modifying the cwe_data.py. A simple processing flow of the sink analyser for each supported CWE is shown below.

Loop through the all functions list of the project and see if any of the sink functions exist.

Show, if any, fuzzers statically reach the target sink function

Discover and display the call path tree to reach each of the sink functions if it is not statically reached by any fuzzers. For each of the sink functions, only display the top few call paths that are publicly accessible. The number of call paths displayed is configurable in constants.py.

Provide blocker information for those sink functions that are statically covered but not dynamically covered to help the developer to update their fuzzers.

Remark: JSON report will be generated, and HTML report will only be generated if the display_html variable of this analyser is set to True. Please also refer to calltree_analysis.FuzzCalltreeAnalysis

Parameters:

table_of_contents (html_helpers.HtmlTableOfContents) – The object that handle the table of contents generation for the html report
tables (List[str]) – List of html strings for each table to be included in the html report, if it is empty or display_html is False, there will be no html report generated for this analyser
proj_profile (project_profile.MergedProjectProfile) – The object storing all the information for this fuzzing project
profiles (List[fuzzer_profile.FuzzerProfile]) – The object list storing the information of each fuzzers for this fuzzing project
basefolder (str) – The path of the base directory for this fuzz-introspector run
coverage_url (str) – The base URL of the coverage report for this session on this fuzzing project
conclusions (List[html_helpers.HTMLConclusion]) – The object list handling the conclusion session of the html report

get_json_string_result()

Return the stored json string result.

Returns:: The json string result processed and stored by this analyser
Return type:: str

classmethod get_name()

Return the analyser identifying name for processing.

Returns:: The identifying name of this analyser
Return type:: str

set_json_string_result(json_string)

Store the result of this analyser as json string result for further processing in a later time.

Parameters:: json_string (str) – A json string variable storing the processing result of the analyser for future use