# ossincn/ossimagent architecture

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

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

## Overview

##### Project type and purpose
- This is the OSSIM Python “agent”:
- Exposes a Control API for remote management
- Runs inventory (LDAP, NMAP, Nagios, OCS, WMI) and monitoring (sniffer, log‐tailing, SDEE, WMI) tasks
- Parses/normalizes data, writes to a local DB, and pushes events to an OSSIM manager

##### File structure
- Top‐level scripts & modules:
- Agent.py / ossim-agent (main binary)
- Control*.py, Conn.py, Monitor*.py (Control & monitoring frameworks)
- InventoryTask_*.py, ControlInventory.py, ControlNmap.py… (task handlers)
- Parser*.py, Detector.py, Event*.py (data ingestion & normalization)
- Database.py, ParserDatabase.py (persistence layer)
- Output.py, MonitorHTTP.py, MonitorSocket.py (event forwarding)
- Utils, Logger, Profiler, Stats, Threshold, Watchdog (support libraries)

##### README for additional insights
- The README.control describes the Control API’s message format, commands (config_file_*, nmap_*), parameters, and response patterns.
- It confirms a request/response socket‐based protocol for remote management.

##### Main components and their interactions
a. Control Framework
- Conn.py / MonitorSocket.py: listens for incoming control requests
- Control.py: parses “control action=…” XML, dispatches to submodules
- Submodules (ControlInventory.py, ControlNmap.py, ControlSniffer.py, ControlVAScanner.py, ControlUtil.py) handle specific commands
- They spawn Task classes (InventoryTask_*, MonitorCommand.py) and stream back responses
b. Monitoring Framework
- MonitorScheduler.py: schedules periodic jobs (sniffer, log tailing, WMI polling…)
- MonitorSession.py: tracks session state for long‐running tasks
- TailFollow.py / TailFollowBookmark.py: incremental log reading
- PacketUtils.py / SessionParser.py: sniff & reassemble network sessions
c. Parsers & Detectors
- Parser*.py modules: parse Snort, FTP, JSON, SDEE, WMI, etc.
- ParserUtil.py: common parsing helpers
- Detector.py + Event/EventList.py + Threshold.py: apply detection rules and generate normalized Event objects
d. Data Layer
- Database.py: local event/inventory store (SQLite or MySQL)
- ParserDatabase.py: lookup tables for normalization (OS, service names, etc.)
e. Output & Networking
- Output.py: formats events for transmission
- MonitorHTTP.py / MonitorSocket.py: sends events to the OSSIM manager via HTTP or native socket

##### Architectural patterns & design principles
- Dispatcher pattern: Control.py → ControlXYZ modules
- Plugin architecture: each inventory/monitor/parser is self‐contained
- Producer/consumer & event‐driven: Scheduler → Parsers → Detector → Output
- Layered separation: API layer, orchestration/scheduler, processing/parsing, persistence, integration

##### Elements
- Clear labels on each component (e.g., “Control API”, “Monitor Scheduler”, “ParserSnort”)
- Solid for synchronous flows (control request → handler → response)
- Blue rectangles for API components
- Green for processing/parsing
- Purple clouds for external systems

