# hikaruegashira/vulnhuntrs architecture

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

- Interactive diagram: https://gitdiagram.com/hikaruegashira/vulnhuntrs
- Repository: https://github.com/hikaruegashira/vulnhuntrs

## Overview

##### Main Components
- CLI & Entry Point: Start with src/main.rs and the build scripts (Cargo.toml, build.rs) that boot the tool.
- Analyzer Engine: Emphasize src/analyzer.rs which is likely the core logic for vulnerability detection.
- Language Parsing Module: Include src/parser.rs along with the tree-sitter grammar directories (tree-sitter-go, tree-sitter-java, etc.). These components provide language-specific parsing capabilities.
- Prompt Management & LLM Interaction: Represent the prompts subdirectory (src/prompts) that contains files like analysis.rs and evaluator.rs. This module likely builds requests to and processes responses from the LLM.
- Repository and Response Handling: Add components like src/repo.rs and src/response.rs which handle retrieval of code repositories and formatting of vulnerability reports.
- Security Patterns: Include src/security_patterns.rs that might define or match known vulnerability signatures.
- Documentation & Configuration: Although not part of runtime, include a section for docs (stack graphs, testing documents) and configuration files (e.g., .devcontainer, .gitignore) that influence how the system is developed and deployed.

##### Relationships and Interactions
- The CLI (src/main.rs) accepts a target project path (with -r option) and delegates analysis to the Analyzer Engine.
- The Analyzer calls the Parser to generate abstract representations of the code, leveraging tree-sitter modules for multiple programming languages.
- As part of the analysis, the tool uses defined security patterns and static analysis strategies (src/security_patterns.rs) to identify vulnerabilities.
- For vulnerability evaluation, the Analyzer interacts with the Prompt Management module which assembles prompts and communicates with external LLM services (such as gpt-4o-0806 and gpt-4o-mini, as noted in the README).
- The Response Module formats the output reports which are then printed or stored.
- The Repository Module (src/repo.rs) abstracts file system operations and potentially handles cloning or reading from the target project repository.

