# ossincn/alienvaultossim54 architecture

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

- Interactive diagram: https://gitdiagram.com/ossincn/alienvaultossim54
- Repository: https://github.com/ossincn/alienvaultossim54

## Overview

##### Project type and purpose
- Os-sim is a security infrastructure monitoring and event-correlation engine written in C.
- It integrates multiple open-source security/network tools (Snort, Nessus, Nmap, Spade, Arpwatch, etc.), ingests their alerts/logs, qualifies and correlates events, stores them, and exposes them for reporting/viewing.

##### File structure
- Top-level C source and headers (main.c, libos-sim.h, os-sim.h) implement the core daemon.
- sim-*.c / sim-*.h modules:
- sim-config: configuration parsing
- sim-connect: network/file input connectors
- sim-database, sim-db-command, sim-db-insert: storage abstraction for MySQL/PostgreSQL
- sim-correlation: event correlation engine
- sim-alarm-stats: alarm aggregation and statistics
- sim-command: runtime command dispatch/CLI
- sim-context: runtime context management
- sim-container: module container/registry
- sim-debug: debug/tracing utilities
- plugin_sid: plugin definitions for mapping external tool signatures to internal schema.
- Build / config files (autogen.sh, configure.ac, Makefile.*) indicate a GNU autotools build.

##### Key insights from the README
- Core goal: ingest, qualify, correlate low-level (logs/alerts), mid-level (risk), high-level (decision support) events.
- Integrates a diverse set of external services and storage backends.
- Multi-language surrounding ecosystem (Perl, PHP, Python, Java front-ends), but core is in C.
- Relies on relational DBs (MySQL/Postgres) and rrdtool for time-series.

a. Main components:
1. External Data Sources
- Snort, Spade, Nessus, Nmap, P0f, Arpwatch, OpenNMS, MRTG, etc.
2. Os-sim Core Daemon
- Connector modules (sim-connect)
- Configuration manager (sim-config)
- Plugin registry (sim-container, plugin_sid)
- Correlation engine (sim-correlation)
- Alarm statistics (sim-alarm-stats)
- Command/CLI interface (sim-command)
- Debug/logging (sim-debug)
3. Storage Layer
- Relational DB (MySQL, PostgreSQL via sim-database)
- Time-series RRD (rrdtool)
4. Visualization/Reporting
- Acid (PHP log viewer)
- OpenNMS UI
- MRTG graphs
- Custom dashboards (Perl/Python/Java)

b. Relationships and data flows:
1. External tools feed event logs/alerts → sim-connect
2. sim-config loads rules/schema → passed to plugin modules
3. sim-connect normalizes inputs → hands off to sim-context
4. sim-correlation matches events against correlation rules → generates alarms
5. sim-db-insert persists raw events and correlated alerts → DB backends
6. sim-alarm-stats aggregates alarms → RRD time-series
7. Visualization tools query DB / RRD → present to users
8. sim-command provides runtime inspection/control (e.g., via CLI or IPC)

c. Architectural patterns and principles:
- Modular, plugin-based architecture (sim-container, plugin_sid) for extensibility.
- Separation of concerns: connectors, config, correlation, storage, reporting.
- Multithreaded or event‐loop design in core C daemon (implied by sim-context, sim-container).

