# grayddq/gscan architecture

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

- Interactive diagram: https://gitdiagram.com/grayddq/gscan
- Repository: https://github.com/grayddq/gscan

## Overview

##### Project type and purpose
- GScan is a command‑line, plugin‑based Linux host security scanning tool.
- Its goal is to automate a comprehensive “checklist” of intrusion‐forensic and security checks (file integrity, process anomalies, network connections, backdoors, rootkits, webshells, etc.) and aggregate results to reconstruct an attacker’s path.

##### File structure
- Top‑level:
- GScan.py – the main entrypoint/CLI driver
- db/ – on‑disk state (e.g., previous scan hashes)
- lib/:
- core/ – common utilities, argument parsing, global variables, data aggregation, IP geolocation
- egg/ – bundled Yara Python extensions for malware signature matching
- malware/ – flat text library of 100K+ malware signatures
- plugins/ – discrete scan modules (Host_Info, File_Analysis, Network_Analysis, etc.) and accompanying webshell Yara rules
- pic/ – screenshots for documentation
- log/ (created at runtime) – scan logs and final aggregated report

##### README for additional insights
- Lists 12 major categories of checks, each mapping to one or more plugin modules.
- Emphasizes Yara for signature matching and CentOS+Python2/3 compatibility.
- Mentions output directories and scheduling support for cron jobs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        GScan["CLI Driver\nGScan.py"]:::code
    end

    %% Core Layer
    subgraph "Core Layer"
        option["Argument Parsing\nlib/core/option.py"]:::code
        globalvar["Global Variables\nlib/core/globalvar.py"]:::code
        common["Common Utils\nlib/core/common.py"]:::code
        dataagg["Data Aggregation Engine\nlib/core/data_aggregation.py"]:::code
        ipapi["IP Geo API\nlib/core/ip/ip.py"]:::code
        ipdb["IP Geolocation DB\nlib/core/ip/17monipdb.dat"]:::datasrc
    end

    %% Plugin Modules
    subgraph "Plugin Modules"
        Host_Info["Plugin: Host_Info.py"]:::code
        File_Analysis["Plugin: File_Analysis.py"]:::code
        File_Check["Plugin: File_Check.py"]:::code
        Proc_Analysis["Plugin: Proc_Analysis.py"]:::code
        Network_Analysis["Plugin: Network_Analysis.py"]:::code
        Rootkit_Analysis["Plugin: Rootkit_Analysis.py"]:::code
        Backdoor_Analysis["Plugin: Backdoor_Analysis.py"]:::code
        SSHAnalysis["Plugin: SSHAnalysis.py"]:::code
        Webserver["Plugin: Webserver.py"]:::code
        Webshell_Analysis["Plugin: Webshell_Analysis.py"]:::code
        webshell_rules["Webshell Yara Rules\ndir: lib/plugins/webshell_rule/"]:::datasrc
    end

    %% Signature Stores
    subgraph "Signature Stores"
        malware["Malware Signatures\nlib/malware/"]:::datasrc
        yara["Yara Engine\nlib/egg/.egg"]:::datasrc
    end

    %% Runtime DB
    subgraph "Runtime DB"
        dbtxt["db.txt\n(db/db.txt)"]:::datasrc
        hashtxt["hash_db.txt\n(db/hash_db.txt)"]:::datasrc
    end

    %% OS Interfaces
    OS["Operating System Interfaces\n(fs, proc, net)"]:::os

    %% Output/Logs
    log["Log Directory\n./log"]:::output

    %% Connections
    GScan -->|"parse args"| option
    GScan -->|"set globals"| globalvar
    GScan -->|"load state"| dbtxt
    GScan -->|"load state"| hashtxt
    GScan -->|"invoke core utils"| common
    GScan -->|"invoke data agg"| dataagg
    GScan -->|"invoke plugins"| Host_Info
    GScan -->|"invoke plugins"| File_Analysis
    GScan -->|"invoke plugins"| File_Check
    GScan -->|"invoke plugins"| Proc_Analysis
    GScan -->|"invoke plugins"| Network_Analysis
    GScan -->|"invoke plugins"| Rootkit_Analysis
    GScan -->|"invoke plugins"| Backdoor_Analysis
    GScan -->|"invoke plugins"| SSHAnalysis
    GScan -->|"invoke plugins"| Webserver
    GScan -->|"invoke plugins"| Webshell_Analysis

    %% Plugins dependencies
    Host_Info --> common
    File_Analysis --> common
    File_Check --> common
    Proc_Analysis --> common
    Network_Analysis --> common
    Rootkit_Analysis --> common
    Backdoor_Analysis --> common
    SSHAnalysis --> common
    Webserver --> common
    Webshell_Analysis --> common

    Host_Info --> dataagg
    File_Analysis --> dataagg
    File_Check --> dataagg
    Proc_Analysis --> dataagg
    Network_Analysis --> dataagg
    Rootkit_Analysis --> dataagg
    Backdoor_Analysis --> dataagg
    SSHAnalysis --> dataagg
    Webserver --> dataagg
    Webshell_Analysis --> dataagg

    %% Plugins data sources
    Host_Info --> malware
    File_Analysis --> malware
    File_Check --> malware
    Proc_Analysis --> yara
    Network_Analysis --> yara
    Rootkit_Analysis --> yara
    Backdoor_Analysis --> yara
    SSHAnalysis --> yara
    Webserver --> yara
    Webshell_Analysis --> webshell_rules

    %% Plugins OS
    Host_Info --> OS
    File_Analysis --> OS
    File_Check --> OS
    Proc_Analysis --> OS
    Network_Analysis --> OS
    Rootkit_Analysis --> OS
    Backdoor_Analysis --> OS
    SSHAnalysis --> OS
    Webserver --> OS
    Webshell_Analysis --> OS

    %% Aggregation and output
    dataagg -->|"aggregate findings"| log
    dataagg -->|"update state"| dbtxt
    dataagg -->|"update state"| hashtxt

    %% Click Events
    click GScan "https://github.com/grayddq/gscan/blob/master/GScan.py"
    click option "https://github.com/grayddq/gscan/blob/master/lib/core/option.py"
    click globalvar "https://github.com/grayddq/gscan/blob/master/lib/core/globalvar.py"
    click common "https://github.com/grayddq/gscan/blob/master/lib/core/common.py"
    click dataagg "https://github.com/grayddq/gscan/blob/master/lib/core/data_aggregation.py"
    click ipapi "https://github.com/grayddq/gscan/blob/master/lib/core/ip/ip.py"
    click ipdb "https://github.com/grayddq/gscan/blob/master/lib/core/ip/17monipdb.dat"
    click yara "https://github.com/grayddq/gscan/blob/master/lib/egg/yara_python-3.5.0-py2.6-linux-2.32-x86_64.egg/yara.py"
    click malware "https://github.com/grayddq/gscan/tree/master/lib/malware/"
    click webshell_rules "https://github.com/grayddq/gscan/tree/master/lib/plugins/webshell_rule/"
    click Host_Info "https://github.com/grayddq/gscan/blob/master/lib/plugins/Host_Info.py"
    click File_Analysis "https://github.com/grayddq/gscan/blob/master/lib/plugins/File_Analysis.py"
    click File_Check "https://github.com/grayddq/gscan/blob/master/lib/plugins/File_Check.py"
    click Proc_Analysis "https://github.com/grayddq/gscan/blob/master/lib/plugins/Proc_Analysis.py"
    click Network_Analysis "https://github.com/grayddq/gscan/blob/master/lib/plugins/Network_Analysis.py"
    click Rootkit_Analysis "https://github.com/grayddq/gscan/blob/master/lib/plugins/Rootkit_Analysis.py"
    click Backdoor_Analysis "https://github.com/grayddq/gscan/blob/master/lib/plugins/Backdoor_Analysis.py"
    click SSHAnalysis "https://github.com/grayddq/gscan/blob/master/lib/plugins/SSHAnalysis.py"
    click Webserver "https://github.com/grayddq/gscan/blob/master/lib/plugins/Webserver.py"
    click Webshell_Analysis "https://github.com/grayddq/gscan/blob/master/lib/plugins/Webshell_Analysis.py"

    %% Styles
    classDef code fill:#AED6F1,stroke:#217DBB,color:#000;
    classDef datasrc fill:#ABEBC6,stroke:#28B463,color:#000;
    classDef os fill:#D5DBDB,stroke:#AAAAAA,color:#000;
    classDef output fill:#F9E79F,stroke:#B7950B,color:#000;
```
