# yandex/gixy architecture

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

- Interactive diagram: https://gitdiagram.com/yandex/gixy
- Repository: https://github.com/yandex/gixy

## Overview

##### Main Components
- Command-Line Interface (CLI) – Found under gixy/cli, this component handles user input and argument parsing.
- Core Engine – The gixy/core package contains the central logic for configuration management, exception handling, context processing, and issue reporting.
- Parser – Under gixy/parser, this module is responsible for processing raw Nginx config files and transforming them into a format that the core can use.
- Plugin System – The gixy/plugins package houses individual plugins (e.g., ssrf.py, alias_traversal.py) that implement specific vulnerability checks.
- Directives Handling – Found under gixy/directives, it processes and interprets Nginx directives.
- Formatters – The gixy/formatters module is responsible for output representation, including JSON and console formatting; it is also responsible for rendering template-based reports.
- Utilities and Support – Additional helper functions located in gixy/utils and other submodules.
- Testing and Validation – Though not part of the production design, the tests directory shows how each component (parser, plugins, directives) is validated, reinforcing the design’s modularity.

##### Relationships and Interactions
- The CLI component (gixy/cli/main.py) acts as the entry point, capturing user commands and passing configuration file paths to the core.
- The Core Engine reads the Nginx configuration using modules in the parser, then manages the analysis workflow.
- The Parser processes the config into a structured representation that the Core Engine and plugins can work with.
- The Plugin Manager (in gixy/core/plugins_manager.py) dynamically loads and iterates over available plugins.
- Each Plugin applies its specific rule checks against the structured configuration data and reports any issues.
- The Formatters take the analysis output and render it into human-readable formats (console output, JSON, etc.) before it is displayed to the user.
- Directives processing ensures that Nginx-specific configuration commands are correctly interpreted for security validations.
- Dependencies and external libraries (notably Python 2.7/3.x compatibility, possibly Jinja2 for templates in formatters) form part of the stack.

##### Architectural Patterns and Design Principles
- Plugin Architecture: Gixy is built in a modular way where independent plugins each check for a specific vulnerability. The Plugin Manager orchestrates these.
- Separation of Concerns: The CLI, core engine, parser, plugins, and formatters are clearly separated into different packages, allowing easier maintenance and extension.
- Testability: The existence of a comprehensive tests directory indicates unit testing is an integral part of the project, ensuring each layer can be validated independently.

