# flouksac/onesoc architecture

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

- Interactive diagram: https://gitdiagram.com/flouksac/onesoc
- Repository: https://github.com/flouksac/onesoc

## Overview

##### Project type and purpose
- OneSOC is a Python-based CLI framework for automating SOC (Security Operations Center) deployment.
- It follows an MVC-like structure (Controller / Model / View) and interfaces with external services (Wazuh, SELKS, Docker containers, OS services).

##### File structure
- Top-level scripts & configs:
- run.sh, run_linux.sh, run_macos.sh, run_windows.ps1 – OS-specific bootstrap wrappers
- config.yaml, requirements.txt – configuration and dependencies
- src/main.py – CLI entry point
- MVC directories under src/Controller, src/Model, src/View
- DesignPattern holds a singleton helper
- Utils holds environment inspection modules (hardware, OS, services)
- Controller is subdivided into ControllerService (managing Wazuh components) and ControllerDocker (managing SELKS container)

##### README for additional insights
- 5 actions (Info, Health-Check, Install, Configure, Repair) drive main_controller
- Core components: Wazuh manager, indexer, dashboard; SELKS/Suricata/ELK; future additions
- Supports cross-platform bootstrap with Python venv or containers

a. Main components
- CLI Application (Python/virtualenv)
– Entry: src/main.py → View (main_view.py) + Parser → Controller (main_controller)
- Controller layer
– main_controller orchestrates user actions → delegates to:
· ServiceControllers (wazuh_server, wazuh_indexer, wazuh_dashboard, wazuh_agent)
· DockerControllers (SELKS via selks_controller)
– abstract_component_controller defines the common interface
- Model layer
– main_model holds global state
– loaderYAML reads config.yaml → ModelObjects (component, option, action, platform)
- Utility services
– os_info, hardware_info, service_info gather environment data
- External systems
– OS & system services (package manager, systemd, networking)
– Docker engine (for SELKS container)
– Wazuh components (manager, indexer, dashboard)
– SELKS stack (Suricata, Elasticsearch, Logstash, Kibana, Arkime)

b. Relationships & data flow
1. User invokes run_*.sh or python src/main.py → environment setup → CLI
2. CLI Parser interprets flags and passes control to main_controller
3. main_controller loads config via loaderYAML → populates ModelObjects
4. Based on action (Install/Info/Configure), main_controller calls appropriate ServiceController or DockerController
5. Controller uses Utils modules to inspect system, then calls OS commands or Docker API
6. Upon completion, Controller sends status back to View for display

c. Architectural patterns & principles
- MVC separation: Controllers orchestrate, Models hold data, View handles I/O
- Template Method: abstract_component_controller defines steps common to all components (install, configure, info)
- Singleton: one global config/manager instance via DesignPattern.singleton
- Strategy-style branching: ServiceController vs DockerController

d. Key technologies & frameworks
- Python 3.10+ with virtualenv
- PyYAML for config parsing
- Docker SDK for Python (in ControllerDocker)
- Standard libraries (subprocess, logging)
- Shell/Powershell wrappers for cross-platform bootstrapping

##### Detailed capture of essential elements
- ControllerService subtype
- Abstract_component_controller as base class
- LoaderYAML feeding into main_model and ModelObjects
- OS vs container flow: e.g., ServiceController calls apt/yum vs DockerController calls Docker API