##### Architectural Patterns/Design Principles
- Separation of Concerns: The codebase is modularized into components (CLI, Analyzer, Parser, Prompts, etc.) to ensure clear boundaries between data collection, processing, and reporting.
- Extensibility: With directories for different tree-sitter languages and prompt configurations, the design allows for adding new language support or tweaking the LLM integration.
- Testability: The snapshots directory showing serialized responses indicates that snapshot tests enforce that changes in vulnerability detection are caught.
- Inversion of Control: By abstracting language-specific parsing and LLM interactions, components can be swapped or extended with minimal changes to core logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Engine
    subgraph "Core Engine"
        CLI["CLI & Entry Point"]:::core
        Analyzer["Analyzer Engine"]:::core
        Parser["Language Parser"]:::core
        Prompts["Prompt Management"]:::core
        AnalysisPrompt["Analysis Prompt"]:::core
        Evaluator["LLM Evaluator"]:::core
    end

    %% Language Support Modules
    subgraph "Language Support Modules"
        TSGo["Tree-Sitter: Go"]:::lang
        TSJava["Tree-Sitter: Java"]:::lang
        TSJavaScript["Tree-Sitter: JavaScript"]:::lang
        TSPython["Tree-Sitter: Python"]:::lang
        TSRust["Tree-Sitter: Rust"]:::lang
        TSTypescript["Tree-Sitter: TypeScript"]:::lang
    end

    %% External Services
    subgraph "External Services"
        LLM["LLM API Service"]:::external
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        Repository["Repository Handling"]:::support
        Response["Response Handling"]:::support
        SecPatterns["Security Patterns"]:::support
        Docs["Documentation & Configuration"]:::support
    end

    %% Example Applications
    subgraph "Example Applications"
        PythonApp["Python Vulnerable App"]:::example
        RustApp["Rust Vulnerable App"]:::example
    end

    %% Relationships and Data Flow
    CLI -->|"triggers"| Analyzer
    Analyzer -->|"parses code"| Parser
    Parser -->|"returns AST"| Analyzer
    Analyzer -->|"evaluates vulnerabilities"| SecPatterns
    Analyzer -->|"retrieves repo"| Repository
    Analyzer -->|"assembles prompt"| Prompts
    Prompts -->|"sends request"| LLM
    LLM -->|"returns analysis"| Prompts
    Prompts -->|"formats report"| Response
    Parser -->|"uses"| TSGo
    Parser -->|"uses"| TSJava
    Parser -->|"uses"| TSJavaScript
    Parser -->|"uses"| TSPython
    Parser -->|"uses"| TSRust
    Parser -->|"uses"| TSTypescript
    Docs --- CLI
    Docs --- Analyzer

    %% Example Applications are used for testing and demo
    Analyzer --- PythonApp
    Analyzer --- RustApp

    %% Internal Prompt Breakdown
    Prompts -->|"builds analysis request"| AnalysisPrompt
    Prompts -->|"evaluates vulnerability"| Evaluator

    %% Click Events
    click CLI "https://github.com/hikaruegashira/vulnhuntrs/blob/main/src/main.rs"
    click CLI "https://github.com/hikaruegashira/vulnhuntrs/blob/main/Cargo.toml"
    click CLI "https://github.com/hikaruegashira/vulnhuntrs/blob/main/build.rs"
    click Analyzer "https://github.com/hikaruegashira/vulnhuntrs/blob/main/src/analyzer.rs"
    click Parser "https://github.com/hikaruegashira/vulnhuntrs/blob/main/src/parser.rs"
    click TSGo "https://github.com/hikaruegashira/vulnhuntrs/tree/main/tree-sitter-go"
    click TSJava "https://github.com/hikaruegashira/vulnhuntrs/tree/main/tree-sitter-java"
    click TSJavaScript "https://github.com/hikaruegashira/vulnhuntrs/tree/main/tree-sitter-javascript"
    click TSPython "https://github.com/hikaruegashira/vulnhuntrs/tree/main/tree-sitter-python"
    click TSRust "https://github.com/hikaruegashira/vulnhuntrs/tree/main/tree-sitter-rust"
    click TSTypescript "https://github.com/hikaruegashira/vulnhuntrs/tree/main/tree-sitter-typescript"
    click Prompts "https://github.com/hikaruegashira/vulnhuntrs/tree/main/src/prompts"
    click AnalysisPrompt "https://github.com/hikaruegashira/vulnhuntrs/blob/main/src/prompts/analysis.rs"
    click Evaluator "https://github.com/hikaruegashira/vulnhuntrs/blob/main/src/prompts/evaluator.rs"
    click Repository "https://github.com/hikaruegashira/vulnhuntrs/blob/main/src/repo.rs"
    click Response "https://github.com/hikaruegashira/vulnhuntrs/blob/main/src/response.rs"
    click SecPatterns "https://github.com/hikaruegashira/vulnhuntrs/blob/main/src/security_patterns.rs"
    click Docs "https://github.com/hikaruegashira/vulnhuntrs/tree/main/docs"
    click PythonApp "https://github.com/hikaruegashira/vulnhuntrs/tree/main/example/python-vulnerable-app"
    click RustApp "https://github.com/hikaruegashira/vulnhuntrs/tree/main/example/rust-vulnerable-app"

    %% Styles
    classDef core fill:#BBE1FA,stroke:#1B4965,stroke-width:2px;
    classDef lang fill:#C4E7B2,stroke:#3F681C,stroke-width:2px;
    classDef external fill:#F4D35E,stroke:#EE964B,stroke-width:2px;
    classDef support fill:#CDF0EA,stroke:#2B7A78,stroke-width:2px;
    classDef example fill:#F0A6CA,stroke:#D72638,stroke-width:2px;
```