##### Including Relevant Technologies and Frameworks
- Python is the primary language.
- The tool uses standard modules as well as third-party libraries (e.g., Jinja2 for templating in the formatters).
- Docker support is provided (see Dockerfile and instructions in the README) to run Gixy as a container for environments where installation might be more controlled.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        CLI_Main["Command-Line Interface: Main"]:::interface
        CLI_ArgParser["Command-Line Interface: ArgParser"]:::interface
    end

    %% Processing Layer
    subgraph "Processing Layer"
        %% Parser Subsystem
        subgraph "Parser"
            Nginx_Parser["Nginx Parser"]:::processing
            Raw_Parser["Raw Parser"]:::processing
        end

        %% Directives Handling Subsystem
        subgraph "Directives Handling"
            Block_Directive["Block Directive"]:::processing
            Directive["Directive"]:::processing
        end

        %% Core Engine Subsystem
        subgraph "Core Engine"
            Core_Manager["Core Manager"]:::processing
            Core_PluginsManager["Plugins Manager"]:::processing
        end

        %% Plugin System Subsystem
        subgraph "Plugin System"
            SSRF_Plugin["SSRF Plugin"]:::plugin
            Alias_Traversal_Plugin["Alias Traversal Plugin"]:::plugin
        end

        %% Utilities
        subgraph "Utilities"
            Text_Utils["Text Utils"]:::processing
        end
    end

    %% Output Layer
    subgraph "Output Layer"
        Formatters_Base["Base Formatter"]:::output
        Formatters_Console["Console Formatter"]:::output
        Formatters_JSON["JSON Formatter"]:::output
        FormatTemplates["Templates"]:::output
    end

    %% Testing Layer (Non-production)
    subgraph "Testing and Validation"
        Tests["Tests Directory"]:::testing
    end

    %% External Deployment (Docker)
    Docker["Docker Container"]:::external

    %% Data Flow Connections
    CLI_Main -->|"input"| CLI_ArgParser
    CLI_ArgParser -->|"provides config path"| Nginx_Parser
    CLI_ArgParser -->|"provides config path"| Raw_Parser

    Nginx_Parser -->|"parsed config"| Core_Manager
    Raw_Parser -->|"parsed config"| Core_Manager
    Block_Directive -->|"interprets directives"| Nginx_Parser
    Directive -->|"interprets directives"| Nginx_Parser

    Text_Utils ---|"support functions"| Nginx_Parser
    Text_Utils ---|"support functions"| Core_Manager

    Core_Manager -->|"loads plugins"| Core_PluginsManager
    Core_PluginsManager -->|"invokes checks"| SSRF_Plugin
    Core_PluginsManager -->|"invokes checks"| Alias_Traversal_Plugin
    SSRF_Plugin -->|"reports issues"| Core_Manager
    Alias_Traversal_Plugin -->|"reports issues"| Core_Manager

    Core_Manager -->|"formatted report"| Formatters_Base
    Core_Manager -->|"formatted report"| Formatters_Console
    Core_Manager -->|"formatted report"| Formatters_JSON

    Formatters_Base -->|"renders using"| FormatTemplates
    Formatters_Console -->|"renders using"| FormatTemplates
    Formatters_JSON -->|"renders using"| FormatTemplates

    %% Docker integration for deployment (entry and exit)
    Docker -->|"runs environment"| CLI_Main
    Formatters_Console -->|"output to user"| Docker

    %% Testing connections (informational)
    Tests ---|"validates"| Nginx_Parser
    Tests ---|"validates"| Core_Manager
    Tests ---|"validates"| SSRF_Plugin
    Tests ---|"validates"| Block_Directive

    %% Click Events for CLI Layer
    click CLI_Main "https://github.com/yandex/gixy/blob/master/gixy/cli/main.py"
    click CLI_ArgParser "https://github.com/yandex/gixy/blob/master/gixy/cli/argparser.py"

    %% Click Events for Core Engine Layer
    click Core_Manager "https://github.com/yandex/gixy/blob/master/gixy/core/manager.py"
    click Core_PluginsManager "https://github.com/yandex/gixy/blob/master/gixy/core/plugins_manager.py"

    %% Click Events for Parser Layer
    click Nginx_Parser "https://github.com/yandex/gixy/blob/master/gixy/parser/nginx_parser.py"
    click Raw_Parser "https://github.com/yandex/gixy/blob/master/gixy/parser/raw_parser.py"

    %% Click Events for Plugin System
    click SSRF_Plugin "https://github.com/yandex/gixy/blob/master/gixy/plugins/ssrf.py"
    click Alias_Traversal_Plugin "https://github.com/yandex/gixy/blob/master/gixy/plugins/alias_traversal.py"

    %% Click Events for Directives Handling
    click Block_Directive "https://github.com/yandex/gixy/blob/master/gixy/directives/block.py"
    click Directive "https://github.com/yandex/gixy/blob/master/gixy/directives/directive.py"

    %% Click Events for Formatters
    click Formatters_Base "https://github.com/yandex/gixy/blob/master/gixy/formatters/base.py"
    click Formatters_Console "https://github.com/yandex/gixy/blob/master/gixy/formatters/console.py"
    click Formatters_JSON "https://github.com/yandex/gixy/blob/master/gixy/formatters/json.py"
    click FormatTemplates "https://github.com/yandex/gixy/tree/master/gixy/formatters/templates"

    %% Click Event for Utilities
    click Text_Utils "https://github.com/yandex/gixy/blob/master/gixy/utils/text.py"

    %% Click Event for Testing
    click Tests "https://github.com/yandex/gixy/tree/master/tests"

    %% Styles
    classDef interface fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef processing fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
    classDef plugin fill:#F5CBA7,stroke:#AF601A,stroke-width:2px;
    classDef output fill:#FAD7A0,stroke:#B9770E,stroke-width:2px;
    classDef testing fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#5B2C6F,stroke-width:2px;
```
