SASTs

codesectools.sasts.core

Initializes the core SAST module.

Modules:

Name	Description
cli	Provides a factory for building command-line interfaces for SAST tools.
graphics	Provides classes for generating plots and visualizations from analysis results.
parser	Defines the core abstract classes for parsing SAST tool results.

cli

Provides a factory for building command-line interfaces for SAST tools.

This module contains the CLIFactory class, which simplifies the creation of standardized typer CLI commands (analyze, benchmark, list, plot) for any SAST integration.

CLIFactory

CLIFactory(sast: SAST, custom_messages: dict)

Provide a factory to generate a standard set of CLI commands for a SAST tool.

Attributes:

Name	Type	Description
cli	typer.Typer	The typer application to which commands will be added.
sast	SAST	The SAST tool instance for which the CLI is being built.
help_messages	dict	A dictionary of help messages for the standard commands.

Initialize the CLIFactory.

Parameters:

Name	Type	Description	Default
sast	SAST	An instance of the SAST tool's implementation class.	required
custom_messages	dict	A dictionary of custom help messages to override the defaults.	required

Methods:

Name	Description
build_cli	Build and return the Typer CLI application for the SAST tool.
add_main	Add the main callback command to the CLI.
add_install	Add the 'install' command to the CLI.
add_analyze	Add the 'analyze' command to the CLI.
add_benchmark	Add the 'benchmark' command to the CLI.
add_list	Add the 'list' command to the CLI.
add_plot	Add the 'plot' command to the CLI.

sast instance-attribute

sast = sast

help_messages instance-attribute

help_messages = {
    "main": f"{sast.name}",
    "install": "List instruction to install missing requirements.",
    "analyze": f"Analyze a project using {sast.name}.",
    "benchmark": f"Benchmark a dataset using {sast.name}.",
    "list": "List existing analysis results.",
    "plot": "Generate plot for results visualization.",
}

build_cli

build_cli() -> typer.Typer

Build and return the Typer CLI application for the SAST tool.

add_main

add_main(help: str = '') -> None

Add the main callback command to the CLI.

This function sets up the main callback that runs when the SAST-specific command is invoked without a subcommand.

Parameters:

Name	Type	Description	Default
help	str	The help string for the main command.	''

add_install

add_install(help: str = '') -> None

Add the 'install' command to the CLI.

This command opens the tool's installation guide URL in a web browser.

Parameters:

Name	Type	Description	Default
help	str	The help string for the command.	''

add_analyze

add_analyze(help: str = '') -> None

Add the 'analyze' command to the CLI.

This command runs the SAST tool on the current directory.

Parameters:

Name	Type	Description	Default
help	str	The help string for the command.	''

add_benchmark

add_benchmark(help: str = '') -> None

Add the 'benchmark' command to the CLI.

This command runs the SAST tool against a specified dataset.

Parameters:

Name	Type	Description	Default
help	str	The help string for the command.	''

add_list

add_list(help: str = '') -> None

Add the 'list' command to the CLI.

This command lists all available analysis results for the SAST tool.

Parameters:

Name	Type	Description	Default
help	str	The help string for the command.	''

add_plot

add_plot(help: str = '') -> None

Add the 'plot' command to the CLI.

This command generates visualizations from analysis or benchmark results.

Parameters:

Name	Type	Description	Default
help	str	The help string for the command.	''

graphics

Provides classes for generating plots and visualizations from analysis results.

This module contains base and specific graphics classes that use Matplotlib to create visual representations of SAST analysis data, such as defect distributions and benchmark performance.

Graphics

Graphics(sast: SAST, project_name: str)

Base class for generating graphics from SAST results.

Attributes:

Name	Type	Description
sast	SAST	The SAST tool instance.
output_dir	Path	The directory containing the analysis results.
color_mapping	dict	A mapping of categories to colors for plotting.
plot_functions	list	A list of methods that generate plots.
limit	int	The maximum number of items to show in top-N plots.
has_latex	bool	True if a LaTeX installation is found.

Initialize the Graphics object.

Parameters:

Name	Type	Description	Default
sast	SAST	The SAST tool instance.	required
project_name	str	The name of the project or dataset being visualized.	required

Methods:

Name	Description
export	Generate, save, and optionally display all registered plots.

sast instance-attribute

sast = sast

output_dir instance-attribute

output_dir = sast.output_dir / project_name

color_mapping instance-attribute

color_mapping = sast.color_mapping

plot_functions instance-attribute

plot_functions = []

limit instance-attribute

limit = 10

has_latex instance-attribute

has_latex = shutil.which('pdflatex')

export

export(overwrite: bool, pgf: bool, show: bool) -> None

Generate, save, and optionally display all registered plots.

Parameters:

Name	Type	Description	Default
overwrite	bool	If True, overwrite existing figure files.	required
pgf	bool	If True and LaTeX is available, export figures in PGF format.	required
show	bool	If True, open the generated figures using the default viewer.	required