Summary:
- Top layer: User & CLI entrypoint
- Next: Parser & View
- Middle: Controller layer (split into Service vs Docker)
- Next: Model & Config loader
- Bottom: Utils and External systems (OS, Docker, Wazuh, SELKS stack)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Bootstrap Wrappers
    subgraph "Bootstrap Wrappers"
        WR1["run.sh"]:::config
        WR2["run_linux.sh"]:::config
        WR3["run_macos.sh"]:::config
        WR4["run_windows.ps1"]:::config
    end
    WR1 --> CLI
    WR2 --> CLI
    WR3 --> CLI
    WR4 --> CLI

    %% CLI Layer
    CLI["CLI Application"]:::internal
    Parser["Parser"]:::internal
    View["View (Output/Status Display)"]:::internal
    CLI --> Parser
    Parser --> MainController
    MainController --> View

    %% Controller Layer
    subgraph "Controller Layer"
        MainController["Main Controller"]:::internal
        AbstractController["Abstract Component Controller"]:::internal

        subgraph "Service Controllers"
            AbstractService["Abstract Service Controller"]:::internal
            WazuhServer["Wazuh Server Controller"]:::internal
            WazuhIndexer["Wazuh Indexer Controller"]:::internal
            WazuhDashboard["Wazuh Dashboard Controller"]:::internal
            WazuhAgent["Wazuh Agent Controller"]:::internal
        end

        subgraph "Docker Controllers"
            AbstractDocker["Abstract Docker Controller"]:::internal
            SELKSController["SELKS Controller"]:::internal
        end

        HostController["Host Controller"]:::internal
        ListController["List Controller"]:::internal

        MainController --> AbstractController
        MainController --> AbstractService
        AbstractService --> WazuhServer
        AbstractService --> WazuhIndexer
        AbstractService --> WazuhDashboard
        AbstractService --> WazuhAgent
        MainController --> AbstractDocker
        AbstractDocker --> SELKSController
        MainController --> HostController
        MainController --> ListController
    end

    %% Model Layer
    subgraph "Model Layer"
        LoaderYAML["YAML Loader"]:::config
        MainModel["Global Model"]:::internal
        subgraph "ModelObjects"
            ActionObj["Action Object"]:::internal
            ComponentObj["Component Object"]:::internal
            OptionObj["Option Object"]:::internal
            PlatformObj["Platform Object"]:::internal
        end
        MainController --> LoaderYAML
        LoaderYAML --> MainModel
        LoaderYAML --> ActionObj
        LoaderYAML --> ComponentObj
        LoaderYAML --> OptionObj
        LoaderYAML --> PlatformObj
    end

    %% Utilities
    subgraph "Utils"
        HardwareInfo["Hardware Info"]:::internal
        OSInfo["OS Info"]:::internal
        ServiceInfo["Service Info"]:::internal
        MainController --> HardwareInfo
        MainController --> OSInfo
        MainController --> ServiceInfo
    end

    %% Configuration & Dependencies
    subgraph "Configuration"
        ConfigYAML["config.yaml"]:::config
        Requirements["requirements.txt"]:::config
        CLI --> ConfigYAML
        CLI --> Requirements
    end

    %% External Systems
    subgraph "External Systems"
        OS["OS & System Services"]:::external
        DockerEngine["Docker Engine"]:::external
        WazuhMgr["Wazuh Manager"]:::external
        WazuhIdx["Wazuh Indexer"]:::external
        WazuhDash["Wazuh Dashboard"]:::external
        SELKSStack["SELKS Stack"]:::external
        ServiceInfo --> OS
        HardwareInfo --> OS
        SELKSController --> DockerEngine
        AbstractService --> WazuhMgr
        AbstractService --> WazuhIdx
        AbstractService --> WazuhDash
        SELKSController --> SELKSStack
    end

    %% Click Events
    click CLI "https://github.com/flouksac/onesoc/blob/main/src/main.py"
    click Parser "https://github.com/flouksac/onesoc/blob/main/src/Controller/parser.py"
    click MainController "https://github.com/flouksac/onesoc/blob/main/src/Controller/main_controller.py"
    click AbstractController "https://github.com/flouksac/onesoc/blob/main/src/Controller/abstract_component_controller.py"
    click WazuhServer "https://github.com/flouksac/onesoc/blob/main/src/Controller/ControllerService/wazuh_server_controller.py"
    click WazuhIndexer "https://github.com/flouksac/onesoc/blob/main/src/Controller/ControllerService/wazuh_indexer_controller.py"
    click WazuhDashboard "https://github.com/flouksac/onesoc/blob/main/src/Controller/ControllerService/wazuh_dashboard_controller.py"
    click WazuhAgent "https://github.com/flouksac/onesoc/blob/main/src/Controller/ControllerService/wazuh_agent_controller.py"
    click AbstractService "https://github.com/flouksac/onesoc/blob/main/src/Controller/ControllerService/abstract_component_service_controller.py"
    click SELKSController "https://github.com/flouksac/onesoc/blob/main/src/Controller/ControllerDocker/selks_controller.py"
    click AbstractDocker "https://github.com/flouksac/onesoc/blob/main/src/Controller/ControllerDocker/abstract_component_docker_controller.py"
    click HostController "https://github.com/flouksac/onesoc/blob/main/src/Controller/host_controller.py"
    click ListController "https://github.com/flouksac/onesoc/blob/main/src/Controller/list_controller.py"
    click View "https://github.com/flouksac/onesoc/blob/main/src/View/main_view.py"
    click MainModel "https://github.com/flouksac/onesoc/blob/main/src/Model/main_model.py"
    click LoaderYAML "https://github.com/flouksac/onesoc/blob/main/src/Model/loaderYAML.py"
    click ActionObj "https://github.com/flouksac/onesoc/blob/main/src/Model/ModelObjects/action.py"
    click ComponentObj "https://github.com/flouksac/onesoc/blob/main/src/Model/ModelObjects/component.py"
    click OptionObj "https://github.com/flouksac/onesoc/blob/main/src/Model/ModelObjects/option.py"
    click PlatformObj "https://github.com/flouksac/onesoc/blob/main/src/Model/ModelObjects/platform.py"
    click HardwareInfo "https://github.com/flouksac/onesoc/blob/main/src/Utils/hardware_info.py"
    click OSInfo "https://github.com/flouksac/onesoc/blob/main/src/Utils/os_info.py"
    click ServiceInfo "https://github.com/flouksac/onesoc/blob/main/src/Utils/service_info.py"
    click singleton "https://github.com/flouksac/onesoc/blob/main/src/DesignPattern/singleton.py"
    click ConfigYAML "https://github.com/flouksac/onesoc/blob/main/config.yaml"
    click Requirements "https://github.com/flouksac/onesoc/blob/main/requirements.txt"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef external fill:#DFFFE0,stroke:#28a745,color:#28a745;
    classDef config fill:#FFF5B1,stroke:#D8A000,color:#D8A000;
```
