# wh1t3p1g/tabby architecture

> Architecture diagram of the GitHub repository wh1t3p1g/tabby, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wh1t3p1g/tabby
- Repository: https://github.com/wh1t3p1g/tabby

## Overview

##### Project Type and Purpose
- This is an open-source static code analysis tool for Java (Tabby).
- It ingests JAR/WAR/CLASS files, builds a Code Property Graph (CPG) via Soot, and stores it in Neo4j for vulnerability hunting.

##### Main Components
a. Entry Point / CLI
- App.java / run.sh – command-line launcher
b. Configuration Layer
- GlobalConfiguration, SootConfiguration, AsyncConfiguration
- application.properties, settings.properties
c. File Collection & Scanning
- FileCollector → ClassInfoCollector → CallGraphCollector
- Uses Soot under the hood
d. Analysis Engine
- Core.Analysis (ActionWorker, SimpleTypeAnalysis)
- Analysis.Helper (SemanticHelper)
- Analysis.Switchers & PTA switchers (StmtSwitcher, TValueSwitcher)
- Model builders (CallEdgeBuilder, InvokeModel implementations)
e. Rule Engine
- JSON rule files (rules/*.json)
- TabbyRule, TagRule, XmlRule classes
f. Data Containers
- DataContainer (holds intermediate objects: ValueContainer, SimpleObject, MultiObject)
- RulesContainer (loaded rules)
g. Persistence Layer
- DAL.Repositories (AliasEdgeRepository, CallEdgeRepository, ClassRepository, etc.)
- DAL.Services (RelationshipsService, ClassRefService, MethodRefService)
- Neo4j graph database (external service)
h. Plugin Framework
- Plugins for jmod, jsp, xml (transfer, compile, parse)
- Extension points for additional file formats
i. External Dependencies
- Soot (static analysis)
- Neo4j + Cypher (graph storage & traversal)

##### Relationships & Data Flow
- Start: CLI/App reads Configuration → loads Rules from JSON
- FileCollector scans input artifacts → hands off to ClassInfoCollector
- CallGraphCollector uses Soot to build call graph, CPG nodes & edges
- Analysis Engine consumes CPG via Switchers & Models → populates DataContainer
- Rule Engine matches analysis results against loaded rules
- Findings & CPG are persisted using DAL.Repositories into Neo4j
- Neo4j’s path-finding extension serves advanced taint/vulnerability queries
- Plugins can inject pre-processing or additional graph data

##### Architectural Patterns & Principles
- Pipeline / staged processing (collector → scanner → analyzer → persister)
- Plugin-based extensibility (jmod, jsp, xml)
- Dependency inversion: core modules depend on abstractions (interfaces for models, repositories)
- Configuration-driven behavior (Spring Boot style, asynchronous tasks)

##### Detailed Callouts
- That Configurations drive Soot setup and async threading
- That DataContainer aggregates intermediate graph objects before persistence
- That Neo4j’s path finder extension executes Cypher queries for taint analysis
- Plugin interfaces clearly so new file-type parsers can be slotted in

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Point & Configuration Layer
    subgraph "Entry & Config" 
        direction TB
        App["App.java / run.sh"]:::config
        ConfigProps["application.properties\nsettings.properties"]:::config
        GlobalConfig["GlobalConfiguration"]:::config
        SootConfig["SootConfiguration"]:::config
        AsyncConfig["AsyncConfiguration"]:::config
    end

    %% File Collection & Scanning Layer
    subgraph "File Collection & Scanning"
        direction TB
        FileCollector["FileCollector"]:::core
        ClassInfoCollector["ClassInfoCollector"]:::core
        CallGraphCollector["CallGraphCollector"]:::core
        ClassInfoScanner["ClassInfoScanner"]:::core
        CallGraphScanner["CallGraphScanner"]:::core
    end

    %% Analysis Engine Layer
    subgraph "Analysis Engine" 
        direction TB
        ActionWorker["ActionWorker"]:::core
        SimpleTypeAnalysis["SimpleTypeAnalysis"]:::core
        SemanticHelper["SemanticHelper"]:::core
        CallEdgeBuilder["CallEdgeBuilder"]:::core
        DefaultInvokeModel["DefaultInvokeModel"]:::core
        StmtSwitcher["StmtSwitcher"]:::core
        ValueSwitcher["ValueSwitcher"]:::core
        TStmtSwitcher["TStmtSwitcher"]:::core
        TValueSwitcher["TValueSwitcher"]:::core
    end

    %% Rule Engine Layer
    subgraph "Rule Engine" 
        direction TB
        RulesJSON["rules/*.json"]:::data
        TabbyRule["TabbyRule"]:::data
        TagRule["TagRule"]:::data
        XmlRule["XmlRule"]:::data
    end

    %% Data Containers Layer
    subgraph "Data Containers" 
        direction TB
        DataContainer["DataContainer"]:::data
        RulesContainer["RulesContainer"]:::data
        ValueContainer["ValueContainer"]:::data
        SimpleObject["SimpleObject"]:::data
        MultiObject["MultiObject"]:::data
    end

    %% Persistence Layer & Database
    subgraph "Persistence & Database"
        direction TB
        AliasEdgeRepo["AliasEdgeRepository"]:::data
        CallEdgeRepo["CallEdgeRepository"]:::data
        ClassRepo["ClassRepository"]:::data
        ExtendEdgeRepo["ExtendEdgeRepository"]:::data
        HasEdgeRepo["HasEdgeRepository"]:::data
        InterfacesEdgeRepo["InterfacesEdgeRepository"]:::data
        MethodRepo["MethodRepository"]:::data
        RelationshipsService["RelationshipsService"]:::data
        ClassRefService["ClassRefService"]:::data
        MethodRefService["MethodRefService"]:::data
        Neo4j["Neo4j Database"]:::ext
    end

    %% Plugin Framework & External Dependencies
    subgraph "Plugins & External"
        direction TB
        JModPlugin["JModTransferPlugin"]:::config
        JspPlugin["JspCompilePlugin"]:::config
        XmlPlugin["XmlParsePlugin"]:::config
        Parser["Parser / MybatisParser"]:::config
        SootExt["Soot"]:::ext
    end

    %% Connections
    App -->|reads| GlobalConfig
    App -->|reads| SootConfig
    App -->|reads| AsyncConfig
    App -->|reads| ConfigProps

    App -->|launches| FileCollector
    FileCollector --> ClassInfoCollector
    ClassInfoCollector --> CallGraphCollector
    CallGraphCollector --> ActionWorker

    CallGraphCollector -->|uses| SootExt

    ActionWorker --> SimpleTypeAnalysis
    ActionWorker --> SemanticHelper
    SimpleTypeAnalysis --> CallEdgeBuilder
    CallEdgeBuilder --> DefaultInvokeModel
    DefaultInvokeModel --> StmtSwitcher
    DefaultInvokeModel --> ValueSwitcher
    StmtSwitcher --> TStmtSwitcher
    ValueSwitcher --> TValueSwitcher

    ActionWorker --> DataContainer
    RulesJSON --> TabbyRule
    RulesJSON --> TagRule
    RulesJSON --> XmlRule
    TabbyRule -->|loads into| RulesContainer
    RulesContainer --> ActionWorker

    ActionWorker -->|findings| DataContainer
    DataContainer --> AliasEdgeRepo
    DataContainer --> CallEdgeRepo
    DataContainer --> ClassRepo
    DataContainer --> ExtendEdgeRepo
    DataContainer --> HasEdgeRepo
    DataContainer --> InterfacesEdgeRepo
    DataContainer --> MethodRepo

    AliasEdgeRepo --> RelationshipsService
    CallEdgeRepo --> RelationshipsService
    ClassRepo --> ClassRefService
    MethodRepo --> MethodRefService

    RelationshipsService --> Neo4j
    ClassRefService --> Neo4j
    MethodRefService --> Neo4j

    JModPlugin --> FileCollector
    JspPlugin --> FileCollector
    XmlPlugin --> FileCollector
    Parser --> XmlPlugin

    %% Click Events
    click App "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/App.java"
    click ConfigProps "https://github.com/wh1t3p1g/tabby/blob/master/src/main/resources/application.properties"
    click ConfigProps "https://github.com/wh1t3p1g/tabby/blob/master/config/settings.properties"
    click GlobalConfig "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/config/GlobalConfiguration.java"
    click SootConfig "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/config/SootConfiguration.java"
    click AsyncConfig "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/config/AsyncConfiguration.java"
    click FileCollector "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/core/collector/FileCollector.java"
    click ClassInfoCollector "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/core/collector/ClassInfoCollector.java"
    click CallGraphCollector "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/core/collector/CallGraphCollector.java"
    click ClassInfoScanner "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/core/scanner/ClassInfoScanner.java"
    click CallGraphScanner "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/core/scanner/CallGraphScanner.java"
    click ActionWorker "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/analysis/ActionWorker.java"
    click SimpleTypeAnalysis "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/analysis/SimpleTypeAnalysis.java"
    click SemanticHelper "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/analysis/helper/SemanticHelper.java"
    click CallEdgeBuilder "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/analysis/model/CallEdgeBuilder.java"
    click DefaultInvokeModel "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/analysis/model/DefaultInvokeModel.java"
    click StmtSwitcher "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/analysis/switcher/StmtSwitcher.java"
    click ValueSwitcher "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/analysis/switcher/ValueSwitcher.java"
    click TStmtSwitcher "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/analysis/switcher/pta/TStmtSwitcher.java"
    click TValueSwitcher "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/analysis/switcher/pta/TValueSwitcher.java"
    click RulesJSON "https://github.com/wh1t3p1g/tabby/blob/master/rules/basicClasses.json"
    click TabbyRule "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/common/rule/TabbyRule.java"
    click TagRule "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/common/rule/TagRule.java"
    click XmlRule "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/common/rule/XmlRule.java"
    click DataContainer "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/core/container/DataContainer.java"
    click RulesContainer "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/core/container/RulesContainer.java"
    click ValueContainer "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/analysis/container/ValueContainer.java"
    click SimpleObject "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/analysis/data/SimpleObject.java"
    click MultiObject "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/analysis/data/MultiObject.java"
    click AliasEdgeRepo "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/dal/repository/AliasEdgeRepository.java"
    click CallEdgeRepo "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/dal/repository/CallEdgeRepository.java"
    click ClassRepo "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/dal/repository/ClassRepository.java"
    click ExtendEdgeRepo "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/dal/repository/ExtendEdgeRepository.java"
    click HasEdgeRepo "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/dal/repository/HasEdgeRepository.java"
    click InterfacesEdgeRepo "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/dal/repository/InterfacesEdgeRepository.java"
    click MethodRepo "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/dal/repository/MethodRepository.java"
    click RelationshipsService "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/dal/service/RelationshipsService.java"
    click ClassRefService "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/dal/service/ClassRefService.java"
    click MethodRefService "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/dal/service/MethodRefService.java"
    click JModPlugin "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/plugin/jmod/JModTransferPlugin.java"
    click JspPlugin "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/plugin/jsp/JspCompilePlugin.java"
    click XmlPlugin "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/plugin/xml/XmlParsePlugin.java"
    click Parser "https://github.com/wh1t3p1g/tabby/blob/master/src/main/java/tabby/plugin/xml/parser/Parser.java"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px
    classDef ext fill:#FFA500,stroke:#000,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px
```