ProjectGraphics

ProjectGraphics(sast: SAST, project_name: str)

Bases: Graphics

Generate graphics for a single project analysis result.

Attributes:

Name	Type	Description
result	AnalysisResult	The loaded analysis result data.

Initialize the ProjectGraphics object.

Parameters:

Name	Type	Description	Default
sast	SAST	The SAST tool instance.	required
project_name	str	The name of the project.	required

Methods:

Name	Description
checker_to_category	Map a checker name to its category.
plot_overview	Generate an overview plot with stats by files, checkers, and categories.

result instance-attribute

result = sast.parser.load_from_output_dir(self.output_dir)

checker_to_category

checker_to_category(checker: str) -> str

Map a checker name to its category.

Parameters:

Name	Type	Description	Default
checker	str	The name of the checker.	required

Returns:

Type	Description
str	The category string for the checker, or "NONE" if not found.

plot_overview

plot_overview() -> Figure

Generate an overview plot with stats by files, checkers, and categories.

Returns:

Type	Description
Figure	A Matplotlib Figure object containing the plots.

FileDatasetGraphics

FileDatasetGraphics(sast: SAST, dataset: FileDataset)

Bases: ProjectGraphics

Generate graphics for a file-based dataset benchmark result.

Attributes:

Name	Type	Description
dataset	FileDataset	The dataset instance used for the benchmark.
benchmark_data	FileDatasetData	The validated benchmark data.

Initialize the FileDatasetGraphics object.

Parameters:

Name	Type	Description	Default
sast	SAST	The SAST tool instance.	required
dataset	FileDataset	The file-based dataset that was benchmarked.	required

Methods:

Name	Description
plot_top_cwes	Generate a plot showing the top predicted CWEs.

dataset instance-attribute

dataset = dataset

benchmark_data instance-attribute

benchmark_data = self.dataset.validate(self.result)

plot_top_cwes

plot_top_cwes() -> Figure

Generate a plot showing the top predicted CWEs.

Returns:

Type	Description
Figure	A Matplotlib Figure object containing the plot.

GitRepoDatasetGraphics

GitRepoDatasetGraphics(sast: SAST, dataset: GitRepoDataset)

Bases: Graphics

Generate graphics for a Git repository-based dataset benchmark result.

Attributes:

Name	Type	Description
dataset	GitRepoDataset	The dataset instance used for the benchmark.
results	list[AnalysisResult]	A list of loaded analysis results.
benchmark_data	GitRepoDatasetData	The validated benchmark data.

Initialize the GitRepoDatasetGraphics object.

Parameters:

Name	Type	Description	Default
sast	SAST	The SAST tool instance.	required
dataset	GitRepoDataset	The Git repository-based dataset that was benchmarked.	required

Methods:

Name	Description
checker_to_category	Map a checker name to its category.
plot_overview	Generate an overview plot classifying defects.
plot_top_cwes	Generate a plot showing the top predicted CWEs.
plot_defects_per_loc	Generate a scatter plot of defects found versus lines of code.
plot_time_per_loc	Generate a scatter plot of analysis time versus lines of code.

dataset instance-attribute

dataset = dataset

results instance-attribute

results = sast.parser.load_from_output_dirs(repo_paths)

benchmark_data instance-attribute

benchmark_data = self.dataset.validate(self.results)

checker_to_category

checker_to_category(checker: str) -> str

Map a checker name to its category.

Parameters:

Name	Type	Description	Default
checker	str	The name of the checker.	required

Returns:

Type	Description
str	The category string for the checker, or "NONE" if not found.

plot_overview

plot_overview() -> Figure

Generate an overview plot classifying defects.

Returns:

Type	Description
Figure	A Matplotlib Figure object containing the plot.

plot_top_cwes

plot_top_cwes() -> Figure

Generate a plot showing the top predicted CWEs.

Returns:

Type	Description
Figure	A Matplotlib Figure object containing the plot.

plot_defects_per_loc

plot_defects_per_loc() -> Figure

Generate a scatter plot of defects found versus lines of code.

Returns:

Type	Description
Figure	A Matplotlib Figure object containing the plot.

plot_time_per_loc

plot_time_per_loc() -> Figure

Generate a scatter plot of analysis time versus lines of code.

Returns:

Type	Description
Figure	A Matplotlib Figure object containing the plot.

parser

Defines the core abstract classes for parsing SAST tool results.

This module provides the Defect and AnalysisResult classes, which serve as standardized data structures for holding information about vulnerabilities and the overall analysis process. Each SAST integration must implement a concrete subclass of AnalysisResult to parse its specific output format.

Defect

Defect(
    file: str,
    checker: str,
    category: str,
    cwe: CWE,
    data: tuple[Any],
)

Represent a single defect or finding reported by a SAST tool.

Attributes:

