How flouksac/onesoc works
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)