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_func(table_of_contents: HtmlTableOfContents, tables: List[str], proj_profile: MergedProjectProfile, profiles: List[FuzzerProfile], basefolder: str, coverage_url: str, conclusions: List[HTMLConclusion], 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 optimal 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) str
Create section showing state of project if optimal targets are hit
- get_json_string_result()
Return json_string_result
- 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)
Return json_string_result
- 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]) 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.
- 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)
Return 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]) 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()
Return json_string_result
- 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)
Return json_string_result
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], 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.
- 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)
Return 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]) 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.
- 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)
Return 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
- analysis_func(table_of_contents: HtmlTableOfContents, tables: List[str], project_profile: MergedProjectProfile, profiles: List[FuzzerProfile], basefolder: str, coverage_url: str, conclusions: List[HTMLConclusion]) 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.
- Return type:
str
- Returns:
A string that corresponds to HTML that can be embedded in the html report.
- get_dictionary(profile: FuzzerProfile) str
Extracts a fuzzer dictionary
- get_dictionary_section(profile: FuzzerProfile, table_of_contents: HtmlTableOfContents) 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)
Return json_string_result
Sink function analyser
Analysis plugin for introspection sink functions of interest
- 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]) str
Performs an analysis based on the sink function discovery and analysis. Show all possible sensitive sink functions / methods in the project and display if any fuzzers statically or dynamically reached them. If not, display the parent functions that invoked the sink functions and possible callpath that could reach that specific parent function. Also, possible blocking functions stopping the fuzzer to reach the sink functions in runtime will also be displayed, together with its information to help the developer to update their fuzzers. Simple processing flow of the sink analyser is shown below.
Loop through the all function list of the project and see if any of the sink functions exists.
Shows if each of those functions is statically reachable.
Analyse and show the parent functions that invoked the target sink functions.
Discover and display callpath tree to reach each of the parent functions if that sink function is not statically reached by any fuzzers.
Analyse the fuzzer report to determine if each of those statically reachable sink functions / methods has been dynamically covered by any of the fuzzers
Provide blocker information for those sink functions that are 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