ScubaTrace

ScubaTrace: Source-level code analysis toolkit for SAST, context engineering, and AI coding.

ScubaTrace is a code analysis toolkit that leverages tree-sitter, Joern and LSP (Language Server Protocol) to provide parsing, analysis, and context extraction capabilities for multiple programming languages.

Unlike most traditional static analysis tools that rely on compilation to extract Intermediate Representation (IR) for code analysis, ScubaTrace delivers analysis capabilities even when code repositories are incomplete or unable to compile. This resilience makes it particularly valuable for scenarios where traditional analysis approaches would fail, enabling developers and security researchers to gain insights from code that might otherwise be inaccessible to conventional static analysis methodologies.

Rather than being an end-to-end program analysis framework, ScubaTrace serves as a foundational toolkit that empowers developers to build solutions for IDE development, AI-powered coding tools, and SAST (Static Application Security Testing).

ScubaTrace 是一个代码分析工具包，利用 tree-sitter、Joern 和 LSP（Language Server Protocol）为多种编程语言提供解析、分析和上下文提取能力。

与大多数依赖编译来提取中间表示（IR）以进行代码分析的传统静态分析工具不同，ScubaTrace 即使在代码仓库不完整或无法编译的情况下，也能提供分析能力。这种高韧性使其在传统分析方法失效的场景中尤为有价值，能够帮助开发者和安全研究人员从那些常规静态分析方法难以处理的代码中获取洞察。

ScubaTrace 并不是一个端到端的程序分析框架，而是一个基础性工具包，旨在帮助开发者构建用于 IDE 开发、AI 驱动的编码工具以及 SAST（Static Application Security Testing）的解决方案。

Features

• Multi-Language Support
• No Need To Compile
• Statement-Based AST Abstraction
• Call Graph
• Control Flow Graph
• Data/Control Dependency Graph
• References Inference
• CPG Based Multi-Granularity Slicing
• Built on Tree-sitter and LSP

Install

pip install scubatrace

Note

If you encounter a pygraphviz installation failure during pip install, you need to install the Graphviz development package. You can install it using the following command:

# For Debian/Ubuntu
apt install libgraphviz-dev
# For macOS, Ref: https://pygraphviz.github.io/documentation/stable/install.html#homebrew
brew install graphviz

Supported Languages

ScubaTrace supports multiple programming languages, including:

Language	Language Server	Tree-sitter Parser	Maturity
C/C++	clangd	tree-sitter-cpp	High
Java	Eclipse JDT LS	tree-sitter-java	High
Python	Pyright	tree-sitter-python	High
JavaScript	typescript-language-server	tree-sitter-javascript	Medium
Go	gopls	tree-sitter-go	Medium
Rust	Rust Analyzer	tree-sitter-rust	Medium
Ruby	Solargraph	tree-sitter-ruby	Low
Swift	SourceKit-LSP	tree-sitter-swift	Low
C#	OmniSharp	tree-sitter-c-sharp	Low
PHP	phpactor	tree-sitter-php	Low

Usage

Initialize a ScubaTrace Project

import scubatrace

# Initialize a ScubaTrace Project
# language can be set to one of the following:
# scubatrace.language.[C, JAVA, PYTHON, JAVASCRIPT, GO, RUST, RUBY, PHP, CSHARP, SWIFT]
project = scubatrace.Project.create("path/to/your/codebase", language=scubatrace.language.C)

Note

Incomplete or broken codebases may cause parsing errors that could result in inaccurate analysis results.

Retrieve Code Entities

# Get a file from the project
file = project.files["relative/path/to/your/file.c"]

# Get a function from the file
function = file.functions[0]
print(f"Function Name: {function.name}")
print(f"Source Code: {function.text}")

# Get the function's callers and print their names and callsites
callers = function.callers
for caller, callsites in callers.items():
    print(f"Caller: {caller.name}")
    for callsite in callsites:
        print(f"  Callsite: {callsite.text}")

# Get the first statement in file line
statement = file.statements_by_line(10)[0]

# Get the first variable in statement
variable = statement.variables[0]
print(f"Variable: {variable.name}")

# Get tree-sitter node in a file/function/statement
file_node = file.node
function_node = function.node
statement_node = statement.node

Perform Analysis

# Find the pre/post statements in control flow
pre_statements_in_control_flow = statement.pre_controls
post_statements_in_control_flow = statement.post_controls

# Find the pre/post data dependencies of a variable
pre_data_dependencies = variable.pre_data_dependents
post_data_dependencies = variable.post_data_dependents

# Find the definitions/references of a variable
definitions = variable.definitions
references = variable.references

# Perform slicing in a function based on specified lines
# Configure the slicing with control depth and data-dependent depth
criteria_lines = [10, 12, 18]
sliced_statements = function.slice_by_lines(
    lines=criteria_lines, control_depth=5, data_dependent_depth=8
)

ScubaTrace with Joern

# Initialize a ScubaTrace Project with Joern
project = scubatrace.Project.create(
    "path/to/your/codebase",
    language=scubatrace.language.C,
    joern_config=scubatrace.JoernConfig(
        enable_joern=True,
    ),
)

For more detailed information, refer to the Documentation.