Name	Type	Description
file	str	The name of the file where the defect was found.
checker	str	The name of the checker or rule that reported the defect.
category	str	The category of the checker (e.g., security, performance).
cwe	CWE	The CWE associated with the defect.
data	tuple[Any]	A tuple containing the raw data for the defect.

Initialize a Defect instance.

Parameters:

Name	Type	Description	Default
file	str	The file path of the defect.	required
checker	str	The name of the rule/checker.	required
category	str	The category of the checker.	required
cwe	CWE	The CWE associated with the defect.	required
data	tuple[Any]	Raw data from the SAST tool for this defect.	required

Methods:

Name	Description
__repr__	Return a developer-friendly string representation of the Defect.

file instance-attribute

file = file

checker instance-attribute

checker = checker

category instance-attribute

category = category

cwe instance-attribute

cwe = cwe

data instance-attribute

data = data

__repr__

__repr__() -> str

Return a developer-friendly string representation of the Defect.

Returns:

Type	Description
str	A string showing the class name and key attributes of the defect.

AnalysisResult

AnalysisResult(
    name: str,
    lang: str,
    files: list[str],
    defects: list[Defect],
    time: float,
    loc: int,
    data: tuple[Any],
)

Bases: ABC

Abstract base class for holding the parsed results of a SAST analysis.

Attributes:

Name	Type	Description
name	str	The name of the analyzed project or dataset.
lang	str	The primary programming language analyzed.
files	list[str]	A list of files that were analyzed.
defects	list[Defect]	A list of Defect objects found.
time	float	The duration of the analysis in seconds.
loc	int	The number of lines of code analyzed.
data	tuple[Any]	A tuple containing raw data from the analysis.

Initialize an AnalysisResult instance.

Parameters:

Name	Type	Description	Default
name	str	The name of the analyzed project/dataset.	required
lang	str	The programming language of the code.	required
files	list[str]	A list of analyzed files.	required
defects	list[Defect]	A list of Defect objects.	required
time	float	The analysis duration in seconds.	required
loc	int	The lines of code analyzed.	required
data	tuple[Any]	Raw data from the SAST tool's output.	required

Methods:

Name	Description
__repr__	Return a developer-friendly string representation of the AnalysisResult.
load_from_output_dir	Load and parse analysis results from a specified directory.
load_from_output_dirs	Load and parse analysis results from multiple directories.
checker_to_category	Get the category for a given checker name.
stats_by_checkers	Calculate statistics on defects, grouped by checker.
stats_by_categories	Calculate statistics on defects, grouped by category.
stats_by_files	Calculate statistics on defects, grouped by file.
stats_by_cwes	Calculate statistics on defects, grouped by CWE ID.

name instance-attribute

name = name

lang instance-attribute

lang = lang

files instance-attribute

files = files

defects instance-attribute

defects = defects

time instance-attribute

time = time

loc instance-attribute

loc = loc

data instance-attribute

data = data

__repr__

__repr__() -> str

Return a developer-friendly string representation of the AnalysisResult.

Returns:

Type	Description
str	A string showing key metrics of the analysis.

load_from_output_dir abstractmethod classmethod

load_from_output_dir(output_dir: Path) -> Self

Load and parse analysis results from a specified directory.

This method must be implemented by subclasses to handle the specific output files of a SAST tool.

Parameters:

Name	Type	Description	Default
output_dir	Path	The directory containing the raw analysis output files.	required

Returns:

Type	Description
Self	An instance of the AnalysisResult subclass.

load_from_output_dirs classmethod

load_from_output_dirs(output_dirs: list[str]) -> list[Self]

Load and parse analysis results from multiple directories.

Parameters:

Name	Type	Description	Default
output_dirs	list[str]	An iterable of directory paths containing results.	required

Returns:

Type	Description
list[Self]	A list of AnalysisResult subclass instances.

checker_to_category

checker_to_category(checker: str) -> str

Get the category for a given checker name.

Parameters:

Name	Type	Description	Default
checker	str	The name of the checker.	required

Returns:

Type	Description
str	The category string, or "NONE" if not found.

stats_by_checkers

stats_by_checkers() -> dict

Calculate statistics on defects, grouped by checker.

Returns:

Type	Description
dict	A dictionary where keys are checker names and values are dicts
dict	containing defect counts and affected files.

stats_by_categories

stats_by_categories() -> dict

Calculate statistics on defects, grouped by category.

Returns:

Type	Description
dict	A dictionary where keys are category names and values are dicts
dict	containing counts and checker lists.

stats_by_files

stats_by_files() -> dict

Calculate statistics on defects, grouped by file.

Returns:

Type	Description
dict	A dictionary where keys are filenames and values are dicts
dict	containing defect counts and the checkers that fired.

stats_by_cwes

stats_by_cwes() -> dict

Calculate statistics on defects, grouped by CWE ID.

Returns:

Type	Description
dict	A dictionary where keys are CWE IDs and values are dicts
dict	containing defect counts and affected files.