d. Key technologies/frameworks:
- C language, GNU autotools (autogen.sh, configure.ac, Makefiles)
- MySQL/PostgreSQL (via libmysqlclient/libpq)
- rrdtool library
- External security tools (Snort, Nessus, Nmap, Spade, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        SNORT["Snort"]:::external
        NESSUS["Nessus"]:::external
        NMAP["Nmap"]:::external
        ARPW["Arpwatch"]:::external
        OPENNMS_EXT["OpenNMS"]:::external
        MRTG_EXT["MRTG"]:::external
    end

    %% Core Processing Layer
    subgraph "Os-sim Core"
        Core["Core Daemon"]:::coreModule
        Config["sim-config"]:::coreModule
        Connect["sim-connect"]:::coreModule
        Context["sim-context"]:::coreModule
        Container["sim-container & plugin_sid"]:::plugin
        Correl["sim-correlation"]:::coreModule
        AlarmStat["sim-alarm-stats"]:::coreModule
        Command["sim-command"]:::coreModule
        Debug["sim-debug"]:::coreModule
    end

    %% Storage Layer
    subgraph "Storage Layer"
        RelDB["MySQL/PostgreSQL"]:::storage
        RRD["RRDTool"]:::storage
    end

    %% Visualization/Reporting Layer
    subgraph "Visualization"
        ACID["ACID (PHP Log Viewer)"]:::output
        ONMS["OpenNMS UI"]:::output
        MRTG["MRTG Graphs"]:::output
        DASH["Custom Dashboards"]:::output
    end

    %% Data Flows
    SNORT -->|"alerts/logs"| Connect
    NESSUS -->|alerts/logs| Connect
    NMAP -->|scan results| Connect
    ARPW -->|alerts/logs| Connect
    OPENNMS_EXT -->|metrics| Connect
    MRTG_EXT -->|graphs| Connect

    Connect -->|"normalized events"| Context
    Config -->|"loads rules/schema"| Container
    Container -->|"provides plugins to"| Core
    Context -->|"runtime context"| Core

    Core -->|dispatch to| Connect
    Core -->|uses| Config
    Core -->|manages| Container
    Core -->|processes| Context
    Core -->|runs| Correl
    Core -->|runs| AlarmStat
    Core -->|executes| Command
    Core -->|logs via| Debug

    Correl -->|"correlated alerts"| RelDB
    Correl -->|"alerts"| AlarmStat
    AlarmStat -->|"time-series data"| RRD

    RelDB -->|"query"| ACID
    RelDB -->|"query"| ONMS
    RRD -->|"data"| MRTG
    RRD -->|"data"| DASH
    Command -->|"CLI/control"| Core

    %% Click Events
    click Core "https://github.com/ossincn/alienvaultossim54/blob/main/main.c"
    click Core "https://github.com/ossincn/alienvaultossim54/blob/main/libos-sim.h"
    click Core "https://github.com/ossincn/alienvaultossim54/blob/main/os-sim.h"
    click Config "https://github.com/ossincn/alienvaultossim54/blob/main/sim-config.c"
    click Config "https://github.com/ossincn/alienvaultossim54/blob/main/sim-config.h"
    click Connect "https://github.com/ossincn/alienvaultossim54/blob/main/sim-connect.c"
    click Connect "https://github.com/ossincn/alienvaultossim54/blob/main/sim-connect.h"
    click Container "https://github.com/ossincn/alienvaultossim54/blob/main/sim-container.c"
    click Container "https://github.com/ossincn/alienvaultossim54/blob/main/sim-container.h"
    click Container "https://github.com/ossincn/alienvaultossim54/tree/main/plugin_sid/"
    click Correl "https://github.com/ossincn/alienvaultossim54/blob/main/sim-correlation.c"
    click Correl "https://github.com/ossincn/alienvaultossim54/blob/main/sim-correlation.h"
    click AlarmStat "https://github.com/ossincn/alienvaultossim54/blob/main/sim-alarm-stats.c"
    click AlarmStat "https://github.com/ossincn/alienvaultossim54/blob/main/sim-alarm-stats.h"
    click Command "https://github.com/ossincn/alienvaultossim54/blob/main/sim-command.c"
    click Command "https://github.com/ossincn/alienvaultossim54/blob/main/sim-command.h"
    click Context "https://github.com/ossincn/alienvaultossim54/blob/main/sim-context.c"
    click Context "https://github.com/ossincn/alienvaultossim54/blob/main/sim-context.h"
    click Debug "https://github.com/ossincn/alienvaultossim54/blob/main/sim-debug.c"
    click Debug "https://github.com/ossincn/alienvaultossim54/blob/main/sim-debug.h"
    click RelDB "https://github.com/ossincn/alienvaultossim54/blob/main/sim-database.c"
    click RelDB "https://github.com/ossincn/alienvaultossim54/blob/main/sim-database.h"
    click RelDB "https://github.com/ossincn/alienvaultossim54/blob/main/sim-db-command.c"
    click RelDB "https://github.com/ossincn/alienvaultossim54/blob/main/sim-db-command.h"
    click RelDB "https://github.com/ossincn/alienvaultossim54/blob/main/sim-db-insert.c"
    click RelDB "https://github.com/ossincn/alienvaultossim54/blob/main/sim-db-insert.h"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef coreModule fill:#bbf,stroke:#333,stroke-width:1px
    classDef plugin fill:#dfd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef storage fill:#bfb,stroke:#333,stroke-width:1px
    classDef output fill:#ffb,stroke:#333,stroke-width:1px
```