##### Detail level
- Don’t lump everything into “agent.py.” Break out at minimum:
- Control API (Conn, Control, ControlXYZ)
- Scheduler & Tasks (MonitorScheduler, InventoryTask_*)
- Parsers & Detectors (Parser*, Detector, EventList)
- Database (Database, ParserDatabase)
- Output (Output, MonitorHTTP/Socket)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    Agent["Agent.py / ossim-agent"]:::entry

    %% API Layer
    subgraph "API Layer"
        Conn["Conn.py"]:::api
        Control["Control.py"]:::api
        MonSock["MonitorSocket.py"]:::api
    end

    %% Control Submodules
    subgraph "Control Handlers"
        CI["ControlInventory.py"]:::api
        CN["ControlNmap.py"]:::api
        CSn["ControlSniffer.py"]:::api
        CV["ControlVAScanner.py"]:::api
        CU["ControlUtil.py"]:::api
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        Scheduler["MonitorScheduler.py"]:::orchestration
        Session["MonitorSession.py"]:::orchestration
        MonCmd["MonitorCommand.py"]:::orchestration
        IT_LDAP["InventoryTask_LDAP.py"]:::orchestration
        IT_NMAP["InventoryTask_NMAP.py"]:::orchestration
        IT_NAG["InventoryTask_Nagios.py"]:::orchestration
        IT_OCS["InventoryTask_OCS.py"]:::orchestration
        IT_WMI["InventoryTask_WMI.py"]:::orchestration
    end

    %% Processing Layer
    subgraph "Processing Layer"
        PSn["ParserSnort.py"]:::processing
        PUSn["ParserUnifiedSnort.py"]:::processing
        PFSn["ParserFormattedSnort.py"]:::processing
        PFtp["ParserFtp.py"]:::processing
        PJson["ParserJson.py"]:::processing
        PLog["ParserLog.py"]:::processing
        PRem["ParserRemote.py"]:::processing
        PSDEE["ParserSDEE.py"]:::processing
        PWMI["ParserWMI.py"]:::processing
        PUtil["ParserUtil.py"]:::processing
        Detector["Detector.py"]:::processing
        Event["Event.py"]:::processing
        EList["EventList.py"]:::processing
        Thr["Threshold.py"]:::processing
        PktUtils["PacketUtils.py"]:::processing
        SessParse["SessionParser.py"]:::processing
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        DB["Database.py"]:::persistence
        PDB["ParserDatabase.py"]:::persistence
        MDB["MonitorDatabase.py"]:::persistence
    end

    %% Integration Layer
    subgraph "Integration Layer"
        Output["Output.py"]:::integration
        OutHTTP["MonitorHTTP.py"]:::integration
        OutSock["MonitorSocket.py"]:::integration
    end

    %% External Systems
    NmapBin["nmap (binary)"]:::external
    LDAPServ["LDAP servers"]:::external
    NagiosServ["Nagios servers"]:::external
    OCSServ["OCS servers"]:::external
    WMIHost["WMI hosts"]:::external
    OSSIMMgr["OSSIM Manager"]:::external

    %% Flows
    Agent -->|initializes| Conn
    Agent -->|initializes| MonSock
    Agent -->|initializes| Scheduler

    Conn -->|accepts XML| Control
    Control -->|dispatches| CI
    Control -->|dispatches| CN
    Control -->|dispatches| CSn
    Control -->|dispatches| CV
    Control -->|dispatches| CU

    CI -->|spawns| IT_LDAP
    CN -->|spawns| IT_NMAP
    CSn -->|spawns| MonCmd
    CV -->|spawns| MonCmd
    CU -->|spawns| MonCmd

    Scheduler -->|schedules jobs| Session
    Session -->|coordinates| MonCmd
    Session -->|spawns| IT_LDAP
    Session -->|spawns| IT_NMAP
    Session -->|spawns| IT_NAG
    Session -->|spawns| IT_OCS
    Session -->|spawns| IT_WMI

    IT_LDAP --->|pull data| LDAPServ
    IT_NMAP --->|invoke| NmapBin
    IT_NAG --->|pull data| NagiosServ
    IT_OCS --->|pull data| OCSServ
    IT_WMI --->|pull data| WMIHost

    MonCmd -->|produces raw| PSn & PUSn & PFSn & PFtp & PJson & PLog & PRem & PSDEE & PWMI & PUtil
    PSn & PUSn & PFSn & PFtp & PJson & PLog & PRem & PSDEE & PWMI & PUtil -->|normalize| Detector
    PktUtils & SessParse -->|assist| Detector
    Detector -->|generates| Event & EList
    EList -->|applies| Thr
    Detector -->|stores events| DB
    Detector -->|uses lookups| PDB

    Output -->|formats events| OutHTTP & OutSock
    OutHTTP & OutSock -->|forwards| OSSIMMgr
    OutHTTP -->|HTTP| OSSIMMgr
    OutSock -->|TCP| OSSIMMgr

    %% Click Events
    click Conn "https://github.com/ossincn/ossimagent/blob/main/Conn.py"
    click Control "https://github.com/ossincn/ossimagent/blob/main/Control.py"
    click MonSock "https://github.com/ossincn/ossimagent/blob/main/MonitorSocket.py"
    click CI "https://github.com/ossincn/ossimagent/blob/main/ControlInventory.py"
    click CN "https://github.com/ossincn/ossimagent/blob/main/ControlNmap.py"
    click CSn "https://github.com/ossincn/ossimagent/blob/main/ControlSniffer.py"
    click CV "https://github.com/ossincn/ossimagent/blob/main/ControlVAScanner.py"
    click CU "https://github.com/ossincn/ossimagent/blob/main/ControlUtil.py"
    click Scheduler "https://github.com/ossincn/ossimagent/blob/main/MonitorScheduler.py"
    click Session "https://github.com/ossincn/ossimagent/blob/main/MonitorSession.py"
    click MonCmd "https://github.com/ossincn/ossimagent/blob/main/MonitorCommand.py"
    click IT_LDAP "https://github.com/ossincn/ossimagent/blob/main/InventoryTask_LDAP.py"
    click IT_NMAP "https://github.com/ossincn/ossimagent/blob/main/InventoryTask_NMAP.py"
    click IT_NAG "https://github.com/ossincn/ossimagent/blob/main/InventoryTask_Nagios.py"
    click IT_OCS "https://github.com/ossincn/ossimagent/blob/main/InventoryTask_OCS.py"
    click IT_WMI "https://github.com/ossincn/ossimagent/blob/main/InventoryTask_WMI.py"
    click PSn "https://github.com/ossincn/ossimagent/blob/main/ParserSnort.py"
    click PUSn "https://github.com/ossincn/ossimagent/blob/main/ParserUnifiedSnort.py"
    click PFSn "https://github.com/ossincn/ossimagent/blob/main/ParserFormattedSnort.py"
    click PFtp "https://github.com/ossincn/ossimagent/blob/main/ParserFtp.py"
    click PJson "https://github.com/ossincn/ossimagent/blob/main/ParserJson.py"
    click PLog "https://github.com/ossincn/ossimagent/blob/main/ParserLog.py"
    click PRem "https://github.com/ossincn/ossimagent/blob/main/ParserRemote.py"
    click PSDEE "https://github.com/ossincn/ossimagent/blob/main/ParserSDEE.py"
    click PWMI "https://github.com/ossincn/ossimagent/blob/main/ParserWMI.py"
    click PUtil "https://github.com/ossincn/ossimagent/blob/main/ParserUtil.py"
    click Detector "https://github.com/ossincn/ossimagent/blob/main/Detector.py"
    click Event "https://github.com/ossincn/ossimagent/blob/main/Event.py"
    click EList "https://github.com/ossincn/ossimagent/blob/main/EventList.py"
    click Thr "https://github.com/ossincn/ossimagent/blob/main/Threshold.py"
    click PktUtils "https://github.com/ossincn/ossimagent/blob/main/PacketUtils.py"
    click SessParse "https://github.com/ossincn/ossimagent/blob/main/SessionParser.py"
    click DB "https://github.com/ossincn/ossimagent/blob/main/Database.py"
    click PDB "https://github.com/ossincn/ossimagent/blob/main/ParserDatabase.py"
    click MDB "https://github.com/ossincn/ossimagent/blob/main/MonitorDatabase.py"
    click Output "https://github.com/ossincn/ossimagent/blob/main/Output.py"
    click OutHTTP "https://github.com/ossincn/ossimagent/blob/main/MonitorHTTP.py"
    click OutSock "https://github.com/ossincn/ossimagent/blob/main/MonitorSocket.py"

    %% Styles
    classDef entry fill:#ffadad,stroke:#333,stroke-width:1px
    classDef api fill:#a0c4ff,stroke:#333,stroke-width:1px
    classDef orchestration fill:#fdffb6,stroke:#333,stroke-width:1px
    classDef processing fill:#caffbf,stroke:#333,stroke-width:1px
    classDef persistence fill:#ffd6a5,stroke:#333,stroke-width:1px
    classDef integration fill:#bdb2ff,stroke:#333,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
